Documentation
¶
Overview ¶
Package observability provides vendor-agnostic observability for SystemForge applications. It wraps omniobserve/observops to provide metrics, traces, and logs with support for OTLP, Datadog, New Relic, and Dynatrace backends.
Index ¶
- Constants
- func ProductGraphCorrelationMiddleware() func(http.Handler) http.Handler
- type Config
- type Observability
- 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) ProductGraphClient() *productgraph.Client
- func (o *Observability) ProductGraphEnabled() bool
- func (o *Observability) ProductGraphMiddleware() func(http.Handler) http.Handler
- func (o *Observability) ProductGraphRequestTrackerMiddleware() 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) SetProductGraph(cfg productgraph.Config) error
- func (o *Observability) SetProductGraphFromEnv() error
- 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
- func (o *Observability) TrackAPICall(ctx context.Context, method, path string, statusCode int, ...)
- func (o *Observability) TrackError(ctx context.Context, errType, message string)
- func (o *Observability) TrackJourneyStep(ctx context.Context, journeyID, stepID, stepName string)
- func (o *Observability) TrackProductGraphEvent(ctx context.Context, event productgraph.Event)
- type ProductGraphConfig
Constants ¶
const ( // MetricPrefix is the prefix for all SystemForge metrics. MetricPrefix = "systemforge." // MetricAuthRequests counts total authentication/authorization requests. // Labels: grant_type, client_id, status MetricAuthRequests = MetricPrefix + "systemauth.auth_requests_total" // MetricAuthLatency records authentication latency in milliseconds. // Labels: grant_type, endpoint MetricAuthLatency = MetricPrefix + "systemauth.auth_latency_ms" // MetricTokensIssued counts total tokens issued. // Labels: grant_type, client_id MetricTokensIssued = MetricPrefix + "systemauth.tokens_issued_total" // MetricTokenValidations counts total token validations. // Labels: result (valid, invalid, expired) MetricTokenValidations = MetricPrefix + "systemauth.token_validations_total" // MetricSessionsActive records currently active sessions. MetricSessionsActive = MetricPrefix + "systemauth.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 "systemforge." for namespacing.
const ( // SpanPrefix is the prefix for all SystemForge spans. SpanPrefix = "systemforge." // SpanAuthorize is the span for the authorization endpoint. SpanAuthorize = SpanPrefix + "systemauth.authorize" // SpanToken is the span for the token endpoint. SpanToken = SpanPrefix + "systemauth.token" // SpanIntrospect is the span for token introspection. SpanIntrospect = SpanPrefix + "systemauth.introspect" // SpanRevoke is the span for token revocation. SpanRevoke = SpanPrefix + "systemauth.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.
Variables ¶
This section is empty.
Functions ¶
func ProductGraphCorrelationMiddleware ¶
ProductGraphCorrelationMiddleware returns middleware that extracts correlation headers (X-Session-ID, X-Request-ID, X-User-ID) from requests. This should be used early in the middleware chain.
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 SystemForge-specific helpers.
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) ProductGraphClient ¶
func (o *Observability) ProductGraphClient() *productgraph.Client
ProductGraphClient returns the ProductGraph client if configured. Returns nil if ProductGraph is not enabled.
func (*Observability) ProductGraphEnabled ¶
func (o *Observability) ProductGraphEnabled() bool
ProductGraphEnabled returns true if ProductGraph integration is enabled.
func (*Observability) ProductGraphMiddleware ¶
func (o *Observability) ProductGraphMiddleware() func(http.Handler) http.Handler
ProductGraphMiddleware returns a combined middleware that handles both correlation extraction and request tracking. This is the recommended middleware for most use cases.
func (*Observability) ProductGraphRequestTrackerMiddleware ¶
func (o *Observability) ProductGraphRequestTrackerMiddleware() func(http.Handler) http.Handler
ProductGraphRequestTrackerMiddleware returns middleware that tracks HTTP requests to ProductGraph. Requires ProductGraph to be configured.
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) SetProductGraph ¶
func (o *Observability) SetProductGraph(cfg productgraph.Config) error
SetProductGraph configures ProductGraph integration. This should be called after New() if you want to enable ProductGraph. Returns an error if the configuration is invalid.
func (*Observability) SetProductGraphFromEnv ¶
func (o *Observability) SetProductGraphFromEnv() error
SetProductGraphFromEnv configures ProductGraph from environment variables. Environment variables:
- PRODUCTGRAPH_PROJECT_ID: Project identifier
- PRODUCTGRAPH_ENDPOINT: API endpoint
- PRODUCTGRAPH_API_KEY: API key (optional)
- PRODUCTGRAPH_BATCH_SIZE: Events per batch (default: 50)
- PRODUCTGRAPH_BATCH_INTERVAL: Flush interval in seconds (default: 5)
- PRODUCTGRAPH_DEBUG: Enable debug logging
func (*Observability) Shutdown ¶
func (o *Observability) Shutdown(ctx context.Context) error
Shutdown gracefully shuts down the provider and ProductGraph client.
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.
func (*Observability) TrackAPICall ¶
func (o *Observability) TrackAPICall(ctx context.Context, method, path string, statusCode int, duration time.Duration)
TrackAPICall tracks an API call to ProductGraph. No-op if ProductGraph is not configured.
func (*Observability) TrackError ¶
func (o *Observability) TrackError(ctx context.Context, errType, message string)
TrackError tracks an error to ProductGraph. No-op if ProductGraph is not configured.
func (*Observability) TrackJourneyStep ¶
func (o *Observability) TrackJourneyStep(ctx context.Context, journeyID, stepID, stepName string)
TrackJourneyStep tracks a journey step to ProductGraph. No-op if ProductGraph is not configured.
func (*Observability) TrackProductGraphEvent ¶
func (o *Observability) TrackProductGraphEvent(ctx context.Context, event productgraph.Event)
TrackProductGraphEvent sends an event to ProductGraph. No-op if ProductGraph is not configured.
type ProductGraphConfig ¶
type ProductGraphConfig = productgraph.Config
ProductGraphConfig holds ProductGraph-specific configuration. Use productgraph.ConfigFromEnv() to load from environment variables.
Source Files