How do I set up tracing for OpenHands?

Rius traces OpenHands with three OTLP environment variables and no plugin, so you add no code to your OpenHands script. Create an API key with the Send telemetry scope, set the variables, run your agent, and the conversation appears in the trace list within a few seconds. Each conversation is one trace with its model calls and tool calls. Tokens and cost are included for SDK scripts using Claude or GPT-4o, and are missing for OpenAI Responses API models and for web-app conversations.

How it works

OpenHands’ Software Agent SDK already traces every conversation with OpenTelemetry. When it finds the OTEL variables in the environment, it turns tracing on by itself and sends plain OTLP to the endpoint you set. Pointing it at Rius needs no extra package.

One conversation becomes one trace:

• The conversation, each agent step, and the model and tool calls inside it.
• For each model call, the model, prompt and answer, plus tokens and cost where OpenHands reports usage.
• For each tool call (terminal, file editor, finish), its input and output, including a terminal command and its exit code.
• The conversation id as the Rius session, so a multi-turn conversation groups together.

OpenHands is the one coding agent in the Coding agents family that skips the Rius plugin. It also differs from the plugin on content: the plugin sends prompts and output only from folders you enable, while OpenHands always sends them. There is no folder to turn on, so tracing starts when the variables are set.

Set it up

1. Install the OpenHands SDK in a Python 3.12 or newer environment.
2. In the Rius console at https://console.rius-glassflow.com, open Settings → API keys and create a key with the Send telemetry scope. The key is shown once. If you have no account yet, the Quickstart covers sign-up.
3. Set the three variables in the environment where your script runs:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.eu.console.rius-glassflow.com/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20ri_..."

Each detail matters, because when one is off Rius never sees the spans and the agent runs on as if nothing happened:

• Protocol: the exporter defaults to gRPC, and Rius takes http/protobuf.
• Path: write the full /v1/traces path. The exporter only adds it when the URL has no path at all.
• Header encoding: the value is URL-encoded, so the space after Bearer is %20.
• Laminar variables: any LMNR_* variable takes precedence over the OTEL settings. Run env | grep LMNR_ and expect no output.

4. Name the agent and, if you want, the user when you create the conversation. Rius otherwise names the agent after the script file, and conversations land in the anonymous row on the Users page:

conversation = Conversation(
    agent=agent,
    workspace=".",
    user_id="dev@example.com",
    observability_metadata={"agent.name": "fib-writer"},
)

5. Start the script from its own directory. Running it by absolute path puts the full path in the service column.
6. Run the agent, then open the trace list in the console. The conversation appears under the agent name you set, within a few seconds.

If you run the OpenHands web app in Docker, the variables do not go on the app container, which never forwards OTEL_* to the agent’s sandbox. Pass the same three values in OH_AGENT_SERVER_ENV instead, a JSON object of extra variables for every sandbox. Web-app conversations show under the agent openhands-agent-server.

For OpenHands Enterprise, bundled analytics must be off, because while it is on the OTEL_* variables are ignored. The OpenHands guide has the Helm and VM install steps.

What you get

• A first session in the trace list. Each conversation is one trace with its steps, model calls and tool calls, and the terminal command with its exit code.
• Tokens and cost where OpenHands reports them. SDK scripts using Claude or GPT-4o come through in full. OpenAI Responses API models such as GPT-4.1 and GPT-5 have no token data. Web-app conversations have every call with its prompt and answer, but no tokens or cost, because their model calls are streamed.
• Users and sessions. The user_id you pass shows the conversation under that user, and the conversation id groups multi-turn runs.
• Alerts. The pre-defined Tool Loop alert is on in every workspace, and Consistent Error Pattern catches a rotated model key, so either can reach a Slack, email or webhook channel you attach.

If no trace shows up, check the protocol, the full path, the %20 in the header and any LMNR_* variable. For web-app runs, check that the values are in OH_AGENT_SERVER_ENV.

When something else fits

• OpenHands Cloud takes no custom environment variables, so it cannot send to Rius. Use the OpenHands SDK with the three variables instead.
• To trace Claude Code, Codex (beta) or Cursor (beta), install the Rius plugin and enable tracing per folder, as described in Coding agents.

Related