Skip to main content

Telemetry pipeline

The API emits local logs in development and production and can export logs and metrics through OpenTelemetry Protocol (OTLP). One configuration switch controls both remote signals.

Configuration gate​

OTEL_EXPORT_ENABLED defaults to off in development and on in production. Tests always disable export. When export is enabled, OTEL_EXPORTER_OTLP_ENDPOINT must be a valid HTTP or HTTPS URL or the API refuses to start.

Logs​

Pino writes non-test logs to stdout and to the rotating logs/api.log file. When export is enabled, a third transport sends log records to <OTLP endpoint>/v1/logs with the service name api and the deployment environment attached as resource attributes.

Metrics​

The API registers HTTP and Node.js runtime instrumentation and reports process CPU utilization and resident memory. Metrics are exported periodically to <OTLP endpoint>/v1/metrics. Outgoing HTTP instrumentation is disabled, and incoming /health and /ready requests are excluded from remote instrumentation.

Collector and Better Stack​

For local forwarding, start the optional collector profile:

docker compose --profile otel up otel-collector

The collector accepts OTLP over ports 4317 and 4318, applies memory limiting and batching, then forwards logs and metrics to Better Stack. Its environment file contains the Better Stack ingest host and source token; those credentials do not belong in the API process.

Shutdown​

Telemetry starts before the database and HTTP listener. During graceful shutdown it stops after Fastify and the database, allowing the provider to flush and close. Calling shutdown more than once is safe.