observability

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package observability provides service observability interfaces, real implementations, library adapter types, centralized error mapping, and correlation ID management. It does not own component construction or dependency injection — those belong to main.go. Primary dependencies: log/slog, go.opentelemetry.io/otel, github.com/prometheus/client_golang, and github.com/aetomala/jwtauth/pkg/tracing and pkg/logging for compile-time adapter assertions.

Index

Constants

View Source 
const (
	MetadataKeyCorrelationID  = "x-correlation-id"
	MetadataKeyAPIKey         = "x-api-key"
	MetadataKeyIdempotencyKey = "x-idempotency-key"
)

gRPC metadata key constants used for correlation, auth, and idempotency.

View Source 
const (
	MetricGRPCRequests     = "token_engine_grpc_requests_total"
	MetricGRPCDuration     = "token_engine_grpc_request_duration_seconds"
	MetricIdempotencyTotal = "token_engine_idempotency_total"
	MetricActiveTenants    = "token_engine_active_tenants"
	MetricRegistryOps      = "token_engine_tenant_registry_operations_total"
	MetricJWKSKeyCount     = "token_engine_jwks_key_count"
)

Prometheus metric name constants for all service instrumentation.

Variables

This section is empty.

Functions

func CallerIdentityFromContext 

func CallerIdentityFromContext(ctx context.Context) string

CallerIdentityFromContext extracts the caller identity from the context.

func CorrelationIDFromContext 

func CorrelationIDFromContext(ctx context.Context) string

CorrelationIDFromContext extracts the correlation ID from the context.

func MapLibraryError 

func MapLibraryError(err error) error

MapLibraryError converts library error sentinels to gRPC status errors.

func NewCorrelationInterceptor 

func NewCorrelationInterceptor(logger Logger, metrics Metrics) grpc.UnaryServerInterceptor

NewCorrelationInterceptor creates a gRPC unary server interceptor that manages correlation IDs and emits per-RPC request count and duration metrics.

func WithCallerIdentity 

func WithCallerIdentity(ctx context.Context, identity string) context.Context

WithCallerIdentity adds a caller identity to the context.

func WithCorrelationID 

func WithCorrelationID(ctx context.Context, id string) context.Context

WithCorrelationID adds a correlation ID to the context.

Types

type CallerIdentityKey 

type CallerIdentityKey struct{}

CallerIdentityKey is the context key for caller identities.

type CorrelationIDKey 

type CorrelationIDKey struct{}

CorrelationIDKey is the context key for correlation IDs.

type LibraryLoggerAdapter 

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

LibraryLoggerAdapter wraps the service Logger and implements the library logging.Logger interface.

func NewLibraryLoggerAdapter 

func NewLibraryLoggerAdapter(logger Logger) *LibraryLoggerAdapter

NewLibraryLoggerAdapter creates a new LibraryLoggerAdapter wrapping the given service Logger.

func (*LibraryLoggerAdapter) Debug 

func (a *LibraryLoggerAdapter) Debug(msg string, keysAndValues ...interface{})

Debug logs a debug-level message using context.Background().

func (*LibraryLoggerAdapter) Error 

func (a *LibraryLoggerAdapter) Error(msg string, keysAndValues ...interface{})

Error logs an error-level message using context.Background().

func (*LibraryLoggerAdapter) Info 

func (a *LibraryLoggerAdapter) Info(msg string, keysAndValues ...interface{})

Info logs an info-level message using context.Background().

func (*LibraryLoggerAdapter) Warn 

func (a *LibraryLoggerAdapter) Warn(msg string, keysAndValues ...interface{})

Warn logs a warn-level message using context.Background().

func (*LibraryLoggerAdapter) With 

func (a *LibraryLoggerAdapter) With(keysAndValues ...interface{}) logging.Logger

With returns a new LibraryLoggerAdapter wrapping the logger with additional fields bound.

type LibraryOtelSpan 

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

