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; Nonefalls 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.

TheBatchSpanProcessor only exports on its schedule_delaytimer (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.