From 8e8f3c1a24f6194fd75d9187aa0827f2c298e8f1 Mon Sep 17 00:00:00 2001 From: enyst Date: Mon, 6 Jul 2026 18:06:23 +0000 Subject: [PATCH 1/2] docs: add Agent Canvas Docker observability guidance Co-authored-by: openhands --- .../agent-canvas/backend-setup/docker.mdx | 42 +++++++++++++++++++ openhands/usage/agent-canvas/setup.mdx | 2 + sdk/guides/observability.mdx | 8 ++++ 3 files changed, 52 insertions(+) diff --git a/openhands/usage/agent-canvas/backend-setup/docker.mdx b/openhands/usage/agent-canvas/backend-setup/docker.mdx index 99454964..91c780d5 100644 --- a/openhands/usage/agent-canvas/backend-setup/docker.mdx +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -54,11 +54,53 @@ Configuration is passed via `-e` flags on `docker run`: | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. | +| `LMNR_PROJECT_API_KEY` | Enables SDK tracing to Laminar. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Sends SDK traces to an OTLP-compatible backend such as Jaeger, Honeycomb, Datadog, or New Relic. | +| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | OTLP transport protocol, usually `http/protobuf` or `grpc`. | +| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Optional authentication headers for your OTLP backend. | + +For the full tracing reference, see [Observability & Tracing](/sdk/guides/observability). The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set `LOCAL_BACKEND_API_KEY` to a strong secret. +## Enable SDK Tracing + +The Docker image starts the OpenHands Agent Server inside the container, and the Agent Server uses the OpenHands SDK. To enable tracing for Agent Canvas conversations, pass the same Laminar or OpenTelemetry environment variables to `docker run`. + +### Laminar example + +```bash icon="terminal" wrap +mkdir -p ~/projects ~/.openhands + +docker run -it --rm \ + -p 8000:8000 \ + -e LMNR_PROJECT_API_KEY="your-laminar-api-key" \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest +``` + +### OTLP collector example + +If your collector runs on your host machine, remember that `localhost` inside the container means the Agent Canvas container itself. Use `host.docker.internal` on Docker Desktop, or add the host gateway alias on Linux. + +```bash icon="terminal" wrap +mkdir -p ~/projects ~/.openhands + +docker run -it --rm \ + --add-host=host.docker.internal:host-gateway \ + -p 8000:8000 \ + -e OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://host.docker.internal:4317" \ + -e OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc" \ + -v ~/.openhands:/home/openhands/.openhands \ + -v ~/projects:/projects \ + ghcr.io/openhands/agent-canvas:latest +``` + +If the collector runs in another container, put both containers on the same Docker network and use the collector's container or Compose service name in the endpoint, for example `http://jaeger:4317`. + ## Connect from the Frontend Start the frontend separately and point it at the container: diff --git a/openhands/usage/agent-canvas/setup.mdx b/openhands/usage/agent-canvas/setup.mdx index f05cd008..6fc6dcf2 100644 --- a/openhands/usage/agent-canvas/setup.mdx +++ b/openhands/usage/agent-canvas/setup.mdx @@ -85,6 +85,8 @@ description: Install and run Agent Canvas via npm or Docker. | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | | `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets | + + To enable SDK tracing from the Docker image, pass `LMNR_*` or `OTEL_*` variables with `-e`. See [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker#enable-sdk-tracing) and [Observability & Tracing](/sdk/guides/observability). diff --git a/sdk/guides/observability.mdx b/sdk/guides/observability.mdx index 3386e55e..5b8e87db 100644 --- a/sdk/guides/observability.mdx +++ b/sdk/guides/observability.mdx @@ -36,6 +36,10 @@ export LMNR_PROJECT_API_KEY="your-laminar-api-key" That's it. Run your agent code normally and traces will be sent to Laminar automatically. + +If you run Agent Canvas with Docker, set the Laminar or OTEL variables on the Agent Canvas container. See [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker#enable-sdk-tracing) for `docker run` examples and Docker networking notes. + + For Laminar-specific walkthroughs, see the official docs for [OpenHands SDK tracing](https://laminar.sh/docs/tracing/integrations/openhands-sdk), [session replay for browser agents](https://laminar.sh/docs/tracing/browser-agent-observability), [viewing traces](https://laminar.sh/docs/platform/viewing-traces), and [signals](https://laminar.sh/docs/signals/introduction). @@ -272,6 +276,10 @@ export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="grpc" Access the Jaeger UI at `http://localhost:16686`. + +If OpenHands is running inside an Agent Canvas Docker container, do not use `http://localhost:4317` for a collector running on your host. Use `http://host.docker.internal:4317` on Docker Desktop, add a host gateway alias on Linux, or put both containers on the same Docker network and use the collector's service name. + + ### Generic OTLP Collector For other backends, use their OTLP endpoint: From e77a2864eb43552c20081f0808bb2a7a890d8a10 Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 6 Jul 2026 18:48:26 +0000 Subject: [PATCH 2/2] docs: clarify Agent Canvas observability boundaries Co-authored-by: openhands --- .../agent-canvas/backend-setup/docker.mdx | 56 +++++++++++++++++-- sdk/guides/observability.mdx | 2 +- 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/openhands/usage/agent-canvas/backend-setup/docker.mdx b/openhands/usage/agent-canvas/backend-setup/docker.mdx index 91c780d5..7a7996c6 100644 --- a/openhands/usage/agent-canvas/backend-setup/docker.mdx +++ b/openhands/usage/agent-canvas/backend-setup/docker.mdx @@ -52,10 +52,10 @@ Configuration is passed via `-e` flags on `docker run`: | Variable | Purpose | |----------|---------| | `PORT` | Ingress port inside the container (default `8000`). Map it with `-p :`. | -| `LOCAL_BACKEND_API_KEY` | API key for the server. Auto-generated and persisted if not set. | +| `LOCAL_BACKEND_API_KEY` | API key for the Agent Canvas backend API. Auto-generated and persisted if not set. | | `OH_SECRET_KEY` | Secret used to protect stored settings and secrets. | -| `LMNR_PROJECT_API_KEY` | Enables SDK tracing to Laminar. | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Sends SDK traces to an OTLP-compatible backend such as Jaeger, Honeycomb, Datadog, or New Relic. | +| `LMNR_PROJECT_API_KEY` | Enables built-in SDK tracing to Laminar. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Enables built-in SDK trace export to an OTLP-compatible backend such as Jaeger, Honeycomb, Datadog, New Relic, or Grafana Tempo. | | `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | OTLP transport protocol, usually `http/protobuf` or `grpc`. | | `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Optional authentication headers for your OTLP backend. | @@ -65,9 +65,57 @@ For the full tracing reference, see [Observability & Tracing](/sdk/guides/observ The agent server can execute arbitrary shell commands inside the container. If exposing it beyond localhost, set `LOCAL_BACKEND_API_KEY` to a strong secret. +## View Backend Conversations and Events + +Agent Canvas includes a backend API for conversations and events. This is built in and uses the same `LOCAL_BACKEND_API_KEY` that the UI uses. It is separate from observability tracing. + +Use this API if you need to inspect conversations stored in the Docker backend, including a conversation that is not visible in the left panel. + +```bash icon="terminal" wrap +# Use the value you passed as LOCAL_BACKEND_API_KEY. +# If you did not set one, check the container logs for the generated key. +export LOCAL_BACKEND_API_KEY="your-backend-api-key" + +curl -sS \ + -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \ + http://localhost:8000/api/conversations/search +``` + +After you find a conversation ID, inspect recent events: + +```bash icon="terminal" wrap +export CONVERSATION_ID="conversation-id" + +curl -sS \ + -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \ + "http://localhost:8000/api/conversations/$CONVERSATION_ID/events/search?limit=20" +``` + + +Observability exporters do not backfill old conversations. Set up tracing before starting the conversations you want to observe. + + +## Built-in Tracing vs. External Backends + +Built into Agent Canvas Docker: + +- The OpenHands Agent Server runs inside the container and uses the OpenHands SDK. +- The SDK automatically emits traces when Laminar or OTEL environment variables are present. +- The backend conversation and event APIs are available behind `LOCAL_BACKEND_API_KEY`. + +Not built into Agent Canvas Docker: + +- A Prometheus `/metrics` endpoint for scraping agent execution metrics. +- A Grafana connector that authenticates into Agent Canvas or makes conversations appear in the left panel. +- Hosted Laminar, Jaeger, Tempo, Prometheus, Grafana, Datadog, Honeycomb, or New Relic services. Those are external observability systems you run or subscribe to separately. + +The SDK also has built-in token, cost, and latency tracking for SDK-based integrations; see [Metrics Tracking](/sdk/guides/metrics). That is different from service metrics scraped by Prometheus. + +For Grafana, the typical tracing setup is to export OTLP traces from Agent Canvas to Grafana Tempo or another trace backend, then add that backend as a Grafana data source. Prometheus is useful for metrics, but the SDK tracing exporter sends traces, not Prometheus scrape metrics. + ## Enable SDK Tracing -The Docker image starts the OpenHands Agent Server inside the container, and the Agent Server uses the OpenHands SDK. To enable tracing for Agent Canvas conversations, pass the same Laminar or OpenTelemetry environment variables to `docker run`. +The Docker image starts the OpenHands Agent Server inside the container, and the Agent Server uses the OpenHands SDK. To enable tracing for Agent Canvas conversations, pass Laminar or OpenTelemetry environment variables to `docker run`. ### Laminar example diff --git a/sdk/guides/observability.mdx b/sdk/guides/observability.mdx index 5b8e87db..77eae7e9 100644 --- a/sdk/guides/observability.mdx +++ b/sdk/guides/observability.mdx @@ -37,7 +37,7 @@ export LMNR_PROJECT_API_KEY="your-laminar-api-key" That's it. Run your agent code normally and traces will be sent to Laminar automatically. -If you run Agent Canvas with Docker, set the Laminar or OTEL variables on the Agent Canvas container. See [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker#enable-sdk-tracing) for `docker run` examples and Docker networking notes. +If you run Agent Canvas with Docker, set the Laminar or OTEL variables on the Agent Canvas container. The built-in part is SDK trace instrumentation and OTLP export; Laminar, Jaeger, Grafana Tempo, and other collectors are external systems you configure separately. See [Docker Backend](/openhands/usage/agent-canvas/backend-setup/docker#built-in-tracing-vs-external-backends) for `docker run` examples, backend API inspection, and Docker networking notes.