Skip to content

Observability

mavrovde edited this page Nov 13, 2026 · 2 revisions

Observability

This page describes what the API will record about itself, so the operator can see whether its promises hold, without recording anything a caller would not expect.

Logs

  • Structured JSON, one access line per request.
  • Fields: request id, public key id, tier, operation, status, total time, database time, queue time, cache outcome, shed reason, trace id.
  • Never logged: keys, secrets, request bodies, query parameters of database statements.
  • Client IPs are truncated to a configurable network prefix.
  • A redactor masks authorization headers and anything shaped like a ViaFrei key, and a test proves it across every log sink.
  • Panics become an internal problem carrying the request id; the stack trace goes to the log only.

Metrics

Exposed on a loopback-only Prometheus endpoint.

Area Metrics
HTTP requests by operation, status and tier; duration histograms by operation and tier
Admission queue depth and wait time per tier; shed count by tier and reason
Database in-flight queries and permits; query duration by named query; cancellation outcomes; pool statistics
Limits rate-limit and quota refusals by plan
Cache hits, misses, 304 answers; bytes held
Auth failures by reason
Integrity licence-gate violations (must stay at zero; alerts above zero); unknown storage codes by view and column; metering flush failures; read-contract compatibility
Build and runtime version info; process memory and CPU; runtime statistics of the chosen language

Traces

  • OpenTelemetry, off by default, parent-based ratio sampling, W3C trace context.
  • Spans: the HTTP request, admission wait, the use case, each database query (named by the query's name, never its parameters) and cache lookups.
  • No collector or extra container is required; an exporter can be enabled by configuration.

Health

Endpoint Meaning
/healthz liveness; does not touch the database
/readyz both pools answer quickly, the read contract is compatible, the access store's migrations are at head
/v1/meta public: API version, platform version, contract version; tested to contain no secret

Usage reporting

Hourly usage per key and feature is stored in the access store (see Rate Limits and Priority) and shown to the operator. It is shown in ViaFrei's operator dashboards rather than in new monitoring containers at the start. A dedicated Prometheus and Grafana setup is an option for a later stage.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally