> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateway Trace Hook • AI Agent SDK
> GatewayTraceHook: Structural contract for tracing a gateway pipeline stage as a span.
# GatewayTraceHook
> Defined in the [**protocols**](../modules/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)
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#8B0000', 'primaryTextColor': '#fff', 'primaryBorderColor': '#710101', 'lineColor': '#189AB4', 'secondaryColor': '#189AB4', 'tertiaryColor': '#fff' }}}%%
graph TD
event["Event Trigger"] --> hook["Hook: GatewayTraceHook"]
hook --> decision{"Decision"}
decision -- "Allow" --> proc["Process"]
decision -- "Deny" --> block["Block"]
style hook fill:#189AB4,color:#fff
style event fill:#8B0000,color:#fff
style proc fill:#8B0000,color:#fff
style block fill:#8B0000,color:#fff
```
## Methods
Open a tracing scope for pipeline stage `name`.
## Source
`praisonaiagents/gateway/protocols.py` at line 4820
***
## Related Documentation