Module

_otel

OpenTelemetry integration for distributed tracing.

Provides automatic span creation and context propagation for HTTP requests, enabling pounce to integrate with observability platforms like Jaeger, Datadog, Tempo, and others.

Features:

  • Automatic span creation for each HTTP request
  • Context propagation via traceparent/tracestate headers (W3C Trace Context)
  • 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 context propagation and attribute recording.

Methods

create_request_span 6 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) -> 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
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
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
inject_trace_context 1 list[tuple[bytes, bytes]] ▼
Inject trace context into outgoing HTTP headers. Adds traceparent and tracesta…
def inject_trace_context(headers: list[tuple[bytes, bytes]]) -> list[tuple[bytes, bytes]]

Inject trace context into outgoing HTTP headers.

Adds traceparent and tracestate headers to propagate trace context to downstream services.

Parameters
Name Type Description
headers list[tuple[bytes, bytes]]

Existing headers list.
Returns
list[tuple[bytes, bytes]]
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.