Optional OpenTelemetry export
OTLP traces to Honeycomb, Tempo, Jaeger, or any OTel collector.
The brain ships an opt-in OpenTelemetry hook. Set Z4J_OTEL_EXPORTER_OTLP_ENDPOINT to configure the exporter and set Z4J_OTEL_TRACES_SAMPLER_ARG to a positive ratio to emit FastAPI HTTP spans, SQLAlchemy query spans, and outbound httpx spans. Sampling defaults to zero, so configuring only the endpoint emits no spans. 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