Repository navigation
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.
- 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
internalproblem carrying the request id; the stack trace goes to the log only.
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 |
- 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.
| 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 |
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.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference