5.0.0 — 2026-08-29¶

Breaking Changes¶

OpenTelemetry replaces Sentry, Elastic APM, and Prometheus - Observability is configured exclusively through BaseConfig.OTEL (OpentelemetryConfig). Providers are built from pydantic settings — OTEL_* environment-variable autoconfiguration is not used.
Removed config classes / fields - SentryConfig, PrometheusConfig, ElasticsearchAPMConfig, FastAPIRateLimitConfig, and the corresponding BaseConfig fields / SENTRY__*, PROMETHEUS__*, ELASTIC_APM__*, FASTAPI_RATE_LIMIT__* env prefixes.

OtelUtils replaces TracingUtils / PrometheusUtils - New module archipy.helpers.utils.otel_utils.
Tracing decorators renamed - @capture_transaction / @capture_span (and async variants) → @trace_root / @trace_span / @async_trace_root / @async_trace_span / @trace_class.
Metrics decorators added - @measure_duration, @async_measure_duration, @count_calls, @async_count_calls.
BaseUtils.capture_exception - Records on the current OpenTelemetry span (no Sentry / Elastic APM capture).

Removed - FastAPIMetricInterceptor, FastAPI rate-limit handler / identifiers, gRPC metric interceptors, gRPC trace interceptors (client and server), and the empty archipy.helpers.interceptors.fastapi package.
AppUtils.create_fastapi_app - Auto-instruments via FastAPIInstrumentor when OTEL.IS_ENABLED (archipy[otel-fastapi]).
AppUtils.create_grpc_app / create_async_grpc_app - Insert OTel contrib server interceptors when enabled (archipy[otel-grpc]). Exception and gRPC rate-limit interceptors remain.
Client gRPC - Use OtelUtils.grpc_client_interceptors() / async_grpc_client_interceptors().

Prometheus scrape endpoint removed - Temporal metrics use Temporal SDK OpenTelemetryConfig (OTLP) driven by TEMPORAL.ENABLE_METRICS and OTEL.IS_ENABLED + OTEL.METRICS_ENABLED (endpoint/protocol/headers from OTEL).
Traces - Client attaches temporalio.contrib.opentelemetry.TracingInterceptor when OTel traces are enabled.

Removed extras - prometheus, sentry, elastic-apm.
Added extras - otel, otel-fastapi, otel-grpc, otel-sqlalchemy, otel-redis, otel-elasticsearch, otel-kafka, otel-scylladb, otel-minio.

Old API / extra	New API / extra
`archipy[prometheus]`	`archipy[otel]` (+ stack extras as needed)
`archipy[sentry]` / `archipy[elastic-apm]`	`archipy[otel]` (+ `otel-fastapi` / `otel-grpc`)
`BaseConfig.SENTRY` / `PROMETHEUS` / `ELASTIC_APM`	`BaseConfig.OTEL` (`OpentelemetryConfig`)
`SENTRY__` / `PROMETHEUS__` / `ELASTIC_APM__*`	`OTEL__*` env prefix
`TracingUtils`	`OtelUtils`
`PrometheusUtils`	OTLP metrics via `OtelUtils` / collector
`@capture_transaction`	`@trace_root` / `@async_trace_root`
`@capture_span`	`@trace_span` / `@async_trace_span`
`FastAPIMetricInterceptor`	`AppUtils.create_fastapi_app` + `otel-fastapi`
gRPC metric / trace interceptors	`AppUtils.create_grpc_app` + `otel-grpc`
gRPC client trace interceptors	`OtelUtils.grpc_client_interceptors()`
`sentry_sdk.capture_exception` / APM capture	`BaseUtils.capture_exception` (current span)
Temporal Prometheus port / scrape	`ENABLE_METRICS` + `OTEL.IS_ENABLED` / `METRICS_ENABLED`
`FastAPIRestRateLimitHandler`	`fastapi-redis-sdk` `rate_limit()`

See Observability for configuration and usage.

OtelUtils - Idempotent provider lifecycle, library instrumentors, status mapping, gRPC client interceptors, and test helpers (configure_for_testing / reset_for_testing).
Tracing & metrics decorators - Span and meter decorators under archipy.helpers.decorators.

OpentelemetryConfig - Master switch, OTLP endpoint/protocol/headers, traces/metrics/logs toggles, sample ratio, resource attributes, FastAPI excluded URLs, log level.

prometheus_utils, tracing_utils, FastAPI metric middleware, FastAPI rate-limit package, gRPC metric and trace interceptor packages.

SentryConfig, PrometheusConfig, ElasticsearchAPMConfig, FastAPIRateLimitConfig.

httpx2 — core HTTP clients use httpx2; otel instruments httpx/requests only
Kafka aio — Confluent sync instrumentor; async Kafka paths may be uninstrumented
SMTP — email adapter / smtplib not auto-instrumented