​

GatewayTraceHook

Defined in the protocols module.

AI Agent Structural contract for tracing a gateway pipeline stage as a span. A hook is fired around each stage of the inbound -> agent -> tool -> delivery pipeline. Implementations return a context manager whose scope is the span: entering starts it, exiting ends it, and an exception propagating out marks the span as failed. The default core implementation (:class:NullGatewayTraceHook) is a no-op so tracing is zero-cost when no exporter is attached. The contract is deliberately dependency-free: no OpenTelemetry import lives in core. A praisonai-plugins exporter implements stage with tracer.start_as_current_span(...) and carries the correlation id as a span attribute. Example:: with self._trace.stage( “agent.run”, correlation_id=current_correlation_id(), session=sid, ): reply = await agent.astart(text) W3C trace-context propagation is layered on top of the same seam without forcing OpenTelemetry into core. stage accepts an optional parent_carrier (a header mapping such as an inbound request’s {"traceparent": ..., "tracestate": ...}) so an exporter can continue an upstream caller’s trace instead of starting a detached one; and the two companion methods let egress call sites propagate the active span context:

​

ingress: continue the caller’s trace when a traceparent arrives

with self._trace.stage(“agent.run”, parent_carrier=inbound.headers): …

​

egress: write the active traceparent onto an outbound request.

​

Seed with provider headers first, then inject last so the active

​

trace context always wins over any stale traceparent/tracestate.

headers = dict(provider_headers) self._trace.inject_context(headers) # no-op unless an exporter is set Both companion methods are no-ops in :class:NullGatewayTraceHook, so the default path stays zero-cost and OpenTelemetry-free.

​

Methods

​

Source

---

​

Related Documentation