Tracing

Every public symbol in the gatewaysdk tracing surface, with its exact signature, a parameter table, its return value, and a short runnable example. Signatures are verified against the SDK source. A captured session is the seed a world is built from, and a run against a world is traced like any other execution.

How-to lives in the Tracing guide: instrument an agent, group runs into sessions, attach metadata and identity, auto-instrument LLM libraries, and export to Surface Area.

The span and lifecycle helpers live on the tracing module. The identify helper lives at the package root. Every example on this page assumes the two imports below, and that tracing.init() has already run.

import gatewaysdk
import gatewaysdk.tracing as tracing

`tracing.init()`

Configure the OpenTelemetry tracer provider, connect to Surface Area, and instrument installed AI libraries. Call once at startup. All parameters are keyword-only.

def init(
    *,
    agent: str | dict | AgentIdentity | None = None,
    trace_name: str | None = None,
    service_name: str | None = None,
    environment: str | None = None,
    version: str | None = None,
    gateway_host: str | None = None,
    gateway_public_key: str | None = None,
    gateway_secret_key: str | None = None,
    gateway_endpoint: str | None = None,
    instrument_default: bool = True,
    exporters: list[SpanExporter] | None = None,
    trace_config: TraceConfig | None = None,
    force: bool = False,
    integrations: dict | None = None,
    debug: bool | str = False,
    batch_queue_size: int | None = None,
    batch_flush_interval: int | None = None,
    batch_max_export_size: int | None = None,
) -> None

Parameter	Type	Default	Purpose
`agent`	`str` \| `dict` \| `AgentIdentity`	`None`	Identity this process runs as. Stamped on every trace and registered with the control plane. Falls back to `GATEWAY_AGENT_ID` / `GATEWAY_AGENT_NAME` / `GATEWAY_AGENT_VERSION`. A dict requires an `id` key.
`trace_name`	`str`	`None`	Sets the `trace.name` resource attribute on new traces.
`service_name`	`str`	`"gatewaysdk-tracing"`	Service name on the OpenTelemetry resource.
`environment`	`str`	`None`	Environment label (`production`, `staging`). Sets the `gateway.environment` resource attribute for filtering.
`version`	`str`	`None`	Application version or git SHA. Sets `gateway.version` for tracking regressions.
`gateway_host`	`str`	`None`	Surface Area server URL. Overrides `GATEWAY_HOST`.
`gateway_public_key`	`str`	`None`	Project public key (`pk-lf-...`). Overrides `GATEWAY_PUBLIC_KEY`.
`gateway_secret_key`	`str`	`None`	Project secret key (`sk-lf-...`). Overrides `GATEWAY_SECRET_KEY`.
`gateway_endpoint`	`str`	`None`	Full OTLP endpoint URL. Overrides `GATEWAY_OTLP_ENDPOINT`. Derived from the host when omitted.
`instrument_default`	`bool`	`True`	Auto-instrument the default set of installed AI libraries.
`exporters`	`list[SpanExporter]`	`None`	Custom OpenTelemetry exporters. When omitted and credentials are present, a Surface Area exporter is created automatically.
`trace_config`	`TraceConfig`	`None`	OpenInference `TraceConfig` controlling capture (for example, hiding inputs or outputs). Captures everything by default, recording each model call’s messages once, in `input.value` / `output.value`. Set `OPENINFERENCE_HIDE_INPUT_MESSAGES=false` / `OPENINFERENCE_HIDE_OUTPUT_MESSAGES=false` to also record one `llm.input_messages.*` attribute per message.
`force`	`bool`	`False`	Replace an existing global tracer provider instead of reusing it.
`integrations`	`dict`	`None`	Fine-grained per-integration configuration.
`debug`	`bool` \| `str`	`False`	Console log level. `True` maps to `"DEBUG"`; accepts `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`.
`batch_queue_size`	`int`	`None` (SDK default 2048)	Max spans buffered in memory. Raise for bulk imports. Wraps `OTEL_BSP_MAX_QUEUE_SIZE`.
`batch_flush_interval`	`int`	`None` (SDK default 5000)	Milliseconds between background flushes. Wraps `OTEL_BSP_SCHEDULE_DELAY`.
`batch_max_export_size`	`int`	`None` (SDK default 512)	Max spans per export call. Wraps `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`.

Returns None.

import gatewaysdk.tracing as tracing

tracing.init(
    service_name="faq-bot",
    environment="production",
    version="1.2.3",
)

