Document observability span names for signals

sdk/guides/agent-server/openai-gateway.mdx

@@ -42,6 +42,18 @@
 
 Both are validated against the configured session API keys — there is no second credential system. When the server is configured without session keys, it remains unauthenticated just like the native agent-server API.
 
+OpenAI-compatible requests can also pass observability overrides for a new OpenHands conversation created behind the request:
+
+<Note>
+Observability override headers are available in OpenHands agent-server `v1.30.0` and later.
+</Note>
+
+- `X-OpenHands-Observability-Span-Name`: stable child span name to emit under the `conversation` root span
+- `X-OpenHands-Observability-Tags`: comma-separated span tags
+- `X-OpenHands-Observability-Metadata`: JSON object attached as trace metadata
+
+Use `X-OpenHands-Observability-Span-Name` when an observability backend, such as Laminar signals, should route or classify traces by a specific span name. The root span remains named `conversation`.
+
 ## Prepare a Profile
 
 OpenAI-compatible traffic is backed by an agent-server LLM profile. Create one with the native profile API first:
@@ -92,6 +104,9 @@
 curl -i "$AGENT_SERVER_URL/v1/chat/completions" \
   -H "Authorization: Bearer $SESSION_API_KEY" \
   -H "Content-Type: application/json" \
+  -H "X-OpenHands-Observability-Span-Name: pr_review_evaluation" \
+  -H "X-OpenHands-Observability-Tags: pr-review,evaluation" \
+  -H 'X-OpenHands-Observability-Metadata: {"repo":"OpenHands/software-agent-sdk"}' \
   -d "{
     \"model\": \"$OPENHANDS_MODEL\",
     \"messages\": [
@@ -127,6 +142,11 @@
     messages=[
         {"role": "user", "content": "Summarize this repository."},
     ],
+    extra_headers={
+        "X-OpenHands-Observability-Span-Name": "repo_summary",
+        "X-OpenHands-Observability-Tags": "repo-summary,docs",
+        "X-OpenHands-Observability-Metadata": '{"source":"docs-example"}',
+    },
 )
 completion = response.parse()
 conversation_id = response.headers["X-OpenHands-ServerConversation-ID"]
@@ -180,7 +200,7 @@
 </Tab>
 <Tab title="Chat UIs">
 
 For Open WebUI, LibreChat, Chatbot UI, and similar OpenAI-compatible frontends, configure a custom OpenAI provider with:
 
 - **Base URL**: `https://YOUR_AGENT_SERVER/v1`
 - **API key**: your agent-server session API key
