Metrics & Tracing

The observe package provides optional, dependency-free observability hooks: a low-cardinality metrics counter interface (with a no-op default and a slog adapter) and structured-logging helpers for security events. There is no Prometheus or other metrics dependency — your application bridges the Metrics interface to its own registry. log/slog is stdlib, so this package adds nothing to go.mod.

Import

import "github.com/thuongh2/go-security/observe"

Metrics

Metrics is a single-method interface — one fixed, low-cardinality Event enum, no label map:

type Metrics interface {
    Inc(event Event)
}

const (
    EventAuthSuccess  Event = "authn.success"
    EventAuthFailure  Event = "authn.failure"
    EventAccessDenied Event = "authz.denied"
    EventRateLimited  Event = "ratelimit.dropped"
    EventLockout      Event = "lockout.locked"
)

Bridge it to your own registry:

import "github.com/prometheus/client_golang/prometheus"

authnTotal := prometheus.NewCounterVec(prometheus.CounterOpts{
    Name: "authn_total",
    Help: "Security events",
}, []string{"event"})

type prometheusMetrics struct{ vec *prometheus.CounterVec }

func (m prometheusMetrics) Inc(e observe.Event) {
    m.vec.WithLabelValues(string(e)).Inc()
}

Low-cardinality discipline

The only label is the fixed Event enum. Never add a username, client IP, session ID, or token as a label or log field — that’s both a metrics-cardinality-explosion DoS and a PII leak.

Bundled sinks

Sink	Behavior
`observe.NopMetrics`	Discards every increment. The safe default.
`observe.SlogMetrics{Logger, Level}`	Logs one record per event via `log/slog`, attribute `"event"` only — never a username, IP, or token.

Wiring into securityhttp

observe.Hooks bundles a Metrics sink and an optional *slog.Logger; securityhttp.New/NewHandler thread it through the assembled chain (an authz denial increments EventAccessDenied/EventAuthFailure, a 429 increments EventRateLimited). Wire observe.Hooks.Metrics to whatever registry your service already exports to — Prometheus (see the bridge above) or OpenTelemetry both work the same way: implement Inc(Event) and forward it to a Counter/CounterVec in that registry.

chain, err := securityhttp.New(
    securityhttp.WithSessionStore(store, users),
    securityhttp.WithObserve(observe.Hooks{Metrics: myMetricsBridge, Logger: slog.Default()}),
    securityhttp.WithAuthorize(authz.Routes(authz.AnyRequest().PermitAll())),
)

observe.Hooks{}.WithDefaults() fills in NopMetrics and slog.Default() where unset, so a zero-value Hooks is safe to pass around.

Wiring authn events directly

observe has no publisher of its own — authn.Manager publishes success/ failure through core/event.Publisher, whose only two methods are PublishAuthSuccess / PublishAuthFailure:

type Publisher interface {
    PublishAuthSuccess(ctx context.Context, auth core.Authentication)
    PublishAuthFailure(ctx context.Context, auth core.Authentication, err error)
}

Adapt plain functions with event.FuncPublisher and bump your Metrics sink from them:

publisher := event.FuncPublisher{
    OnSuccess: func(ctx context.Context, auth core.Authentication) {
        hooks.Inc(observe.EventAuthSuccess)
    },
    OnFailure: func(ctx context.Context, auth core.Authentication, err error) {
        hooks.Inc(observe.EventAuthFailure)
    },
}

manager := authn.NewManager(providers, authn.WithPublisher(publisher))

The auth passed to PublishAuthFailure is already sanitized (any plaintext password cleared), so it’s safe to key on auth.Name().

Structured audit log

publisher := event.FuncPublisher{
    OnSuccess: func(ctx context.Context, auth core.Authentication) {
        slog.Info("authn.success", "user", auth.Name())
    },
    OnFailure: func(ctx context.Context, auth core.Authentication, err error) {
        slog.Warn("authn.failure", "user", auth.Name(), "error", err)
    },
}

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Metrics

Low-cardinality discipline

Bundled sinks

Wiring into securityhttp

Wiring authn events directly

Structured audit log

​Import

​Metrics

​Low-cardinality discipline

​Bundled sinks

​Wiring into securityhttp

​Wiring authn events directly

​Structured audit log

Import

Metrics

Low-cardinality discipline

Bundled sinks

Wiring into securityhttp

Wiring authn events directly

Structured audit log