telemetry

Documentation

Overview

Package telemetry provides request tagging for structured logging and metrics.

Index

• Variables
• func InitMetrics(ctx context.Context, cfg MetricsConfig) (shutdown func(context.Context) error, err error)
• func InjectTags(r *http.Request) *http.Request
• func PrometheusHandler() http.Handler
• func RecordHTTP(ctx context.Context, r *http.Request, protocol string, status int, ...)
• func SetCacheResult(r *http.Request, result CacheResult)
• func SetEndpoint(r *http.Request, endpoint string)
• func StatusClass(status int) string
• type CacheResult
• type Metrics
• type MetricsConfig
• type RequestTags
  • func GetTags(r *http.Request) *RequestTags

Variables

var ErrMetricsAlreadyInitialized = errors.New("metrics already initialized")

ErrMetricsAlreadyInitialized is returned when InitMetrics is called more than once.

Functions

func InitMetrics

func InitMetrics(ctx context.Context, cfg MetricsConfig) (shutdown func(context.Context) error, err error)

InitMetrics initializes the OpenTelemetry metrics system. Returns a shutdown function that should be called on application exit. Returns ErrMetricsAlreadyInitialized if called more than once.

func InjectTags

func InjectTags(r *http.Request) *http.Request

InjectTags creates a new request with an empty RequestTags in context. Call this in middleware before handlers run.

func PrometheusHandler

func PrometheusHandler() http.Handler

PrometheusHandler returns the Prometheus metrics HTTP handler. Returns a handler that returns 404 if Prometheus export is not enabled, allowing safe registration regardless of initialization order.

func RecordHTTP

func RecordHTTP(ctx context.Context, r *http.Request, protocol string, status int, bytesSent int64, duration time.Duration)

RecordHTTP records HTTP request metrics. Call this from the logging middleware after the request completes.

func SetCacheResult

func SetCacheResult(r *http.Request, result CacheResult)

SetCacheResult sets the cache result for logging.

func SetEndpoint

func SetEndpoint(r *http.Request, endpoint string)

SetEndpoint sets the endpoint type for logging.

func StatusClass

func StatusClass(status int) string

StatusClass returns the HTTP status class (2xx, 3xx, 4xx, 5xx).

Types

type CacheResult

type CacheResult string

CacheResult represents the outcome of a cache lookup.

const (
	CacheHit    CacheResult = "hit"
	CacheMiss   CacheResult = "miss"
	CacheBypass CacheResult = "bypass"
)

type Metrics

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

Metrics holds the OpenTelemetry metric instruments.

type MetricsConfig

type MetricsConfig struct {
	// ServiceName is the name of the service for resource attributes.
	ServiceName string

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

	// OTLPEndpoint is the OTLP gRPC endpoint (e.g., "localhost:4317").
	// If empty, OTLP export is disabled.
	OTLPEndpoint string

	// EnablePrometheus enables the Prometheus /metrics endpoint.
	EnablePrometheus bool

	// FlushInterval is how often to export metrics (default: 10s).
	FlushInterval time.Duration
}

MetricsConfig configures the metrics system.

type RequestTags

type RequestTags struct {
	CacheResult CacheResult
	Endpoint    string
}

RequestTags holds mutable request metadata that handlers can set for logging.

func GetTags

func GetTags(r *http.Request) *RequestTags

GetTags retrieves the request tags from context. Returns nil if not in a request context with logging middleware.