With no credential parameters, init() reads GATEWAY_HOST, GATEWAY_PUBLIC_KEY, and GATEWAY_SECRET_KEY from the environment. When none of the three are set, spans are created but not exported.

`tracing.shutdown()` and `tracing.flush()`

Flush pending spans. Spans are batched and exported in the background, so a short-lived process must flush before exit or it drops its last traces.

def shutdown(timeout_millis: int = 30000) -> None
def flush(timeout_millis: int = 30000) -> bool

Parameter	Type	Default	Purpose
`timeout_millis`	`int`	`30000`	Maximum time to wait for the flush to complete, in milliseconds.

shutdown() flushes and tears down the provider; it is safe to call more than once and returns None. flush() forces an export at a checkpoint without ending the session and returns True when the flush completed, False on timeout or error.

import atexit
import gatewaysdk.tracing as tracing

tracing.init()
atexit.register(tracing.shutdown)

# Force export after a batch of work, keeping tracing active:
tracing.flush()

`tracing.trace()`

Create a root span. trace is a class that works both as a decorator (auto-captures function input and output) and as a context manager (explicit input and output). The first positional argument is either a span name or the function being decorated.

class trace:
    def __init__(
        self,
        name_or_func: str | Callable | None = None,
        *,
        name: str | None = None,
        input: Any | None = None,
        kind: SpanKind = SpanKind.INTERNAL,
        attributes: dict | None = None,
        capture_input: bool = True,
        capture_output: bool = True,
        record_exception: bool = True,
        set_status_on_exception: bool = True,
    )

Parameter	Type	Default	Purpose
`name_or_func`	`str` \| `Callable`	`None`	Span name, or the decorated function when used as `@tracing.trace`.
`name`	`str`	`None`	Explicit span name. Defaults to the function name in decorator mode, or `"trace"`.
`input`	`Any`	`None`	Input value recorded on the span (context-manager mode).
`kind`	`SpanKind`	`SpanKind.INTERNAL`	OpenTelemetry span kind.
`attributes`	`dict`	`None`	Attributes set on the span at start.
`capture_input`	`bool`	`True`	Auto-record the function’s arguments (decorator mode).
`capture_output`	`bool`	`True`	Auto-record the function’s return value (decorator mode).
`record_exception`	`bool`	`True`	Record a raised exception on the span.
`set_status_on_exception`	`bool`	`True`	Set span status to error when the block raises.

As a context manager it yields an OpenTelemetry Span. As a decorator it wraps sync and async functions unchanged.

# Decorator: captures input and output automatically
@tracing.trace
def summarize(text: str) -> dict:
    return {"summary": text[:100]}

# Context manager: explicit input and output
with tracing.trace("answer-question", input=query) as span:
    result = run_agent(query)
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)

`tracing.span()`

Create a child span under the current active span. Becomes a root span when none is active. Yields an OpenTelemetry Span.

@contextmanager
def span(
    name: str,
    *,
    input: Any | None = None,
    kind: SpanKind = SpanKind.INTERNAL,
    attributes: dict | None = None,
    record_exception: bool = True,
    set_status_on_exception: bool = True,
    **extra_attributes: Any,
) -> Generator[Span, None, None]

Parameter	Type	Default	Purpose
`name`	`str`	required	Span name.
`input`	`Any`	`None`	Input value recorded on the span.
`kind`	`SpanKind`	`SpanKind.INTERNAL`	OpenTelemetry span kind.
`attributes`	`dict`	`None`	Attributes set on the span at start.
`record_exception`	`bool`	`True`	Record a raised exception on the span.
`set_status_on_exception`	`bool`	`True`	Set span status to error when the block raises.
`**extra_attributes`	`Any`	N/A	Extra attributes passed as keyword arguments, merged with `attributes`.

with tracing.trace("answer-question", input=query):
    with tracing.span("retrieve", input=query) as s:
        docs = retrieve(query)
        s.set_attribute(tracing.semconv.OBSERVATION_OUTPUT, str(len(docs)))

`tracing.tool()`

Trace a tool or API call. Marks the span as a client call and sets gateway.observation.type to tool so the platform files it as a tool observation. Yields an OpenTelemetry Span.

@contextmanager
def tool(
    name: str,
    *,
    input: Any | None = None,
    tool_name: str | None = None,
    attributes: dict | None = None,
    record_exception: bool = True,
    set_status_on_exception: bool = True,
    **extra_attributes: Any,
) -> Generator[Span, None, None]

