observability

Documentation

Overview

Package observability standardizes how every service turns on Azugo's own telemetry — logging (with PII/secret redaction), metrics naming, and OpenTelemetry tracing. It re-implements none of it: it configures and wraps Azugo's zap logger, the VictoriaMetrics/metrics registry, and azugo.io/opentelemetry so the whole fleet emits the same shapes.

Index

• Constants
• func EnableRedaction(app *azugo.App, policy *RedactionPolicy)
• func EnableTracing(app *azugo.App, cfg *opentelemetry.Configuration, opts ...opentelemetry.Option) error
• func IncCounter(name string, labels map[string]string)
• func InstrumentHTTPClient(c *http.Client) *http.Client
• func InstrumentedTransport(base http.RoundTripper) http.RoundTripper
• func ObserveSeconds(name string, labels map[string]string, seconds float64)
• type RedactionPolicy
  • func DefaultRedactionPolicy() *RedactionPolicy

Constants

const (
	LabelService = "service"
	LabelRoute   = "route"
	LabelOutcome = "outcome"
	LabelTopic   = "topic"
	LabelTarget  = "target"
)

Standard metric label keys, injected so dashboards are uniform across the fleet. Azugo already emits the inbound-request RED metrics (requests_total / request_duration_seconds with code/method/path labels); these helpers cover the deltas go-platform-kit owns — broker publish/consume and outbound HTTP-client calls.

const (
	OutcomeSuccess = "success"
	OutcomeError   = "error"
)

Standard outcome label values.

const (
	MetricBrokerPublishTotal      = "platform_broker_publish_total"
	MetricBrokerConsumeTotal      = "platform_broker_consume_total"
	MetricOutboundRequestsTotal   = "platform_http_client_requests_total"
	MetricOutboundDurationSeconds = "platform_http_client_request_duration_seconds"
)

Standard metric names for the go-platform-kit-owned signals.

Functions

func EnableRedaction

func EnableRedaction(app *azugo.App, policy *RedactionPolicy)

EnableRedaction installs the redacting policy on the application logger. Every log line — from ctx.Log() in handlers to the framework's own logs — is then scrubbed before it reaches the encoder. Redaction is not optional once installed.

It wraps the core of the current application logger and re-sets it via App.ReplaceLogger. Because ReplaceLogger re-adds Azugo's standard service-identity fields, the policy drops those (already-present) keys when they are re-applied, so they appear exactly once. Call this from platform.Setup, before any request is served.

func EnableTracing

func EnableTracing(app *azugo.App, cfg *opentelemetry.Configuration, opts ...opentelemetry.Option) error

EnableTracing performs the documented azugo.io/opentelemetry wiring once, with standard resource attributes. It enables — never re-implements — tracing: it calls opentelemetry.Use (which traces router handlers, ctx.HTTPClient, and the cache) and registers the returned task with the app.

The service name defaults to the app's AppName when not set via OTEL_SERVICE_NAME. If no OTLP endpoint is configured the package returns a no-op task, so the service starts cleanly and tracing is simply inert — no code change required.

opts is forwarded to opentelemetry.Use as-is, so a service with instrumentation needs beyond the framework's built-in router/HTTP-client/cache tracing (e.g. a custom InstrumentationRecorder for DB query tracing) can supply it without losing platform.Setup — most callers pass none.

func IncCounter

func IncCounter(name string, labels map[string]string)

IncCounter increments the named counter with the given labels, registering it on first use (VictoriaMetrics/metrics — the same registry Azugo exposes at /metrics). Label VALUES must be low-cardinality (service names, topics, outcomes — never ids, urls, or user input): every distinct label set creates a new time series.

func InstrumentHTTPClient

func InstrumentHTTPClient(c *http.Client) *http.Client

InstrumentHTTPClient sets c.Transport to the instrumented wrapper in place and returns c (allocating a client when c is nil). Convenience for the common case of instrumenting a service's own http.Client at construction.

func InstrumentedTransport

func InstrumentedTransport(base http.RoundTripper) http.RoundTripper

InstrumentedTransport wraps base (or http.DefaultTransport when base is nil) so every request sent through it opens an OpenTelemetry client span and injects the W3C trace context (traceparent/baggage) into the outbound headers. The span is a child of whatever span is in the request's context (set ctx via http.NewRequestWithContext), or a new root when none is active.

Use it for the BESPOKE http.Clients that do NOT go through ctx.HTTPClient() — external APIs (eParaksts/Entrust, the EU LOTL/CELLAR, OCSP responders) and service-to-service calls — so those hops show up as client spans and in the Tempo service graph. For S2S calls to other azugo services the injected trace context lets the callee continue the same trace.

It is safe to apply unconditionally: otelhttp is a no-op when tracing is inert (no exporter configured / no active span), so it never changes behaviour or adds overhead beyond a cheap wrapper.

func ObserveSeconds

func ObserveSeconds(name string, labels map[string]string, seconds float64)

ObserveSeconds records a duration (in seconds) on the named histogram with the given labels, registering it on first use.

Types

type RedactionPolicy

type RedactionPolicy struct {
	DropKeys []string
	MaskKeys []string
	// contains filtered or unexported fields
}

RedactionPolicy decides, by log-field key, what must never reach the log sink. Matching is case-insensitive substring matching against the field key.

- DropKeys: the whole field is omitted (credentials, secrets, document bytes — things that must not be stored at all). - MaskKeys: the field is kept but its value is replaced with "[REDACTED]" (free-text PII — useful to know a field was present without storing it).

Redaction is applied centrally so a handler using ctx.Log() cannot accidentally log a token or document content.

Limitation: matching is by TOP-LEVEL field key only. A nested value logged via zap.Any / zap.Reflect (e.g. a whole attributes map) is NOT inspected — sensitive keys inside it bypass redaction. Do not log raw maps/structs that may carry secrets or PII; log individual fields, or sanitize the map first (the audit emitter libraries do this for their own attribute maps).

func DefaultRedactionPolicy

func DefaultRedactionPolicy() *RedactionPolicy

DefaultRedactionPolicy returns the fleet-standard policy: drop credentials, secrets, and document content; mask free-text PII. The lists are intentionally broad (substring matches) so that, e.g., "authorization", "dpop_proof", and "service_token" are all dropped.