Logging, Metrics and Distributed Tracing
Make APIs diagnosable in production using structured logs, metrics, tracing, and correlation identifiers.
Structured Logging
Production API logs should be machine-readable and searchable.
Useful fields include timestamp, severity, service name, environment, request ID, trace ID, HTTP method, route, status code, duration, user or tenant identifier where appropriate, and error classification.
Never log passwords, access tokens, session cookies, or sensitive personal information unnecessarily.
Logging the route template such as /users/:id is generally more useful than logging millions of unique URLs.
{
"level": "info",
"requestId": "req_123",
"method": "GET",
"route": "/users/:id",
"status": 200,
"durationMs": 23
}API Metrics
Track request rate, error rate, latency, saturation, and dependency health.
Latency should be measured using percentiles rather than only averages. Averages can hide a severe tail-latency problem.
Useful measurements include p50, p95, and p99 latency, HTTP status distribution, requests per second, database latency, queue depth, and external dependency failures.
A useful service-level objective might specify that 99% of successful API requests should complete within a target latency under defined conditions.
How long requests takeRequests per secondFailed requestsResource pressureDistributed Tracing
A single API request can travel through an API gateway, service, database, cache, queue, and several downstream services.
Distributed tracing attaches trace context to requests so the complete journey can be reconstructed.
A trace contains spans representing operations such as HTTP handling, database queries, Redis calls, and downstream API calls.
Correlation IDs help connect logs, while distributed trace IDs provide a richer view of request execution across services.