Instrument an agent

Instrumenting an agent takes one call to start tracing, plus a decorator or context manager wherever you want a span. Auto-instrumentation of LLM libraries is covered in Auto-instrumentation.

Initialize tracing with one call

Call tracing.init() once at startup. It configures an OpenTelemetry tracer provider, connects to Surface Area from your environment, and instruments installed AI libraries.

import gatewaysdk.tracing as tracing

tracing.init()

init() finds your Surface Area project from three environment variables. Set them before the process starts.

Variable	Purpose
`GATEWAY_HOST`	Surface Area 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 export endpoint

Copy the host and generate a key pair from your project’s Settings page.

The project Settings page. Copy the Host Name into GATEWAY_HOST, and create your pk-lf-… / sk-lf-… keys under the API keys tab.

With the three required variables set, the SDK builds the export URL automatically by appending /api/public/otel/v1/traces to the host. Override that path only with GATEWAY_OTLP_ENDPOINT or the gateway_endpoint parameter. See Export to Surface Area for details.

Pass credentials directly instead of environment variables

Provide the host and keys as arguments when the environment is not an option. Read them from your own configuration. Never hardcode secrets in source.

import os
import gatewaysdk.tracing as tracing

tracing.init(
    service_name="my-agent",
    environment="production",
    version="1.2.3",
    gateway_host=os.environ["GATEWAY_HOST"],
    gateway_public_key=os.environ["GATEWAY_PUBLIC_KEY"],
    gateway_secret_key=os.environ["GATEWAY_SECRET_KEY"],
)

Useful init parameters

init() is keyword-only.

Parameter	Type	Default	Description
`service_name`	`str`	`"gatewaysdk-tracing"`	Service name on the resource attributes
`environment`	`str`	`None`	Environment label (`production`, `staging`) for filtering traces
`version`	`str`	`None`	Application version or git SHA for tracking regressions
`agent`	`str` \| `dict` \| `AgentIdentity`	`None`	The agent this process runs as (stamped on every trace). See Metadata & identity
`instrument_default`	`bool`	`True`	Auto-instrument installed AI libraries
`debug`	`bool` \| `str`	`False`	Console logging level: `True`, `"DEBUG"`, `"INFO"`, `"WARNING"`, or `"ERROR"`

Pass debug="INFO" while you set tracing up. It logs the init summary, instrumentor activation, and export success or failure, without the full firehose of True.

Flush spans before the process exits

Spans are batched and exported in the background. Call tracing.shutdown() before the process exits so pending spans are flushed; otherwise a short-lived script can drop its last traces.

import atexit
import gatewaysdk.tracing as tracing

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

Call tracing.flush() to force export at a checkpoint without ending the session.

tracing.flush()

Trace a function with a decorator

Apply @tracing.trace to a function to capture its input and output as a span. The span name defaults to the function name.

import gatewaysdk.tracing as tracing

tracing.init()

@tracing.trace
def summarize(text: str) -> dict:
    return {"summary": text[:100]}

summarize("a long document...")

Pass a custom name, or turn off input or output capture, with keyword arguments.

@tracing.trace(name="custom-step", capture_output=False)
def process(data):
    do_work(data)

The decorator works on async functions with no change.

@tracing.trace
async def fetch_and_answer(query: str) -> str:
    return await answer(query)

Trace a block with a context manager

Use tracing.trace as a context manager to start a root span and set input and output explicitly. The block yields the OpenTelemetry span, so you can attach attributes to it.

import gatewaysdk.tracing as tracing

tracing.init()

with tracing.trace("answer-question", input=query) as span:
    result = run_agent(query)
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)

Nest tracing.span() calls to record sub-steps as child spans. Each child appears under the active trace in the call tree.

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)))

    with tracing.span("generate"):
        answer = generate(docs)

Record a tool or API call with tracing.tool(). It marks the span as a client call and adds a tool.name attribute.

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

Async code has matching context managers: tracing.atrace() for a root span and tracing.aspan() for a child span. They behave like their synchronous counterparts.

Errors are recorded automatically

The trace, span, and tool context managers record exceptions for you. If the block raises, the exception is recorded on the span and its status is set to error before the exception propagates.

import gatewaysdk.tracing as tracing

with tracing.span("operation"):
    do_work()  # If this raises, the span is marked as an error and the exception is recorded

To mark a span as failed without raising, call set_status on the yielded span. It is a standard OpenTelemetry Span.

from opentelemetry.trace import Status, StatusCode
import gatewaysdk.tracing as tracing

with tracing.span("operation") as s:
    result = do_work()
    if not result.success:
        s.set_status(Status(StatusCode.ERROR, f"Operation failed: {result.error}"))

A complete traced agent

Set your Surface Area connection

export GATEWAY_HOST="https://withgateway.ai"
export GATEWAY_PUBLIC_KEY="pk-lf-..."
export GATEWAY_SECRET_KEY="sk-lf-..."

Write the agent

import atexit
import gatewaysdk.tracing as tracing

tracing.init(service_name="faq-bot", environment="production")
atexit.register(tracing.shutdown)

@tracing.trace
def answer(question: str) -> str:
    with tracing.span("lookup", input=question) as s:
        facts = ["the sky is blue"]
        s.set_attribute(tracing.semconv.OBSERVATION_OUTPUT, str(facts))
    return f"Answer to {question!r}: {facts[0]}"

print(answer("why is the sky blue?"))

Run it and open the dashboard

Run the script, then open your project in Surface Area. The faq-bot trace appears with its nested lookup span.

Where to go next

Auto-instrumentation: capture LLM and agent-framework calls with no span code.
Metadata & identity: attach users, agents, tags, and custom metadata.
Sessions & traces: group related runs into one session.

Start here

Get Started

Use cases

Worlds

Evaluation & Replay

Tracing

Hooks

Initialize tracing with one call

Pass credentials directly instead of environment variables

Useful init parameters

Flush spans before the process exits

Trace a function with a decorator

Trace a block with a context manager

Errors are recorded automatically

A complete traced agent

Where to go next

​Initialize tracing with one call

​Pass credentials directly instead of environment variables

​Useful init parameters

​Flush spans before the process exits

​Trace a function with a decorator

​Trace a block with a context manager

​Errors are recorded automatically

​A complete traced agent

​Where to go next

Initialize tracing with one call

Pass credentials directly instead of environment variables

Useful init parameters

Flush spans before the process exits

Trace a function with a decorator

Trace a block with a context manager

Errors are recorded automatically

A complete traced agent

Where to go next