Help us shape the future of Go! Take the 2026 Go Developer Survey

observability

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source 
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.

View Source 
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.

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

Validation result constants for metric labels.

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

Status constants for metric labels.

View Source 
const RouteUnmatched = "unmatched"

RouteUnmatched is the http.route value recorded for a request that no route pattern matched.

Variables

This section is empty.

Functions

func ProductGraphCorrelationMiddleware 

func ProductGraphCorrelationMiddleware() func(http.Handler) http.Handler

ProductGraphCorrelationMiddleware returns middleware that extracts correlation headers (X-Session-ID, X-Request-ID) from requests. It does not read a user ID from the request; set it from the authenticated session with productgraph.WithUserID. 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 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, route, status_code, and duration.

The request URL is not recorded: its query string can carry OAuth authorization codes, state, API keys and other secrets, and its path can carry tokens such as invite tokens. The route is the matched pattern (http.ServeMux's Request.Pattern or chi's route pattern), or RouteUnmatched, which also keeps metric label cardinality bounded.

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.