observability

Documentation

Overview

Package observability provides vendor-agnostic observability for CoreForge applications. It wraps omniobserve/observops to provide metrics, traces, and logs with support for OTLP, Datadog, New Relic, and Dynatrace backends.

Index

• Constants
• type Config
  • func ConfigFromEnv() Config
• type Observability
  • func MustNew(cfg Config) *Observability
  • func New(cfg Config) (*Observability, error)
  • func (o *Observability) Config() Config
  • func (o *Observability) ForceFlush(ctx context.Context) error
  • func (o *Observability) IsEnabled() bool
  • func (o *Observability) Logger() observops.Logger
  • func (o *Observability) Meter() observops.Meter
  • func (o *Observability) Middleware() func(http.Handler) http.Handler
  • func (o *Observability) Provider() observops.Provider
  • func (o *Observability) RecordAPIKeyValidation(ctx context.Context, result string)
  • func (o *Observability) RecordAuthLatency(ctx context.Context, grantType, endpoint string, latencyMs float64)
  • func (o *Observability) RecordAuthRequest(ctx context.Context, grantType, clientID, status string)
  • func (o *Observability) RecordJWTLatency(ctx context.Context, latencyMs float64)
  • func (o *Observability) RecordJWTValidation(ctx context.Context, result string)
  • func (o *Observability) RecordRateLimitRequest(ctx context.Context, policyID, clientID string, allowed bool)
  • func (o *Observability) RecordRateLimitUsage(ctx context.Context, policyID, clientID, window string, usage float64)
  • func (o *Observability) RecordSessionsActive(ctx context.Context, count int)
  • func (o *Observability) RecordTokenIssued(ctx context.Context, grantType, clientID string)
  • func (o *Observability) RecordTokenValidation(ctx context.Context, result string)
  • func (o *Observability) Shutdown(ctx context.Context) error
  • func (o *Observability) SlogHandler(opts ...observops.SlogOption) slog.Handler
  • func (o *Observability) SpanFromContext(ctx context.Context) observops.Span
  • func (o *Observability) StartSpan(ctx context.Context, name string, opts ...observops.SpanOption) (context.Context, observops.Span)
  • func (o *Observability) Tracer() observops.Tracer

Constants

const (
	// MetricPrefix is the prefix for all CoreForge metrics.
	MetricPrefix = "coreforge."

	// MetricAuthRequests counts total authentication/authorization requests.
	// Labels: grant_type, client_id, status
	MetricAuthRequests = MetricPrefix + "coreauth.auth_requests_total"

	// MetricAuthLatency records authentication latency in milliseconds.
	// Labels: grant_type, endpoint
	MetricAuthLatency = MetricPrefix + "coreauth.auth_latency_ms"

	// MetricTokensIssued counts total tokens issued.
	// Labels: grant_type, client_id
	MetricTokensIssued = MetricPrefix + "coreauth.tokens_issued_total"

	// MetricTokenValidations counts total token validations.
	// Labels: result (valid, invalid, expired)
	MetricTokenValidations = MetricPrefix + "coreauth.token_validations_total"

	// MetricSessionsActive records currently active sessions.
	MetricSessionsActive = MetricPrefix + "coreauth.sessions_active"

	// MetricRateLimitRequests counts rate limit checks.
	// Labels: policy_id, client_id, allowed
	MetricRateLimitRequests = MetricPrefix + "coreapi.ratelimit_requests_total"

	// MetricRateLimitUsage records current quota usage ratio.
	// Labels: policy_id, client_id, window
	MetricRateLimitUsage = MetricPrefix + "coreapi.ratelimit_quota_usage"

	// MetricJWTValidations counts JWT validations.
	// Labels: result (valid, invalid, expired, missing)
	MetricJWTValidations = MetricPrefix + "session.jwt_validations_total"

	// MetricJWTLatency records JWT validation latency in milliseconds.
	MetricJWTLatency = MetricPrefix + "session.jwt_validation_latency_ms"

	// MetricAPIKeyValidations counts API key validations.
	// Labels: result (valid, invalid, expired, revoked)
	MetricAPIKeyValidations = MetricPrefix + "session.apikey_validations_total"
)

Metric name constants following OpenTelemetry semantic conventions. All metrics are prefixed with "coreforge." for namespacing.

const (
	// SpanPrefix is the prefix for all CoreForge spans.
	SpanPrefix = "coreforge."

	// SpanAuthorize is the span for the authorization endpoint.
	SpanAuthorize = SpanPrefix + "coreauth.authorize"

	// SpanToken is the span for the token endpoint.
	SpanToken = SpanPrefix + "coreauth.token"

	// SpanIntrospect is the span for token introspection.
	SpanIntrospect = SpanPrefix + "coreauth.introspect"

	// SpanRevoke is the span for token revocation.
	SpanRevoke = SpanPrefix + "coreauth.revoke"

	// SpanHTTPRequest is the span for HTTP requests.
	SpanHTTPRequest = SpanPrefix + "http.request"

	// SpanJWTValidation is the span for JWT validation.
	SpanJWTValidation = SpanPrefix + "session.jwt_validation"

	// SpanAPIKeyValidation is the span for API key validation.
	SpanAPIKeyValidation = SpanPrefix + "session.apikey_validation"

	// SpanRateLimitCheck is the span for rate limit checks.
	SpanRateLimitCheck = SpanPrefix + "ratelimit.check"
)

Span name constants for tracing.

const (
	ResultValid   = "valid"
	ResultInvalid = "invalid"
	ResultExpired = "expired"
	ResultMissing = "missing"
	ResultRevoked = "revoked"
	ResultDenied  = "denied"
	ResultError   = "error"
)

