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

# OpenHands

> Export the OpenTelemetry trace variables for OpenHands to ship agent session traces — conversation runs, agent steps, tool calls, and LLM requests — to Sazabi as searchable logs.

[All OpenHands integration capabilities](https://docs.sazabi.com/catalogs/integrations/openhands)

## About

Ship OpenHands agent session traces to Sazabi using the OpenHands Software Agent SDK's built-in OpenTelemetry exporter. The OpenHands CLI runs on the same SDK, so one setup covers CLI sessions and your own SDK programs, with no code changes.

Every span becomes a searchable log: `conversation.run`, `conversation.send_message`, and `agent.step` spans, tool-call spans named after the tool action, and LLM request spans with the model and token usage. An exception recorded on a span arrives as its own error log that keeps the span's trace and span IDs.

> [!WARNING]
>
> Span inputs and outputs can include prompt, response, and tool content. Review what your OpenHands version records before you enable tracing for your team.

## Prerequisites

* OpenHands CLI (`openhands`) or a Python program built on `openhands-sdk`
* Your Sazabi intake URL, shown above — open the log source and copy the **Intake URL** from its setup screen (the public key is embedded in the URL)

## Set up in the dashboard

**Step 1**

### Export the trace exporter variables

OpenHands turns tracing on when `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set; there is no separate OpenHands telemetry setting. Add the following to the shell profile (or launcher script) that starts OpenHands:

```bash title="~/.zshrc" theme={"system"}
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<your intake URL>/v1/traces"
```

Replace `<your intake URL>` with the intake URL shown above, keeping the `/v1/traces` path. The public key is part of the URL, so `OTEL_EXPORTER_OTLP_TRACES_HEADERS` is not needed.

Keep `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf`. Without it, OpenHands sends traces over gRPC, which the intake URL does not accept.

Leave `LMNR_PROJECT_API_KEY` and `LMNR_BASE_URL` unset in this shell. When either is set, OpenHands sends traces to Laminar instead.

**Step 2**

### Start a new OpenHands session

OpenHands reads these variables when it starts. Open a new shell (so the exports are present) and start `openhands` or your SDK program; telemetry begins with that session, not one that is already running. When OpenHands runs the agent in a Docker or remote sandbox, it passes the `OTEL_*` variables through.

## Set up with the CLI

You can also register the OpenHands log source with the [Sazabi CLI](https://docs.sazabi.com/reference/cli.md) (installed and authenticated — see [CLI reference](https://docs.sazabi.com/reference/cli/log-sources.md)).

Registering the source mints the same intake URL the dashboard shows above (the public key is embedded in its hostname):

```bash theme={"system"}
sazabi log-sources create openhands --mode manual
```

The command prints the intake URL for the new source — copy the whole URL and point OpenHands at it using the configuration shown above. Run `sazabi log-sources get <log-source-id>` at any time to reprint the endpoint, or `sazabi log-sources list` to see every log source in the project.

## Verify

Start OpenHands from a shell that has the exports and run one task. OpenHands sends spans in batches every few seconds and on exit. Open the [Intake page](https://docs.sazabi.com/guides/instrument/intake.md) in the Sazabi dashboard and confirm logs from the **OpenHands** source appear within a minute or two.

From the CLI, `sazabi logs ask "How many OpenHands log lines arrived in the last 15 minutes?"` confirms rows are arriving, and `sazabi logs ask "Show the latest OpenHands agent.step logs"` lists agent steps. In a thread, search by trace ID to see every span from one conversation run.

## Troubleshooting

**No logs after restarting** — Confirm the exports are present in the shell that started OpenHands (`env | grep OTEL_`), that `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` is `http/protobuf`, and that the endpoint ends in `/v1/traces`.

**Traces still go to Laminar** — `LMNR_PROJECT_API_KEY` or `LMNR_BASE_URL` is set in that shell. Unset it and start a new OpenHands session.

**OpenHands CLI stops with `observe() got an unexpected keyword argument 'rollout_entrypoint'`** — OpenHands CLI 1.16.0 from PyPI fails when tracing is on. This is an OpenHands packaging issue, not a Sazabi one. Until a fixed release ships, install the CLI from source as described in the [OpenHands CLI repository](https://github.com/OpenHands/OpenHands-CLI), then start a new session.

**OpenHands Cloud conversations are missing** — This source covers OpenHands processes you run yourself. Conversations that run in OpenHands Cloud are not collected.

**No metrics** — OpenHands exports traces only. There are no OpenHands metrics or logs signals for Sazabi to store.

## Further reading

> [card] [OpenHands SDK observability](https://docs.openhands.dev/sdk/guides/observability)
>
> OpenHands' reference for its OpenTelemetry tracing variables.

> [card] [Intake](https://docs.sazabi.com/guides/instrument/intake.md)
>
> See per-source ingestion volume and health.

> [card] [Log sources](https://docs.sazabi.com/catalogs/log-sources.md)
>
> Browse the full log source catalog.


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