Optional OpenTelemetry export
OTLP traces to Honeycomb, Tempo, Jaeger, or any OTel collector.
The brain ships an opt-in OpenTelemetry hook. One env var (Z4J_OTEL_EXPORTER_OTLP_ENDPOINT) enables OTLP/HTTP export of FastAPI HTTP spans, SQLAlchemy query spans, and outbound httpx spans. Off by default; sampling defaults to zero so a fresh enablement does not flood your collector. Health and metrics endpoints are excluded from tracing by default since they swamp any sampling budget. The integration is fail-safe: a missing SDK, a typo'd endpoint, or a broken collector all degrade to a single WARNING and a normal boot.
Ships with
- OTLP/HTTP default; OTLP/gRPC supported via a separate pip extra
- Auto-instrumentation for FastAPI (HTTP server spans), SQLAlchemy (DB client spans), httpx (outbound HTTP spans)
- ParentBased(TraceIdRatioBased) sampler with remote-parent decisions overridden to ALWAYS_OFF so a spoofed traceparent cannot force-sample brain requests
- Resource attributes pin service.name, service.namespace, service.version, deployment.environment
- Default exclude list for /health* and /metrics; operator-supplied additions append
Highlights
- 33-case test suite pins the on/off contract, the resource-attribute schema, and the health-exclusion default
- Endpoint + headers are SecretStr at the Pydantic layer so path-embedded API keys never land in startup logs
- Out-of-range sampler args and unknown protocol values fail Pydantic validation at startup
Related