Parameter	Type	Default	Purpose
`name`	`str`	required	Span name, often the tool or function name.
`input`	`Any`	`None`	Input value recorded on the span.
`tool_name`	`str`	`None`	Explicit `tool.name` attribute. Defaults to `name`.
`attributes`	`dict`	`None`	Attributes set on the span at start.
`record_exception`	`bool`	`True`	Record a raised exception on the span.
`set_status_on_exception`	`bool`	`True`	Set span status to error when the block raises.
`**extra_attributes`	`Any`	N/A	Extra attributes passed as keyword arguments.

with tracing.tool("search_database", input=query) as s:
    rows = db.execute(query)
    s.set_attribute(tracing.semconv.OBSERVATION_OUTPUT, str(len(rows)))

`tracing.atrace()` and `tracing.aspan()`

Async variants of trace (root span) and span (child span). Both are async context managers with identical signatures and yield an OpenTelemetry Span.

@asynccontextmanager
async def atrace(
    name: str,
    *,
    input: Any | None = None,
    kind: SpanKind = SpanKind.INTERNAL,
    attributes: dict | None = None,
    record_exception: bool = True,
    set_status_on_exception: bool = True,
    **extra_attributes: Any,
) -> AsyncGenerator[Span, None]

@asynccontextmanager
async def aspan(
    name: str,
    *,
    input: Any | None = None,
    kind: SpanKind = SpanKind.INTERNAL,
    attributes: dict | None = None,
    record_exception: bool = True,
    set_status_on_exception: bool = True,
    **extra_attributes: Any,
) -> AsyncGenerator[Span, None]

Parameter	Type	Default	Purpose
`name`	`str`	required	Span name.
`input`	`Any`	`None`	Input value recorded on the span.
`kind`	`SpanKind`	`SpanKind.INTERNAL`	OpenTelemetry span kind.
`attributes`	`dict`	`None`	Attributes set on the span at start.
`record_exception`	`bool`	`True`	Record a raised exception on the span.
`set_status_on_exception`	`bool`	`True`	Set span status to error when the block raises.
`**extra_attributes`	`Any`	N/A	Extra attributes passed as keyword arguments.

async with tracing.atrace("workflow", input=query):
    async with tracing.aspan("fetch_data") as s:
        data = await fetch()
        s.set_attribute(tracing.semconv.OBSERVATION_OUTPUT, str(len(data)))

`tracing.get_current_span()`

Return the currently active span, or a non-recording span when none is active. Use it to attach attributes from deep inside a call stack without threading the span through arguments.

def get_current_span() -> Span

Returns the active OpenTelemetry Span.

def inner_step():
    span = tracing.get_current_span()
    span.set_attribute("inner_data", "value")

`tracing.session()`

Group every trace recorded inside the block under one session id. Propagates process-wide, so auto-instrumented LLM calls and tool spans inside the block are grouped too. When sessions nest, the innermost wins.

@contextmanager
def session(session_id: str) -> Iterator[None]

Parameter	Type	Default	Purpose
`session_id`	`str`	required	Session id applied to every span created in the block.

Yields None.

with tracing.session("checkout-regression-001"):
    with tracing.trace("turn-1", input=prompt):
        run_agent(prompt)   # every span here carries the session id

Every trace already belongs to an ambient session that resolves from GATEWAY_SESSION_ID, or is auto-generated per process. tracing.session() overrides that default for the duration of the block. Use it for a named, replayable session.

Inside a live world session, with open_session(...) as s: or with s.trace_context(): works the same way with the world session’s id, and adds world_session_id trace metadata. See Trace inside a world session.

`tracing.tracing_context()` and `tracing.call_type_decorator()`

Tag spans with a call type, tags, or an environment without touching each span. tracing_context is a context manager; call_type_decorator builds a reusable decorator that sets the call type for a function.

@contextmanager
def tracing_context(
    *,
    call_type: str | None = None,
    tags: list[str] | None = None,
    environment: str | None = None,
    session_id: str | None = None,
) -> Generator[None, None, None]

def call_type_decorator(call_type: str) -> Callable[[F], F]

Parameter	Type	Default	Purpose
`call_type`	`str`	`None`	Call type applied to spans, for example `agent-call` or `judge-call`.
`tags`	`list[str]`	`None`	Tags applied to traces in the block.
`environment`	`str`	`None`	Environment label applied in the block.
`session_id`	`str`	`None`	Session id for the block. `tracing.session()` is the higher-level form.

tracing_context yields None. call_type_decorator returns a decorator that wraps sync and async functions.

