Observability: Metrics, Alerts and Tracing

Docs version v1 (main) · Nauthera is pre-1.0, in a design-partner program · Updated November 4, 2026

#Metrics

Prometheus metrics are served on the admin listener (:9090/metrics by default; see metrics.enabled and metrics.path). They are never served on the public port. Besides its own metrics, the endpoint serves the Go runtime (go_*), process (process_*) and database connection-pool (go_sql_*, with db_name="nauthera") metrics. The server's own metrics have the nauthera_ prefix:

#Threat signals

Every attack signal of the dashboard's threat page is exported too. nauthera_threat_signals_total counts each audit record a signal counts as the replica records it, once the audit policy has kept it, labelled with the signal, its category and the organization's ID (empty for a platform record). Because it counts as records are written, it sees what the audit level records, as the page does, and each replica counts its own records. nauthera_threat_threshold_per_hour publishes the built-in elevated and critical rates for each signal, so an alert compares against the same thresholds the page shows. Unlike nauthera_audit_events_total, the threat counter carries the organization, so it can tell which tenant is under attack; it never carries an actor or an address.

#The operator's metrics

The Kubernetes operator serves its metrics over TLS on :8443, only to callers the API server authorizes for GET /metrics (operator.metrics.readers in the chart). Beside controller-runtime's own, it publishes:

See Operator.

#Alerting

With the Helm chart, metrics.serviceMonitor creates a ServiceMonitor and metrics.prometheusRule.enabled renders the server's alerting rules as a PrometheusRule; both are off by default and need the Prometheus Operator CRDs. The rules come in groups that can be switched off one by one under metrics.prometheusRule.rules:

Leave out single alerts under disabled, and tune an alert's severity, for and threshold under alerts. The threat alerts take their thresholds from nauthera_threat_threshold_per_hour and have a window (1h) instead; by default the critical one fires after 5m and the elevated one, below the critical rate, after 15m. Every alert has a firing and a silent test case in the chart. See Installation; the chart README lists every alert and its default.

Every alert carries a runbook_url annotation to its runbook: what it means, who is affected, how to diagnose it, what to do and when to escalate. metrics.prometheusRule.runbookUrl (default https://nauthera.io/runbooks/alerts) sets the base; point it at your own wiki to link <runbookUrl>/<alert name> there, or set it empty to leave the annotation out. nauthera-server runbook alerts <name> prints the runbook of the running version offline.

#Tracing

OpenTelemetry tracing is opt-in and exports over OTLP/gRPC:

tracing:
  enabled: true
  endpoint: tempo:4317
  insecure: true          # no TLS to the collector
  sample_ratio: 1.0       # head-based sampling, 0.0–1.0
  environment: production # deployment.environment resource attribute

The public HTTP handler, the gRPC server, database queries, cache calls, SMTP delivery and back-channel logout deliveries are instrumented.

#Logs

Structured logs come from zap, as logging.format: json (the default) or console. Each request's own log line (http_request, or grpc_call for the AdminService) carries its request_id, and, when tracing is on, trace_id and span_id, so you can go from a request to its trace. An http_request line also carries client_kind, what kind of software the User-Agent claims sent the request (browser, ai_agent, crawler, automation, library or unknown), and, for anything but a browser, client_agent, the product it names, such as ClaudeBot or curl. Both are a claim the sender makes; the audit log labels its records the same way. Other lines logged while serving it carry them only when they are logged through the request's logger. DSNs, driver errors and secrets are logged on the server and never returned to clients.

#Health

The Redis cache and the audit pipeline are checked as soft dependencies: if either is down, the server reports degraded, but the replica is not taken out of service.

#Dashboards

The Docker Compose stack in the repository provisions Grafana with:

• a server overview dashboard (/d/nauthera-overview) on Prometheus: HTTP and gRPC request rates and latency, requests in flight, the database pool and cache, goroutines and memory, and the build,
• an audit-log explorer (/d/nauthera-audit) that reads audit_events from PostgreSQL and opens a record's trace in Tempo when the request was sampled, and
• a threats dashboard (/d/nauthera-threats) on Prometheus: how many organization and signal pairs are elevated or critical now, every signal counted in the last hour against its thresholds, with a link from the organization to the audit-log explorer, and the signals over time by signal, category and organization.

Tempo is provisioned as a separate datasource: search traces in Explore. Nothing links a metric to its trace. The server attaches trace_id exemplars to its HTTP and gRPC latency histograms when the trace is sampled, but /metrics does not serve the OpenMetrics format, so a Prometheus with default scrape settings, like this one, receives none.

Prometheus in the same stack loads deploy/compose/alerts.yml, the Helm chart's alerting rules rendered for the compose stack.