LibraryOtelSpan wraps an OpenTelemetry span and implements the library tracing.Span interface.

func (*LibraryOtelSpan) End 

func (s *LibraryOtelSpan) End()

End ends the span.

func (*LibraryOtelSpan) RecordError 

func (s *LibraryOtelSpan) RecordError(err error)

RecordError records an error on the span.

func (*LibraryOtelSpan) SetAttribute 

func (s *LibraryOtelSpan) SetAttribute(key string, value interface{})

SetAttribute sets a single attribute on the span, converting non-string values using Sprintf.

func (*LibraryOtelSpan) SetAttributes 

func (s *LibraryOtelSpan) SetAttributes(attrs map[string]interface{})

SetAttributes sets multiple attributes on the span, converting non-string values using Sprintf.

func (*LibraryOtelSpan) SetStatus 

func (s *LibraryOtelSpan) SetStatus(code tracing.StatusCode, description string)

SetStatus sets the status of the span, mapping library StatusCode to OTel codes.

type LibraryOtelTracer 

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

LibraryOtelTracer wraps the OpenTelemetry trace.Tracer and implements the library tracing.Tracer interface.

func NewLibraryOtelTracer 

func NewLibraryOtelTracer(tracer oteltrace.Tracer) *LibraryOtelTracer

NewLibraryOtelTracer creates a new LibraryOtelTracer wrapping the given OpenTelemetry tracer.

func (*LibraryOtelTracer) Start 

func (t *LibraryOtelTracer) Start(ctx context.Context, name string) (context.Context, tracing.Span)

Start creates a new span with SpanKindInternal and returns it wrapped in LibraryOtelSpan.

type LibraryPrometheusMetrics added in v0.2.0 

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

LibraryPrometheusMetrics adapts the service's Metrics to satisfy the library's metrics.Metrics interface. NOT injected into tokens.Manager in v0.2 — the Manager receives the library's own librarymetrics.NewPrometheusMetrics so its 18 pre-registered metrics land on the shared registry. This type is defined here as a future seam only.

func NewLibraryPrometheusMetrics added in v0.2.0 

func NewLibraryPrometheusMetrics(inner Metrics) *LibraryPrometheusMetrics

NewLibraryPrometheusMetrics returns a LibraryPrometheusMetrics delegating all calls to inner. Inner must not be nil.

func (*LibraryPrometheusMetrics) AddCounter added in v0.2.0 

func (a *LibraryPrometheusMetrics) AddCounter(name string, value float64, labels map[string]string)

AddCounter delegates to inner.

func (*LibraryPrometheusMetrics) IncrementCounter added in v0.2.0 

func (a *LibraryPrometheusMetrics) IncrementCounter(name string, labels map[string]string)

IncrementCounter delegates to inner.

func (*LibraryPrometheusMetrics) RecordDuration added in v0.2.0 

func (a *LibraryPrometheusMetrics) RecordDuration(name string, d time.Duration, labels map[string]string)

RecordDuration delegates to inner.

func (*LibraryPrometheusMetrics) RecordHistogram added in v0.2.0 

func (a *LibraryPrometheusMetrics) RecordHistogram(name string, value float64, labels map[string]string)

RecordHistogram delegates to inner.

func (*LibraryPrometheusMetrics) SetGauge added in v0.2.0 

func (a *LibraryPrometheusMetrics) SetGauge(name string, value float64, labels map[string]string)

SetGauge delegates to inner.

type Logger 

type Logger interface {
	Debug(ctx context.Context, msg string, keysAndValues ...interface{})
	Info(ctx context.Context, msg string, keysAndValues ...interface{})
	Warn(ctx context.Context, msg string, keysAndValues ...interface{})
	Error(ctx context.Context, msg string, keysAndValues ...interface{})
	With(keysAndValues ...interface{}) Logger
}

Logger is the service's logging interface.

type Metrics 