@@ -272,17 +292,17 @@
       ]
     }
   ],
   "parallel_tool_calls": false,
   "previous_response_id": null,
   "status": "completed",
   "tool_choice": "none",
   "tools": [],
   "usage": {
     "input_tokens": 123,
     "input_tokens_details": { "cached_tokens": 0 },
     "output_tokens": 45,
     "output_tokens_details": { "reasoning_tokens": 0 },
     "total_tokens": 168
   }
 }
 ```

sdk/guides/observability.mdx

@@ -1,6 +1,6 @@
 ---
 title: Observability & Tracing
 description: Enable OpenTelemetry tracing to monitor and debug your agent's execution with tools like Laminar, MLflow, Honeycomb, or any OTLP-compatible backend.
 ---
 
 > A full setup example is available [below](#example-full-setup).
@@ -12,7 +12,7 @@
 - **[Laminar](https://laminar.sh/)** - AI-focused observability with trace inspection, signals, and browser session replay
 - **[MLflow](https://mlflow.org/)** - Open-source AI platform with tracing, evaluation, and LLM governance
 - **[Honeycomb](https://www.honeycomb.io/)** - High-performance distributed tracing
 - **Any OTLP-compatible backend** - Including Jaeger, Datadog, New Relic, and more
 
 The SDK automatically traces:
 - Agent execution steps
@@ -37,7 +37,7 @@
 That's it. Run your agent code normally and traces will be sent to Laminar automatically.
 
 <Note>
 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).
 </Note>
 
 For **self-hosted Laminar** deployments, configure the instance base URL and ports:
@@ -49,13 +49,13 @@
 export LMNR_GRPC_PORT=8001
 ```
 
 If you need help deciding between Laminar Cloud and self-hosted Laminar, see Laminar's official [hosting options](https://laminar.sh/docs/hosting-options).
 
 ### Why use Laminar with OpenHands?
 
 Laminar is especially useful when you want to understand how an agent behaved across one run or across many runs:
 
 - Inspect a single run in transcript, tree, or timeline views to see prompts, tool calls, outputs, and nested agent activity. See Laminar's guide to [viewing traces](https://laminar.sh/docs/platform/viewing-traces).
 - Watch browser automation alongside trace spans with [session replay for browser agents](https://laminar.sh/docs/tracing/browser-agent-observability).
 - Define [signals](https://laminar.sh/docs/signals/introduction) to classify failures, user friction, or success patterns across many traces.
 - Keep each OpenHands conversation grouped under a single session ID so multi-turn debugging is easier.
@@ -141,6 +141,31 @@
 
 In `tool.execute`, the tool calls are traced individually, such as `bash`, `file_editor`, or `task_tracker`.
 
+### Named Child Spans for Signals
+
+<Note>
+`observability_span_name` is available in OpenHands SDK `v1.30.0` and later.
+</Note>
+
+By default, each conversation trace starts with a root span named `conversation`. Keep that root span name stable for trace grouping. When you need an observability backend to route or classify a run by span name, set `observability_span_name` on the conversation. The SDK emits that value as an immediate child span under the `conversation` root.
+
+This is useful for Laminar signals or other backend rules that match a specific span name:
+
+```python icon="python" wrap
+conversation = Conversation(
+    agent=agent,
+    workspace=".",
+    observability_span_name="pr_review_evaluation",
+    observability_tags=["pr-review", "evaluation"],
+    observability_metadata={
+        "repo": "OpenHands/software-agent-sdk",
+        "workflow": "nightly-eval",
+    },
+)
+```
+
+Use stable, low-cardinality names such as `pr_review_evaluation`, `support_triage`, or `release_note_check`. Span names must be non-empty strings up to 128 characters and may contain letters, numbers, dots, underscores, colons, slashes, and hyphens.
+
 ## Configuration Reference
 
 ### Environment Variables
@@ -177,8 +202,8 @@
 
 The SDK supports both HTTP and gRPC protocols:
 
 - **`http/protobuf`** or **`otlp_http`** - HTTP with protobuf encoding (recommended for most backends)
 - **`grpc`** or **`otlp_grpc`** - gRPC with protobuf encoding (use only if your backend supports gRPC)
 
 ## Platform-Specific Configuration
 
@@ -215,24 +240,24 @@
 6. Save that key as the **Laminar Project API Key** in the Admin Console.
 7. Redeploy, then start a conversation in OpenHands.
 
 In OHE, environment variables with `LMNR_` and `LLM_` prefixes are automatically forwarded to the SDK runtime. That makes it possible to configure Laminar endpoint settings such as `LMNR_BASE_URL`, `LMNR_PROJECT_API_KEY`, and `LMNR_FORCE_HTTP`, as well as the LLM that powers Laminar's own AI features (chat-with-trace, SQL-with-AI, and [signals](https://laminar.sh/docs/signals/introduction)) via `LLM_PROVIDER`, `LLM_BASE_URL`, and `LLM_MODEL_SMALL|MEDIUM|LARGE`.
 
 `LLM_PROVIDER` accepts `gemini` (Laminar's default), `openai`, or `bedrock`. Set it to `openai` whenever you point `LLM_BASE_URL` at an OpenAI-compatible gateway (for example LiteLLM, OpenRouter, or vLLM), not just the public OpenAI API. For the full list of supported values, see Laminar's official [self-hosting configuration reference](https://laminar.sh/docs/self-hosting/configuration).
 
 For the full OHE flow with screenshots and configuration examples, see [Analytics in OpenHands Enterprise](/enterprise/analytics).
 
 ### MLflow Setup
 
 [MLflow](https://mlflow.org/) is an open-source AI platform that accepts OpenTelemetry traces out of the box, alongside evaluation and LLM governance capabilities.
 
 1. Start your MLflow tracking server:
 
 ```bash icon="terminal" wrap
 uvx mlflow server
 ```
 
 <Note>
 For other deployment options (pip, Docker Compose, etc.), see [Set Up MLflow Server](https://mlflow.org/docs/latest/genai/getting-started/connect-environment/).
 </Note>
 
 2. Configure the environment variables:
@@ -243,7 +268,7 @@
 export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
 ```
 
 Navigate to the MLflow UI (for example, `http://localhost:5000`), select the experiment, and open the **Traces** tab to view the recorded traces.
 
 ### Honeycomb Setup
 
@@ -338,7 +363,7 @@
 
 4. **Validate headers**: Check that authentication headers are properly URL-encoded.
 
 For Laminar-specific troubleshooting, see Laminar's official [tracing troubleshooting guide](https://laminar.sh/docs/tracing/troubleshooting).
 
 ## Troubleshooting
 
@@ -367,7 +392,7 @@
 
 **Solutions**:
 - Tracing has minimal overhead when properly configured
 - Disable tracing in development by unsetting environment variables
 - Use asynchronous exporters (default in most OTLP configurations)
 
 ## Example: Full Setup
@@ -432,5 +457,5 @@
 
 - **[Analytics in OpenHands Enterprise](/enterprise/analytics)** - Deploy Laminar inside OHE and send conversation traces automatically
 - **[Metrics Tracking](/sdk/guides/metrics)** - Monitor token usage and costs alongside traces
 - **[LLM Registry](/sdk/guides/llm-registry)** - Track multiple LLMs used in your application
 - **[Security](/sdk/guides/security)** - Add security validation to your traced agent executions