with tracing.tracing_context(call_type="agent-call", tags=["gepa", "train"]):
    response = client.chat.completions.create(...)   # tagged automatically

judge = tracing.call_type_decorator("judge-call")

@judge
def score_answer(answer: str) -> float:
    ...   # LLM calls inside are tagged as judge-call

Three getters read the active context: tracing.get_current_call_type(), tracing.get_current_tags(), and tracing.get_current_environment(). Each returns the current value or None.

`gatewaysdk.identify()`

Attribute everything that follows (and the currently open span) to an end user. Sets the user for spans started in the calling context and stamps gateway.user.id on the in-flight span so the current trace is attributed immediately. Defined in gatewaysdk.tracing.identity and exported at the package root.

def identify(
    user_id: str,
    *,
    attributes: dict | None = None,
    display_name: str | None = None,
    email: str | None = None,
) -> None

Parameter	Type	Default	Purpose
`user_id`	`str`	required	End-user id. Stamped as `gateway.user.id`. A blank id is ignored.
`attributes`	`dict`	`None`	Profile facts merged into the user’s stored profile (for example `plan`, `account_value`). Values are stringified.
`display_name`	`str`	`None`	Display name for the user’s platform profile.
`email`	`str`	`None`	Email for the user’s platform profile.

Returns None. When any of attributes, display_name, or email is provided, the user’s platform profile is updated on a background thread, so identify() never blocks the request. Profile updates need GATEWAY_HOST, GATEWAY_PUBLIC_KEY, and GATEWAY_SECRET_KEY; span attribution works without them.

import gatewaysdk
import gatewaysdk.tracing as tracing

tracing.init()

with tracing.trace("checkout", input=cart):
    gatewaysdk.identify(
        "user-123",
        attributes={"plan": "enterprise", "account_value": "48000"},
    )
    result = run_checkout(cart)

Semantic conventions: `tracing.semconv`

Attribute-key constants for span.set_attribute(...). Set the gateway.* keys below to control how traces and observations appear in Surface Area. Reference a constant, not the raw string, so a key rename never breaks your code.

with tracing.trace("task", input=query) as span:
    span.set_attribute(tracing.semconv.SESSION_ID, "session-456")
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)

Trace-level attributes: set on the root span to shape the trace.

Constant	Key	Meaning
`semconv.TRACE_NAME`	`gateway.trace.name`	Display name of the trace.
`semconv.TRACE_INPUT`	`gateway.trace.input`	Trace-level input.
`semconv.TRACE_OUTPUT`	`gateway.trace.output`	Trace-level output.
`semconv.TRACE_METADATA`	`gateway.trace.metadata`	Free-form trace metadata.
`semconv.TRACE_TAGS`	`gateway.trace.tags`	Tags on the trace.
`semconv.TRACE_PUBLIC`	`gateway.trace.public`	Whether the trace is public.
`semconv.TRACE_METADATA_PREFIX`	`gateway.trace.metadata.`	Key prefix; attributes under it are hoisted into filterable trace metadata.

User, agent, and session: who and what the trace belongs to.

Constant	Key	Meaning
`semconv.USER_ID`	`gateway.user.id`	End-user id. Set by `identify()`, or per span.
`semconv.AGENT_ID`	`gateway.agent.id`	Agent id, stamped from `init(agent=...)`.
`semconv.AGENT_NAME`	`gateway.agent.name`	Agent display name.
`semconv.AGENT_VERSION`	`gateway.agent.version`	Agent version.
`semconv.SESSION_ID`	`gateway.session.id`	Session id grouping related traces.

Run tracking: links traces to a Surface Area run. Set automatically when a run is active.

Constant	Key	Meaning
`semconv.RUN_ID`	`gateway.run.id`	Experiment run id.
`semconv.RUN_NAME`	`gateway.run.name`	Experiment run name.

Environment and version: resource-level filters, usually set through init().

Constant	Key	Meaning
`semconv.ENVIRONMENT`	`gateway.environment`	Environment label (`production`, `staging`).
`semconv.RELEASE`	`gateway.release`	Release identifier.
`semconv.VERSION`	`gateway.version`	Application version or git SHA.

Context Hub linkage: stamped automatically when content is pulled from the Context Hub, correlating a trace with the prompts, agents, skills, and memory it used.