type Metrics interface {
	IncrementCounter(name string, labels map[string]string)
	AddCounter(name string, value float64, labels map[string]string)
	SetGauge(name string, value float64, labels map[string]string)
	RecordHistogram(name string, value float64, labels map[string]string)
	RecordDuration(name string, d time.Duration, labels map[string]string)
}

Metrics is the service's metrics recording interface.

type NoOpLogger 

type NoOpLogger struct{}

NoOpLogger is a no-op implementation of the Logger interface.

func NewNoOpLogger 

func NewNoOpLogger() *NoOpLogger

NewNoOpLogger creates a new NoOpLogger.

func (*NoOpLogger) Debug 

func (n *NoOpLogger) Debug(ctx context.Context, msg string, keysAndValues ...interface{})

Debug does nothing.

func (*NoOpLogger) Error 

func (n *NoOpLogger) Error(ctx context.Context, msg string, keysAndValues ...interface{})

Error does nothing.

func (*NoOpLogger) Info 

func (n *NoOpLogger) Info(ctx context.Context, msg string, keysAndValues ...interface{})

Info does nothing.

func (*NoOpLogger) Warn 

func (n *NoOpLogger) Warn(ctx context.Context, msg string, keysAndValues ...interface{})

Warn does nothing.

func (*NoOpLogger) With 

func (n *NoOpLogger) With(keysAndValues ...interface{}) Logger

With returns the receiver.

type NoOpMetrics 

type NoOpMetrics struct{}

NoOpMetrics is a no-op implementation of the Metrics interface.

func NewNoOpMetrics 

func NewNoOpMetrics() *NoOpMetrics

NewNoOpMetrics creates a new NoOpMetrics.

func (*NoOpMetrics) AddCounter 

func (n *NoOpMetrics) AddCounter(name string, value float64, labels map[string]string)

AddCounter does nothing.

func (*NoOpMetrics) IncrementCounter 

func (n *NoOpMetrics) IncrementCounter(name string, labels map[string]string)

IncrementCounter does nothing.

func (*NoOpMetrics) RecordDuration 

func (n *NoOpMetrics) RecordDuration(name string, d time.Duration, labels map[string]string)

RecordDuration does nothing.

func (*NoOpMetrics) RecordHistogram 

func (n *NoOpMetrics) RecordHistogram(name string, value float64, labels map[string]string)

RecordHistogram does nothing.

func (*NoOpMetrics) SetGauge 

func (n *NoOpMetrics) SetGauge(name string, value float64, labels map[string]string)

SetGauge does nothing.

type NoOpSpan 

type NoOpSpan struct{}

NoOpSpan is a no-op implementation of the Span interface.

func (*NoOpSpan) End 

func (n *NoOpSpan) End()

End does nothing.

func (*NoOpSpan) RecordError 

func (n *NoOpSpan) RecordError(err error)

RecordError does nothing.

func (*NoOpSpan) SetAttributes 

func (n *NoOpSpan) SetAttributes(attrs map[string]string)

SetAttributes does nothing.

func (*NoOpSpan) SetStatus 

func (n *NoOpSpan) SetStatus(code StatusCode, description string)

SetStatus does nothing.

type NoOpTracer 

type NoOpTracer struct{}

NoOpTracer is a no-op implementation of the Tracer interface.

func NewNoOpTracer 

func NewNoOpTracer() *NoOpTracer

NewNoOpTracer creates a new NoOpTracer.

func (*NoOpTracer) Start 

func (n *NoOpTracer) Start(ctx context.Context, name string) (context.Context, Span)

Start returns the context unchanged and a new NoOpSpan.

type OtelSpan 

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

OtelSpan wraps an OpenTelemetry span and implements the service Span interface.

func (*OtelSpan) End 

func (s *OtelSpan) End()

End ends the span.

func (*OtelSpan) RecordError 

func (s *OtelSpan) RecordError(err error)

RecordError records an error on the span.

