Runback
Docs menuQuickstart: OpenTelemetry

    ↑↓ move ↵ open esc close

    Docs Start

    Quickstart: OpenTelemetry

    Point a standard OpenTelemetry exporter at Runback and record one OpenAI call as a run, with no Runback package in your code. About five minutes, plus a minute for the run to appear.

    Before you begin

    • A Runback account. Create one free.
    • Python 3.9 or later. Check with python3 --version.
    • An OpenAI API key, set as OPENAI_API_KEY.

    Using another language or framework? The same two variables work for any OpenTelemetry SDK that exports GenAI spans; OpenTelemetry recipes has tested setups for CrewAI, LlamaIndex, Pydantic AI and Google ADK.

    Steps

    1. Get a Runback key

      A key tells Runback which workspace a run belongs to. Use a Send only key: it can send runs and nothing else.In the app, open Settings › Keys and access › API key, keep Send only selected, select Generate API key and copy it. It is shown once, and starts rb_cloud_. Creating keys needs a workspace admin; whoever created the workspace is one.

      Checking your session…

    2. Install the OpenTelemetry packages

      Install the OpenTelemetry SDK, the HTTP exporter and an instrumentor for the OpenAI client. Any OpenTelemetry setup works; this one is tested against Runback.

      terminalShell
      pip install openai opentelemetry-sdk opentelemetry-exporter-otlp-proto-http openinference-instrumentation-openai
      Expected output

      pip ends with a Successfully installed line and no errors.

    3. Point the exporter at Runback

      Two standard OpenTelemetry variables send your traces to Runback, authenticated with your key. Replace the placeholder with the key from step 1 (if you signed in, it is already filled in).

      terminalShell
      export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://runback.dev/api/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=Bearer <RUNBACK_API_KEY>"
      Expected output

      Nothing is printed. To check, run env | grep OTEL_: it should list both variables, with your key in the second.

    4. Run an instrumented agent

      Save this as agent.py and run it with OPENAI_API_KEY set. It has no Runback import: an OpenAI call inside one named span, and the standard exporter setup, which reads the two variables from step 3. The span's name, quickstart-agent, becomes the run's name.

      agent.pyPython
      # agent.py: no Runback import. The exporter reads the two OTEL_ variables you exported.
import openai
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

tp = TracerProvider()
tp.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(tp)
OpenAIInstrumentor().instrument(tracer_provider=tp)

client = openai.OpenAI()
# The outer span's name is the run's name in Runback.
with trace.get_tracer("quickstart").start_as_current_span("quickstart-agent"):
    res = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Say hello in three words."}],
    )
print(res.choices[0].message.content)
tp.shutdown()  # flush the spans before the process exits
      terminalShell
      OPENAI_API_KEY=sk-... python agent.py
      Expected output

      The model's reply. Runback writes the run about a minute after the trace ends, so allow a minute before step 5.

    5. Check the run arrived

      Open Runs in the app. Your run is at the top, named quickstart-agent, about a minute after the agent finished. Open it to step through what the agent did.

    Troubleshooting

    You seeWhat it meansFix
    The exporter logs 401 or Failed to exportThe authorization header is missing or the key is wrong.Check step 3 ran in this terminal and the key starts rb_cloud_. Keep the space after Bearer.
    ModuleNotFoundError: No module named 'opentelemetry'The packages went into a different Python environment.Activate the environment from step 2, or install with the same python you run the agent with.
    openai.OpenAIError: Missing credentialsOPENAI_API_KEY is not set.Run the agent as OPENAI_API_KEY=sk-... python agent.py.
    The agent finished but the run is not in Runs yetRunback writes an OpenTelemetry run once the trace has been quiet for about a minute.Wait a minute and refresh. If it still isn't there, check the workspace name in the top right of the app is the one the key came from.

    What this path gives up

    OpenTelemetry sends spans after each call has run, so Runback can record and replay a model step but cannot stop a tool call before it happens, and redaction runs when the spans arrive rather than inside your process. If you need to stop calls, or redact inside your process, use the Python or TypeScript SDK.

    Next steps

    Last updated 2 Nov 2026.