Constant	Key	Meaning
`semconv.GATEWAY_CONTEXT_PROMPT`	`gateway.context.prompt`	Most recent prompt repo handle used.
`semconv.GATEWAY_CONTEXT_AGENT`	`gateway.context.agent`	Most recent agent repo handle used.
`semconv.GATEWAY_CONTEXT_SKILL`	`gateway.context.skill`	Most recent skill repo handle used.
`semconv.GATEWAY_CONTEXT_MEMORY`	`gateway.context.memory`	Most recent memory repo handle used.
`semconv.GATEWAY_CONTEXT_ITEMS`	`gateway.context.items`	JSON array of every Context Hub item used in the execution.

Observation-level attributes: set on a child span or generation.

Constant	Key	Meaning
`semconv.OBSERVATION_TYPE`	`gateway.observation.type`	Observation type (`span`, `generation`, `event`, `tool`).
`semconv.OBSERVATION_INPUT`	`gateway.observation.input`	Observation input.
`semconv.OBSERVATION_OUTPUT`	`gateway.observation.output`	Observation output.
`semconv.OBSERVATION_METADATA`	`gateway.observation.metadata`	Free-form observation metadata.
`semconv.OBSERVATION_LEVEL`	`gateway.observation.level`	Severity level (`DEBUG`, `DEFAULT`, `WARNING`, `ERROR`).
`semconv.OBSERVATION_STATUS_MESSAGE`	`gateway.observation.status_message`	Human-readable status message.
`semconv.MODEL_NAME`	`gateway.observation.model.name`	Model name for a generation.
`semconv.MODEL_PARAMETERS`	`gateway.observation.model.parameters`	Model parameters for a generation.

Cost and timing metrics: GatewaySDK custom measures.

Constant	Key	Meaning
`semconv.GATEWAY_LLM_THINKING`	`gateway.llm.thinking`	Model reasoning or thinking content.
`semconv.GATEWAY_LLM_COST_USD`	`gateway.llm.cost_usd`	Estimated call cost in US dollars.
`semconv.GATEWAY_DURATION_MS`	`gateway.duration_ms`	Total duration in milliseconds.
`semconv.GATEWAY_DURATION_API_MS`	`gateway.duration_api_ms`	API-call duration in milliseconds.
`semconv.GATEWAY_NUM_TURNS`	`gateway.num_turns`	Number of turns in the interaction.
`semconv.GATEWAY_TOOL_IS_ERROR`	`gateway.tool.is_error`	Whether a tool call resulted in an error.

Two helper classes hold the valid values: semconv.ObservationType (SPAN, GENERATION, EVENT) and semconv.ObservationLevel (DEBUG, DEFAULT, WARNING, ERROR).

semconv also defines compatibility constants under the langfuse.*, gen_ai.*, and openinference.* namespaces. Auto-instrumentation and OTLP ingestion read those; you rarely set them by hand. Prefer the gateway.* keys above for your own spans.

`tracing.gateway_exporter()`

Build the Surface Area OTLP exporter explicitly, for passing to init(exporters=[...]) alongside your own exporters. init() creates one for you when credentials are present, so call this only when you need an explicit instance.

def gateway_exporter(
    *,
    host: str | None = None,
    public_key: str | None = None,
    secret_key: str | None = None,
    endpoint: str | None = None,
    **kwargs,
) -> GatewayOTLPExporter

Parameter	Type	Default	Purpose
`host`	`str`	`None`	Server URL. Falls back to `GATEWAY_HOST`.
`public_key`	`str`	`None`	Public key. Falls back to `GATEWAY_PUBLIC_KEY`.
`secret_key`	`str`	`None`	Secret key. Falls back to `GATEWAY_SECRET_KEY`.
`endpoint`	`str`	`None`	Full OTLP endpoint URL. Falls back to `GATEWAY_OTLP_ENDPOINT`, then `host` + `/api/public/otel/v1/traces`.
`**kwargs`	`Any`	N/A	Extra arguments forwarded to the underlying `OTLPSpanExporter`.

Returns a GatewayOTLPExporter. Raises ValueError when host, public key, or secret key is missing from both the arguments and the environment.

import gatewaysdk.tracing as tracing

# Reads GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY from the environment
exporter = tracing.gateway_exporter()

tracing.init(exporters=[exporter])

Environment variable	Purpose
`GATEWAY_HOST`	Server URL, for example `https://withgateway.ai`.
`GATEWAY_PUBLIC_KEY`	Project public key (`pk-lf-...`).
`GATEWAY_SECRET_KEY`	Project secret key (`sk-lf-...`).
`GATEWAY_OTLP_ENDPOINT`	Optional override for the OTLP endpoint path.

`tracing.instrument()` and the auto-instrumentation registry