func (*OtelSpan) SetAttributes 

func (s *OtelSpan) SetAttributes(attrs map[string]string)

SetAttributes sets string attributes on the span, converting to OTel attributes.

func (*OtelSpan) SetStatus 

func (s *OtelSpan) SetStatus(code StatusCode, description string)

SetStatus sets the status of the span, converting service StatusCode to OTel codes.

type OtelTracer 

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

OtelTracer wraps the OpenTelemetry trace.Tracer and implements the service Tracer interface.

func NewOtelTracer 

func NewOtelTracer(tracer oteltrace.Tracer) *OtelTracer

NewOtelTracer creates a new OtelTracer wrapping the given OpenTelemetry tracer.

func (*OtelTracer) Start 

func (t *OtelTracer) Start(ctx context.Context, name string) (context.Context, Span)

Start creates a new span with SpanKindInternal and returns it wrapped in OtelSpan.

type PrometheusMetrics 

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

PrometheusMetrics records metrics using Prometheus.

func NewPrometheusMetrics 

func NewPrometheusMetrics(reg *prometheus.Registry) *PrometheusMetrics

NewPrometheusMetrics creates a new PrometheusMetrics and registers all metrics.

func (*PrometheusMetrics) AddCounter 

func (p *PrometheusMetrics) AddCounter(name string, value float64, labels map[string]string)

AddCounter adds a value to a counter metric.

func (*PrometheusMetrics) IncrementCounter 

func (p *PrometheusMetrics) IncrementCounter(name string, labels map[string]string)

IncrementCounter increments a counter metric by 1.

func (*PrometheusMetrics) RecordDuration 

func (p *PrometheusMetrics) RecordDuration(name string, d time.Duration, labels map[string]string)

RecordDuration records a duration to a histogram metric, converting to seconds.

func (*PrometheusMetrics) RecordHistogram 

func (p *PrometheusMetrics) RecordHistogram(name string, value float64, labels map[string]string)

RecordHistogram records a value to a histogram metric.

func (*PrometheusMetrics) SetGauge 

func (p *PrometheusMetrics) SetGauge(name string, value float64, labels map[string]string)

SetGauge sets a gauge metric to a specific value.

type SlogLogger 

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

SlogLogger wraps *slog.Logger and implements the service Logger interface.

func NewSlogLogger 

func NewSlogLogger(w io.Writer) *SlogLogger

NewSlogLogger creates a new SlogLogger with a JSON handler writing to w.

func (*SlogLogger) Debug 

func (s *SlogLogger) Debug(ctx context.Context, msg string, keysAndValues ...interface{})

Debug logs a debug-level message with correlation ID.

func (*SlogLogger) Error 

func (s *SlogLogger) Error(ctx context.Context, msg string, keysAndValues ...interface{})

Error logs an error-level message with correlation ID.

func (*SlogLogger) Info 

func (s *SlogLogger) Info(ctx context.Context, msg string, keysAndValues ...interface{})

Info logs an info-level message with correlation ID.

func (*SlogLogger) Warn 

func (s *SlogLogger) Warn(ctx context.Context, msg string, keysAndValues ...interface{})

Warn logs a warn-level message with correlation ID.

func (*SlogLogger) With 

func (s *SlogLogger) With(keysAndValues ...interface{}) Logger

With returns a new SlogLogger with additional fields bound.

type Span 

type Span interface {
	SetStatus(code StatusCode, description string)
	SetAttributes(attrs map[string]string)
	RecordError(err error)
	End()
}

Span is the service's span interface.

type StatusCode 

type StatusCode int

StatusCode represents the status of a span. 

const (
	// StatusOK indicates successful span completion.
	StatusOK StatusCode = 0
	// StatusError indicates span failure.
	StatusError StatusCode = 1
)

type Tracer 

type Tracer interface {
	Start(ctx context.Context, name string) (context.Context, Span)
}

Tracer is the service's span creation interface.

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.