Validation result constants for metric labels.

const (
	StatusSuccess = "success"
	StatusError   = "error"
	StatusDenied  = "denied"
)

Status constants for metric labels.

Types

type Config

type Config struct {
	// Provider is the backend provider name: "otlp", "datadog", "newrelic", "dynatrace".
	// If empty, observability is disabled (noop provider).
	Provider string

	// ServiceName is the name of the service.
	ServiceName string

	// ServiceVersion is the version of the service.
	ServiceVersion string

	// Endpoint is the backend endpoint (e.g., "localhost:4317" for OTLP).
	Endpoint string

	// APIKey is the API key for authentication (required for some backends).
	APIKey string

	// Disabled explicitly disables observability.
	Disabled bool

	// Insecure disables TLS for the connection.
	Insecure bool

	// Debug enables debug logging for the provider.
	Debug bool
}

Config holds observability configuration.

func ConfigFromEnv

func ConfigFromEnv() Config

ConfigFromEnv creates a Config from environment variables.

Environment variables:

• OBSERVABILITY_PROVIDER: otlp, datadog, newrelic, dynatrace
• OBSERVABILITY_ENDPOINT: Backend endpoint
• OBSERVABILITY_API_KEY: API key for authentication
• OBSERVABILITY_SERVICE_NAME: Service name
• OBSERVABILITY_SERVICE_VERSION: Service version
• OBSERVABILITY_DISABLED: true/false
• OBSERVABILITY_INSECURE: true/false
• OBSERVABILITY_DEBUG: true/false

type Observability

type Observability struct {
	// contains filtered or unexported fields
}

Observability wraps an observops.Provider with CoreForge-specific helpers.

func MustNew

func MustNew(cfg Config) *Observability

MustNew is like New but panics on error.

func New

func New(cfg Config) (*Observability, error)

New creates a new Observability instance from the given config. If the provider is empty or disabled, a noop provider is used.

func (*Observability) Config

func (o *Observability) Config() Config

Config returns the observability configuration.

func (*Observability) ForceFlush

func (o *Observability) ForceFlush(ctx context.Context) error

ForceFlush forces any buffered telemetry to be exported.

func (*Observability) IsEnabled

func (o *Observability) IsEnabled() bool

IsEnabled returns true if observability is enabled.

func (*Observability) Logger

func (o *Observability) Logger() observops.Logger

Logger returns the structured logger.

func (*Observability) Meter

func (o *Observability) Meter() observops.Meter

Meter returns the metrics meter.

func (*Observability) Middleware

func (o *Observability) Middleware() func(http.Handler) http.Handler

Middleware creates HTTP middleware that traces requests and records metrics. It starts a span for each request and records method, path, status_code, and duration.

func (*Observability) Provider

func (o *Observability) Provider() observops.Provider

Provider returns the underlying observops.Provider.

func (*Observability) RecordAPIKeyValidation

func (o *Observability) RecordAPIKeyValidation(ctx context.Context, result string)

RecordAPIKeyValidation records an API key validation result.

func (*Observability) RecordAuthLatency

func (o *Observability) RecordAuthLatency(ctx context.Context, grantType, endpoint string, latencyMs float64)

RecordAuthLatency records authentication latency in milliseconds.

func (*Observability) RecordAuthRequest

func (o *Observability) RecordAuthRequest(ctx context.Context, grantType, clientID, status string)

RecordAuthRequest records an authentication/authorization request metric.

func (*Observability) RecordJWTLatency

func (o *Observability) RecordJWTLatency(ctx context.Context, latencyMs float64)

RecordJWTLatency records JWT validation latency in milliseconds.

func (*Observability) RecordJWTValidation

func (o *Observability) RecordJWTValidation(ctx context.Context, result string)

RecordJWTValidation records a JWT validation result.

func (*Observability) RecordRateLimitRequest

func (o *Observability) RecordRateLimitRequest(ctx context.Context, policyID, clientID string, allowed bool)

RecordRateLimitRequest records a rate limit check.

func (*Observability) RecordRateLimitUsage

func (o *Observability) RecordRateLimitUsage(ctx context.Context, policyID, clientID, window string, usage float64)

RecordRateLimitUsage records the current rate limit usage ratio (0.0 to 1.0).

func (*Observability) RecordSessionsActive

func (o *Observability) RecordSessionsActive(ctx context.Context, count int)

RecordSessionsActive records the current number of active sessions.

func (*Observability) RecordTokenIssued

func (o *Observability) RecordTokenIssued(ctx context.Context, grantType, clientID string)

RecordTokenIssued records a token issuance.

func (*Observability) RecordTokenValidation

func (o *Observability) RecordTokenValidation(ctx context.Context, result string)

RecordTokenValidation records a token validation result.

func (*Observability) Shutdown

func (o *Observability) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the provider.

func (*Observability) SlogHandler

func (o *Observability) SlogHandler(opts ...observops.SlogOption) slog.Handler

SlogHandler returns an slog.Handler that integrates with this provider. Options can be used to configure local output and filtering.

func (*Observability) SpanFromContext

func (o *Observability) SpanFromContext(ctx context.Context) observops.Span

SpanFromContext retrieves the current span from context.

func (*Observability) StartSpan

func (o *Observability) StartSpan(ctx context.Context, name string, opts ...observops.SpanOption) (context.Context, observops.Span)

StartSpan creates a new span with the given name.

func (*Observability) Tracer

func (o *Observability) Tracer() observops.Tracer

Tracer returns the tracer for creating spans.