v3.0.0

Major release. FastAPI 0.142 added built-in OpenTelemetry, and servicekit now uses it for HTTP metrics instead of the separate opentelemetry-instrumentation-fastapi package. Monitoring is now on by default. HTTP metric names change, so dashboards and alerts need updating.

Why

• fastapi[standard] now installs opentelemetry-sdk and the OTLP HTTP exporter, so every servicekit service already had a second OpenTelemetry stack next to ours.
• FastAPI OpenTelemetry follows the stable HTTP semantic conventions. The contrib package emitted the old http_server_duration_milliseconds series, which did not match our own documentation.
• With OTEL_EXPORTER_OTLP_ENDPOINT set, FastAPI turns on OTLP export by itself at startup. servicekit now controls that switch together with monitoring.

Changed

• Monitoring is on by default. Every BaseServiceBuilder service exposes Prometheus metrics at /metrics without calling with_monitoring(). Call with_monitoring(...) only to change the prefix, tags or service name.
• with_monitoring(enabled=False) turns monitoring off completely: it removes /metrics and disables FastAPI OpenTelemetry tracing, metrics, logs and OTLP auto-configuration, even when OTEL_* variables are set.
• HTTP metrics come from FastAPI OpenTelemetry: http_server_request_duration_seconds (histogram, _count for request totals) and http_server_active_requests, with labels http_request_method, http_response_status_code, http_route, url_scheme and network_protocol_version. Durations are in seconds.
• Requests to the metrics endpoint are no longer counted in HTTP metrics.
• teardown_monitoring() keeps the global meter provider and its Prometheus reader. OpenTelemetry cannot replace a global provider, so setting monitoring up again after a teardown used to leave an orphaned reader.
• Dependencies: fastapi[standard]>=0.142.2, opentelemetry-api>=1.44.0, opentelemetry-sdk>=1.44.0. opentelemetry-instrumentation-fastapi is removed. SQLAlchemy instrumentation, process metrics and the Prometheus exporter are unchanged.

Added

• OTLP export through FastAPI OpenTelemetry. Set OTEL_EXPORTER_OTLP_ENDPOINT (and optionally OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_HEADERS) to send request traces, metrics and logs to a collector, in addition to Prometheus scraping. Only the http/protobuf protocol is supported for this automatic setup.

Upgrading

• Update Prometheus queries, Grafana panels and alerts: http_server_duration_milliseconds_* becomes http_server_request_duration_seconds_*, http_method becomes http_request_method, http_status_code becomes http_response_status_code, and http_target becomes http_route. Thresholds in milliseconds must be divided by 1000. The example Grafana dashboard in examples/monitoring is already updated.
• Services that did not call with_monitoring() now expose /metrics. Add .with_monitoring(enabled=False) if you do not want it, or if something else is mounted at /metrics.
• If your deployment sets OTEL_* variables for other tools, FastAPI will now export over OTLP. Use with_monitoring(enabled=False), or set OTEL_SDK_DISABLED=true, if that is not wanted.
• Remove any direct use of FastAPIInstrumentor alongside servicekit; it is no longer installed.
• Downstream projects pinning servicekit>=2,<3 need to move to >=3.0.0,<4.

What's Changed

• chore(ci): tag releases with --cleanup=verbatim to keep Markdown headings by @mortenoh in #44
• feat(monitoring): use FastAPI OpenTelemetry and enable monitoring by default by @mortenoh in #45
• chore: release 3.0.0 by @mortenoh in #46

Full Changelog: v2.0.3...v3.0.0