kaya/packages/kaya-otel/README.md

kaya-otel

OpenTelemetry tracing and metrics for the Kaya web framework.

Provides OTelMixin, a KayaMixin that instruments HTTP requests and WebSocket connections with OpenTelemetry spans and exports HTTP server metrics, shipping everything to an OTLP/HTTP collector.

Usage

from kaya.core import KayaApp, HttpContext
from kaya.otel import OTelMixin

app = KayaApp(mixins=[
    OTelMixin(
        service_name='my-service',
        endpoint='http://localhost:4318',
    )
])

@app.GET('/')
async def home(ctx: HttpContext):
    await ctx.send_str(200, 'Hello World!')

Parameters

• service_name: value of the service.name resource attribute.
• endpoint: base URL of an OTLP/HTTP collector; the signal paths /v1/traces and /v1/metrics are appended. When None, the exporters use their own defaults, including the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
• headers: extra HTTP headers sent to the collector (e.g. authentication).
• metric_export_interval_millis: metric export interval (default 60000).
• tracer_provider / meter_provider: inject custom providers (e.g. with in-memory exporters for tests) instead of the OTLP defaults. The mixin only shuts down providers it created itself.
• resource_attributes: extra resource attributes merged with service.name when the mixin creates the providers.
• excluded_paths / excluded_path_regexes: skip tracing and metrics for matching paths (useful for health checks and metrics endpoints).
• capture_request_headers / capture_response_headers: opt-in HTTP header capture as http.request.header.<name> / http.response.header.<name> span attributes. Header names are normalized to lowercase with - replaced by _; values are captured as string lists.
• sanitize_headers: headers captured as REDACTED (default: authorization, proxy-authorization, cookie, set-cookie).
• server_request_hook / server_response_hook / websocket_connect_hook / websocket_close_hook: optional synchronous callbacks invoked with the span and the Kaya context/websocket at the corresponding lifecycle point. Hook exceptions are logged and do not fail the request.
• metrics_include_raw_path: when True, metrics use raw url.path attributes (legacy, potentially high cardinality). The default False keeps metrics low-cardinality by using http.route when Kaya can resolve a route template.
• websocket_error_close_codes: close codes that mark a websocket span as failed. Defaults to protocol/application error codes such as 1002, 1003 and 1007-1011.

Behavior

• Every HTTP request gets a SERVER span named <METHOD> <path> with the usual HTTP semantic attributes (http.request.method, url.path, client.address, server.address, ...). When Kaya resolves a route template, the span name is updated to <METHOD> <route template> and http.route is set. The response status code is recorded as http.response.status_code when the handler sends the response; 5xx statuses mark the span as failed. Exceptions escaping the handler are recorded on the span and also mark it as failed.
• Every WebSocket connection gets one span for its whole lifetime. The close code is recorded as kaya.websocket.close_code; exceptions and configured error close codes mark the span as failed.
• W3C traceparent/tracestate headers on incoming requests are honored, so traces propagate from upstream services.
• Metrics:
  • http.server.request.duration (histogram, seconds), with http.request.method, http.route when known and http.response.status_code attributes.
  • http.server.active_requests (up-down counter), with http.request.method attributes.

OTelMixin is a KayaMixin, so the app stays a KayaApp and both ASGI and RSGI keep working.