Documentation
¶
Overview ¶
Package metrics provides contrib HTTP metrics middleware.
The middleware records request counts and durations through a supplied recorder, using low-cardinality method, route, status, route-policy, and health-status labels. Route labels come from chi route patterns or net/http ServeMux request patterns, never raw paths when the router exposes a matched pattern. RoutePolicyLabels exposes the same bounded route-policy label shape for custom recorders. IdempotencyOutcomeHook and HardTimeoutEventHook wire bounded idempotency and hard-timeout event labels to supported recorders. See docs/metrics.md for label policy and bootstrap defaults.
Index ¶
- Variables
- func HardTimeoutEventHook(recorder HardTimeoutEventMetricsRecorder) func(timeoutmw.HardTimeoutEvent)
- func HealthStatusChangeHook(recorder HealthMetricsRecorder) func(context.Context, ports.HealthStatus, ports.HealthStatus, ...)
- func IdempotencyOutcomeHook(recorder IdempotencyOutcomeMetricsRecorder) idempotencymw.OutcomeHandler
- func PrometheusHandler() http.Handler
- func WebhookDeliveryHook(recorder WebhookDeliveryMetricsRecorder) webhookdelivery.MetricsRecorder
- type HardTimeoutEventMetricsRecorder
- type HealthMetricsRecorder
- type IdempotencyOutcomeMetricsRecorder
- type Labels
- func HardTimeoutEventLabels(event timeoutmw.HardTimeoutEvent) Labels
- func HealthStatusChangeLabels(from, to ports.HealthStatus) Labels
- func IdempotencyOutcomeLabels(event idempotencymw.OutcomeEvent) Labels
- func RoutePolicyLabels(labels Labels) Labels
- func WebhookDeliveryLabels(event webhookdelivery.DeliveryObservation) Labels
- type MetricsRecorder
- type Middleware
- type NoopMetrics
- func (NoopMetrics) IncCounter(_ string, _ Labels)
- func (NoopMetrics) ObserveHistogram(_ string, _ float64, _ Labels)
- func (NoopMetrics) ObserveWebhookDelivery(context.Context, webhookdelivery.DeliveryObservation)
- func (NoopMetrics) RecordHardTimeoutEvent(timeoutmw.HardTimeoutEvent)
- func (NoopMetrics) RecordHealthStatusChange(_, _ ports.HealthStatus, _ ports.DetailedHealthResponse)
- func (NoopMetrics) RecordIdempotencyOutcome(idempotencymw.OutcomeEvent)
- func (NoopMetrics) RecordRoutePolicy(Labels)
- func (NoopMetrics) RecordWebhookDelivery(webhookdelivery.DeliveryObservation)
- type Options
- type PrometheusRecorder
- func (p *PrometheusRecorder) IncCounter(_ string, labels Labels)
- func (p *PrometheusRecorder) ObserveHistogram(_ string, value float64, labels Labels)
- func (p *PrometheusRecorder) ObserveWebhookDelivery(ctx context.Context, event webhookdelivery.DeliveryObservation)
- func (p *PrometheusRecorder) RecordHardTimeoutEvent(event timeoutmw.HardTimeoutEvent)
- func (p *PrometheusRecorder) RecordHealthStatusChange(from, to ports.HealthStatus, _ ports.DetailedHealthResponse)
- func (p *PrometheusRecorder) RecordIdempotencyOutcome(event idempotencymw.OutcomeEvent)
- func (p *PrometheusRecorder) RecordRoutePolicy(labels Labels)
- func (p *PrometheusRecorder) RecordWebhookDelivery(event webhookdelivery.DeliveryObservation)
- type RoutePolicyMetricsRecorder
- type WebhookDeliveryMetricsRecorder
Constants ¶
This section is empty.
Variables ¶
var ErrIncompatibleCollectorRegistration = errors.New("metrics: incompatible collector already registered")
ErrIncompatibleCollectorRegistration reports that a Prometheus metric name is already registered with an incompatible collector type or descriptor shape.
Functions ¶
func HardTimeoutEventHook ¶
func HardTimeoutEventHook(recorder HardTimeoutEventMetricsRecorder) func(timeoutmw.HardTimeoutEvent)
HardTimeoutEventHook converts a hard-timeout middleware callback into a metrics recorder call.
func HealthStatusChangeHook ¶
func HealthStatusChangeHook(recorder HealthMetricsRecorder) func(context.Context, ports.HealthStatus, ports.HealthStatus, ports.DetailedHealthResponse)
HealthStatusChangeHook converts a health scheduler status-change callback into a metrics recorder call.
func IdempotencyOutcomeHook ¶
func IdempotencyOutcomeHook(recorder IdempotencyOutcomeMetricsRecorder) idempotencymw.OutcomeHandler
IdempotencyOutcomeHook converts an idempotency middleware callback into a metrics recorder call.
func PrometheusHandler ¶
PrometheusHandler returns a standard /metrics http.Handler if the Prometheus client is linked; otherwise returns http.NotFoundHandler. This indirection avoids hard dependency on the Prometheus client.
func WebhookDeliveryHook ¶
func WebhookDeliveryHook(recorder WebhookDeliveryMetricsRecorder) webhookdelivery.MetricsRecorder
WebhookDeliveryHook converts webhook delivery observations into a metrics recorder call.
Types ¶
type HardTimeoutEventMetricsRecorder ¶
type HardTimeoutEventMetricsRecorder interface {
RecordHardTimeoutEvent(event timeoutmw.HardTimeoutEvent)
}
HardTimeoutEventMetricsRecorder captures bounded hard-timeout event metrics.
type HealthMetricsRecorder ¶
type HealthMetricsRecorder interface {
RecordHealthStatusChange(from, to ports.HealthStatus, result ports.DetailedHealthResponse)
}
HealthMetricsRecorder captures health-state transition metrics.
Implementations must keep labels bounded and must not include dependency names, error strings, request data, tenant identifiers, or health messages.
type IdempotencyOutcomeMetricsRecorder ¶
type IdempotencyOutcomeMetricsRecorder interface {
RecordIdempotencyOutcome(event idempotencymw.OutcomeEvent)
}
IdempotencyOutcomeMetricsRecorder captures bounded idempotency outcome metrics.
type Labels ¶
Labels is a simple key:value map for metric dimensions.
func HardTimeoutEventLabels ¶
func HardTimeoutEventLabels(event timeoutmw.HardTimeoutEvent) Labels
HardTimeoutEventLabels returns the bounded label set used for hard-timeout metrics and logs. It intentionally excludes paths, panic payloads, headers, response bodies, tenants, and request IDs.
func HealthStatusChangeLabels ¶
func HealthStatusChangeLabels(from, to ports.HealthStatus) Labels
HealthStatusChangeLabels returns the bounded label set used for health status transition metrics.
func IdempotencyOutcomeLabels ¶
func IdempotencyOutcomeLabels(event idempotencymw.OutcomeEvent) Labels
IdempotencyOutcomeLabels returns the bounded label set used for idempotency outcome metrics.
func RoutePolicyLabels ¶
RoutePolicyLabels returns the bounded label set used for route-policy request metrics. The route label should be a route pattern, not a raw request path; blank routes are normalized to "unknown".
func WebhookDeliveryLabels ¶
func WebhookDeliveryLabels(event webhookdelivery.DeliveryObservation) Labels
WebhookDeliveryLabels returns the bounded label set used for outbound webhook delivery metrics and logs. It intentionally excludes tenant IDs, endpoint IDs, delivery IDs, URLs, payloads, secrets, and raw error strings.
type MetricsRecorder ¶
type MetricsRecorder interface {
IncCounter(name string, labels Labels)
ObserveHistogram(name string, value float64, labels Labels)
}
MetricsRecorder captures counters and histograms.
type Middleware ¶
type Middleware struct {
M MetricsRecorder
Clock ports.Clock
}
Middleware instruments HTTP traffic using a provided recorder.
func (*Middleware) Handler ¶
func (mw *Middleware) Handler(next http.Handler) http.Handler
Handler wraps the next handler to record counters and duration. It is intended to emit exactly one observation on both normal and panic paths. For panic paths, it should infer the final visible status before re-panicking so outer recovery can still produce the response contract.
func (*Middleware) HandlerFunc ¶
func (mw *Middleware) HandlerFunc() func(http.Handler) http.Handler
HandlerFunc exposes middleware as a plain function for router use.
func (*Middleware) Middleware ¶
func (mw *Middleware) Middleware() func(http.Handler) http.Handler
Middleware implements ports.Middleware by returning Handler.
type NoopMetrics ¶
type NoopMetrics struct{}
NoopMetrics is the default. Swap later for Prometheus, etc.
func (NoopMetrics) IncCounter ¶
func (NoopMetrics) IncCounter(_ string, _ Labels)
IncCounter is a no-op implementation.
func (NoopMetrics) ObserveHistogram ¶
func (NoopMetrics) ObserveHistogram(_ string, _ float64, _ Labels)
ObserveHistogram is a no-op implementation.
func (NoopMetrics) ObserveWebhookDelivery ¶
func (NoopMetrics) ObserveWebhookDelivery(context.Context, webhookdelivery.DeliveryObservation)
ObserveWebhookDelivery is a no-op implementation.
func (NoopMetrics) RecordHardTimeoutEvent ¶
func (NoopMetrics) RecordHardTimeoutEvent(timeoutmw.HardTimeoutEvent)
RecordHardTimeoutEvent is a no-op implementation.
func (NoopMetrics) RecordHealthStatusChange ¶
func (NoopMetrics) RecordHealthStatusChange(_, _ ports.HealthStatus, _ ports.DetailedHealthResponse)
RecordHealthStatusChange is a no-op implementation.
func (NoopMetrics) RecordIdempotencyOutcome ¶
func (NoopMetrics) RecordIdempotencyOutcome(idempotencymw.OutcomeEvent)
RecordIdempotencyOutcome is a no-op implementation.
func (NoopMetrics) RecordRoutePolicy ¶
func (NoopMetrics) RecordRoutePolicy(Labels)
RecordRoutePolicy is a no-op implementation.
func (NoopMetrics) RecordWebhookDelivery ¶
func (NoopMetrics) RecordWebhookDelivery(webhookdelivery.DeliveryObservation)
RecordWebhookDelivery is a no-op implementation.
type Options ¶
type Options struct {
Recorder MetricsRecorder
Clock ports.Clock
}
Options configures the metrics middleware.
type PrometheusRecorder ¶
type PrometheusRecorder struct {
// contains filtered or unexported fields
}
PrometheusRecorder implements MetricsRecorder using Prometheus client. This is a minimal adapter; applications can supply their own recorder.
func NewPrometheusRecorder ¶
func NewPrometheusRecorder(registerer prometheus.Registerer, buckets []float64) *PrometheusRecorder
NewPrometheusRecorder wires counters and histograms with standard names. Consumers may pass a custom registerer (e.g. for testing). When nil, the default Prometheus registerer is used.
func NewPrometheusRecorderChecked ¶
func NewPrometheusRecorderChecked(registerer prometheus.Registerer, buckets []float64) (*PrometheusRecorder, error)
NewPrometheusRecorderChecked wires counters and histograms with standard names and returns registration conflicts instead of panicking.
func (*PrometheusRecorder) IncCounter ¶
func (p *PrometheusRecorder) IncCounter(_ string, labels Labels)
IncCounter increments the Prometheus counter.
func (*PrometheusRecorder) ObserveHistogram ¶
func (p *PrometheusRecorder) ObserveHistogram(_ string, value float64, labels Labels)
ObserveHistogram records the Prometheus histogram observation.
func (*PrometheusRecorder) ObserveWebhookDelivery ¶
func (p *PrometheusRecorder) ObserveWebhookDelivery(ctx context.Context, event webhookdelivery.DeliveryObservation)
ObserveWebhookDelivery implements webhookdelivery.MetricsRecorder.
func (*PrometheusRecorder) RecordHardTimeoutEvent ¶
func (p *PrometheusRecorder) RecordHardTimeoutEvent(event timeoutmw.HardTimeoutEvent)
RecordHardTimeoutEvent records one bounded hard-timeout event.
func (*PrometheusRecorder) RecordHealthStatusChange ¶
func (p *PrometheusRecorder) RecordHealthStatusChange(from, to ports.HealthStatus, _ ports.DetailedHealthResponse)
RecordHealthStatusChange records a bounded health-state transition counter.
func (*PrometheusRecorder) RecordIdempotencyOutcome ¶
func (p *PrometheusRecorder) RecordIdempotencyOutcome(event idempotencymw.OutcomeEvent)
RecordIdempotencyOutcome records one bounded idempotency decision.
func (*PrometheusRecorder) RecordRoutePolicy ¶
func (p *PrometheusRecorder) RecordRoutePolicy(labels Labels)
RecordRoutePolicy records bounded route policy labels for one request.
func (*PrometheusRecorder) RecordWebhookDelivery ¶
func (p *PrometheusRecorder) RecordWebhookDelivery(event webhookdelivery.DeliveryObservation)
RecordWebhookDelivery records one bounded outbound webhook delivery outcome.
type RoutePolicyMetricsRecorder ¶
type RoutePolicyMetricsRecorder interface {
RecordRoutePolicy(labels Labels)
}
RoutePolicyMetricsRecorder captures bounded per-request route policy labels.
type WebhookDeliveryMetricsRecorder ¶
type WebhookDeliveryMetricsRecorder interface {
RecordWebhookDelivery(event webhookdelivery.DeliveryObservation)
}
WebhookDeliveryMetricsRecorder captures bounded outbound webhook delivery outcomes.
Source Files