# _otel URL: /pounce/api/_otel/ Section: api Description: OpenTelemetry integration for distributed tracing. Provides automatic span creation for HTTP requests and inbound W3C Trace Context extraction, enabling pounce to integrate with observability platforms like Jaeger, Datadog, Tempo, and others. Features: - Automatic span creation for each HTTP request - Inbound W3C Trace Context extraction (traceparent/tracestate parsed from request headers so server spans join an upstream trace). Pounce is a server, not an outbound HTTP client, so it does not inject trace context into downstream requests. - OTLP exporter configuration - Request/response attributes (method, path, status, duration) - Optional integration (graceful degradation if OTel not installed) - Zero overhead when disabled Usage: config = ServerConfig( otel_endpoint="http://localhost:4318", # OTLP HTTP endpoint otel_service_name="my-service", ) Security: - Only enabled when otel_endpoint is configured - Never samples sensitive data (passwords, tokens) - Respects standard OTel environment variables --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/_otel/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_otel%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_otel%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_otel%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_otel%2Findex.txt) Module # `_otel` OpenTelemetry integration for distributed tracing. Provides automatic span creation for HTTP requests and inbound W3C Trace Context extraction, enabling pounce to integrate with observability platforms like Jaeger, Datadog, Tempo, and others. Features: - Automatic span creation for each HTTP request - Inbound W3C Trace Context extraction (traceparent/tracestate parsed from request headers so server spans join an upstream trace). Pounce is a server, not an outbound HTTP client, so it does not inject trace context into downstream requests. - OTLP exporter configuration - Request/response attributes (method, path, status, duration) - Optional integration (graceful degradation if OTel not installed) - Zero overhead when disabled Usage: ``` config = ServerConfig( otel_endpoint="http://localhost:4318", # OTLP HTTP endpoint otel_service_name="my-service", ) ``` Security: - Only enabled when otel_endpoint is configured - Never samples sensitive data (passwords, tokens) - Respects standard OTel environment variables 2Classes6Functions ## Classes `RequestSpanManager` 5 ▼ Manages OpenTelemetry spans for HTTP requests. Creates and manages the lifecycle of trace spans fo… Manages OpenTelemetry spans for HTTP requests. Creates and manages the lifecycle of trace spans for incoming HTTP requests, including inbound parent-context extraction (so server spans join an upstream trace) and attribute recording. Does not propagate trace context to downstream services. #### Methods `create_request_span` 7 `Any` ▼ Create a span for an HTTP request. `def create_request_span(self, *, method: str, path: str, headers: Sequence[tuple[bytes, bytes]], scheme: str = 'http', server_host: str = 'localhost', server_port: int = 8000, route: str | None = None) -> Any` ##### Parameters Name Type Description `method` `—` HTTP method (GET, POST, etc.). `path` `—` Request path. `headers` `—` Request headers for context extraction. `scheme` `—` URL scheme (http or https). Default:`'http'` `server_host` `—` Server hostname. Default:`'localhost'` `server_port` `—` Server port. Default:`8000` `route` `—` Low-cardinality route template (e.g.`/users/{id}`) when the app exposes one. Used in the span name to keep cardinality bounded; `None`falls back to just the method. Default:`None` ##### Returns `Any` Span context manager (use with `with` statement). `record_response` 3 ▼ Record response attributes on a span. `def record_response(self, span: Any, *, status_code: int, response_size: int = 0) -> None` ##### Parameters Name Type Description `span` `—` The span to update. `status_code` `—` HTTP status code. `response_size` `—` Response body size in bytes. Default:`0` `record_exception` 2 ▼ Record an exception on a span. `def record_exception(self, span: Any, exception: Exception) -> None` ##### Parameters Name Type Description `span` `—` The span to update. `exception` `—` The exception that occurred. `end_span` 1 ▼ End a span. `def end_span(self, span: Any) -> None` ##### Parameters Name Type Description `span` `—` The span to end. Internal Methods 1 ▼ `__init__` 2 ▼ Initialize the span manager. `def __init__(self, *, service_name: str = 'pounce', enabled: bool = True) -> None` ##### Parameters Name Type Description `service_name` `—` Service name for the tracer. Default:`'pounce'` `enabled` `—` Whether tracing is enabled. Default:`True` `_NoOpSpan` 6 ▼ No-op span for when OpenTelemetry is disabled. No-op span for when OpenTelemetry is disabled. #### Methods `set_attribute` 2 ▼ `def set_attribute(self, *args, **kwargs)` ##### Parameters Name Type Description `*args` `—` `**kwargs` `—` `set_status` 2 ▼ `def set_status(self, *args, **kwargs)` ##### Parameters Name Type Description `*args` `—` `**kwargs` `—` `record_exception` 2 ▼ `def record_exception(self, *args, **kwargs)` ##### Parameters Name Type Description `*args` `—` `**kwargs` `—` `end` 0 ▼ `def end(self)` Internal Methods 2 ▼ `__enter__` 0 ▼ `def __enter__(self)` `__exit__` 1 ▼ `def __exit__(self, *args)` ##### Parameters Name Type Description `*args` `—` ## Functions `is_otel_available` 0 `bool` ▼ Check if OpenTelemetry is installed. `def is_otel_available() -> bool` ##### Returns `bool` `configure_otel` 3 `None` ▼ Configure OpenTelemetry with OTLP exporter. `def configure_otel(*, endpoint: str, service_name: str = 'pounce', insecure: bool = False) -> None` ##### Parameters Name Type Description `endpoint` `str` OTLP endpoint URL (e.g., "http://localhost:4318"). `service_name` `str` Service name for resource attributes. Default:`'pounce'` `insecure` `bool` Allow insecure connections (HTTP instead of HTTPS). Default:`False` `flush_otel` 1 `None` ▼ Flush in-flight spans from the active provider's processors. The ``BatchSpanPr… `def flush_otel(timeout_millis: int = 5000) -> None` Flush in-flight spans from the active provider's processors. The`BatchSpanProcessor` only exports on its `schedule_delay`timer (or when its queue fills), and the SDK does not flush on process exit. Spans created shortly before a worker stops are therefore dropped unless flushed explicitly. Worker shutdown calls this so those spans are exported instead of lost (issue #133). Safe to call when OTel is unavailable or unconfigured. ##### Parameters Name Type Description `timeout_millis` `int` Default:`5000` `extract_trace_context` 1 `Any` ▼ Extract trace context from HTTP headers. Parses W3C Trace Context headers (tra… `def extract_trace_context(headers: Sequence[tuple[bytes, bytes]]) -> Any` Extract trace context from HTTP headers. Parses W3C Trace Context headers (traceparent, tracestate) from the incoming request and returns a context object for span creation. ##### Parameters Name Type Description `headers` `Sequence[tuple[bytes, bytes]]` List of (name, value) header tuples. ##### Returns `Any` `get_current_span` 0 `Any` ▼ Get the current active span. `def get_current_span() -> Any` ##### Returns `Any` `add_span_attribute` 2 `None` ▼ Add an attribute to the current span. `def add_span_attribute(key: str, value: Any) -> None` ##### Parameters Name Type Description `key` `str` Attribute name. `value` `Any` Attribute value.