> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing

> Exact signatures, parameters, and runnable examples for the gatewaysdk tracing API: init, the span decorators, sessions, identify, semantic-convention keys, the exporter, and the auto-instrumentation registry.

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](/worlds) is built from, and a run against a world is traced like any other execution.

<Info>
  How-to lives in the [Tracing guide](/tracing): [instrument an agent](/tracing/setup), [group runs into sessions](/tracing/sessions), [attach metadata and identity](/tracing/metadata), [auto-instrument LLM libraries](/tracing/auto-instrumentation), and [export to Surface Area](/tracing/export).
</Info>

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.

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
import gatewaysdk.tracing as tracing

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

<Info>
  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.
</Info>

## `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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
# 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`.

```python theme={null}
@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`. |

```python theme={null}
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`.

```python theme={null}
@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. |

```python theme={null}
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`.

```python theme={null}
@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. |

```python theme={null}
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.

```python theme={null}
def get_current_span() -> Span
```

**Returns** the active OpenTelemetry `Span`.

```python theme={null}
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.

```python theme={null}
@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`.

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

<Info>
  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.
</Info>

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/sessions#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.

```python theme={null}
@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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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`).

<Info>
  `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.
</Info>

## `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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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](/tracing/auto-instrumentation#older-client-versions) 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` |

<Info>
  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.
</Info>

<Info>
  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.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.