Activate instrumentors by name. init(instrument_default=True) calls this with the default set; call it directly for manual control.

def instrument(
    names: list[str] | None = None,
    skip: list[str] | None = None,
    trace_config: TraceConfig | None = None,
) -> None

Parameter	Type	Default	Purpose
`names`	`list[str]`	`None`	Instrumentor names to enable. `None` enables the default set.
`skip`	`list[str]`	`None`	Instrumentor names to exclude.
`trace_config`	`TraceConfig`	`None`	OpenInference `TraceConfig` for these instrumentors. `init()` passes its own `trace_config` here.

Returns None. An installed AI library whose instrumentor is missing produces a loud warning rather than silent zero-telemetry.

import gatewaysdk.tracing as tracing

tracing.init(instrument_default=False)          # start with nothing instrumented
tracing.instrument(names=["openai", "anthropic"])

The registry ships the instrumentors below. Default set marks the seven enabled by instrument_default=True. An instrumentor activates only when its target library is importable.

Name (`names=` value)	Traces library	Default set	Install
`openai_agents`	`openai-agents` (imports as `agents`)	Yes	`gatewaysdk[tracing]`
`claude_agent_sdk`	`claude_agent_sdk`	Yes	Native: install `claude_agent_sdk`
`openai`	`openai`	Yes	`gatewaysdk[tracing]`
`anthropic`	`anthropic`	Yes	`gatewaysdk[tracing]` (on `anthropic` before 0.84, a built-in fallback traces it)
`litellm`	`litellm`	Yes	`gatewaysdk[tracing]`
`langchain`	`langchain`	Yes	`openinference-instrumentation-langchain`
`llama_index`	`llama_index`	Yes	`openinference-instrumentation-llama-index`
`google_adk`	`google.adk`	No	`openinference-instrumentation-google-adk`
`mistral`	`mistralai`	No	`openinference-instrumentation-mistralai`
`groq`	`groq`	No	`openinference-instrumentation-groq`
`bedrock`	`boto3`	No	`openinference-instrumentation-bedrock`
`vertexai`	`vertexai`	No	`openinference-instrumentation-vertexai`
`dspy`	`dspy`	No	`openinference-instrumentation-dspy`
`instructor`	`instructor`	No	`openinference-instrumentation-instructor`
`crewai`	`crewai`	No	`openinference-instrumentation-crewai`

The gatewaysdk[tracing] extra bundles only the OpenInference instrumentors for openai-agents, openai, anthropic, and litellm. It installs instrumentors only, never the libraries themselves (LiteLLM is traced once your app installs litellm). langchain and llama_index are in the default set but their instrumentor packages are not bundled: install openinference-instrumentation-langchain or openinference-instrumentation-llama-index for them to activate. Everything below the default set needs its own openinference-instrumentation-* package.

Setting OPENAI_AGENTS_DISABLE_TRACING=1 turns off the OpenAI Agents SDK tracing pipeline the openai_agents instrumentor rides on, so nothing from openai-agents reaches Surface Area. Leave it unset; the OpenAI trace-upload 401s it silences are harmless.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

`tracing.init()`

`tracing.shutdown()` and `tracing.flush()`

`tracing.trace()`

`tracing.span()`

`tracing.tool()`

`tracing.atrace()` and `tracing.aspan()`

`tracing.get_current_span()`

`tracing.session()`

`tracing.tracing_context()` and `tracing.call_type_decorator()`

`gatewaysdk.identify()`

Semantic conventions: `tracing.semconv`

`tracing.gateway_exporter()`

`tracing.instrument()` and the auto-instrumentation registry

​tracing.init()

​tracing.shutdown() and tracing.flush()

​tracing.trace()

​tracing.span()

​tracing.tool()

​tracing.atrace() and tracing.aspan()

​tracing.get_current_span()

​tracing.session()

​tracing.tracing_context() and tracing.call_type_decorator()

​gatewaysdk.identify()

​Semantic conventions: tracing.semconv

​tracing.gateway_exporter()

​tracing.instrument() and the auto-instrumentation registry

`tracing.init()`

`tracing.shutdown()` and `tracing.flush()`

`tracing.trace()`

`tracing.span()`

`tracing.tool()`

`tracing.atrace()` and `tracing.aspan()`

`tracing.get_current_span()`

`tracing.session()`

`tracing.tracing_context()` and `tracing.call_type_decorator()`

`gatewaysdk.identify()`

Semantic conventions: `tracing.semconv`

`tracing.gateway_exporter()`

`tracing.instrument()` and the auto-instrumentation registry