Skip to content

docs: add External Observability Platforms integration page - #700

Closed
rajshah4 wants to merge 3 commits into
OpenHands:mainfrom
rajshah4:docs/external-observability-platforms
Closed

docs: add External Observability Platforms integration page#700
rajshah4 wants to merge 3 commits into
OpenHands:mainfrom
rajshah4:docs/external-observability-platforms

Conversation

@rajshah4

@rajshah4 rajshah4 commented Aug 7, 2026

Copy link
Copy Markdown
Member

Summary

Add a customer-facing integration guide for redirecting OpenHands Enterprise conversation traces to an external OTLP-compatible observability platform (Langfuse, Honeycomb, Grafana Tempo, or any OTLP backend) instead of, or in addition to, the bundled Laminar.

  • New page: enterprise/integrations/observability-platforms.mdx
  • Nav: added enterprise/integrations/observability-platforms to the Enterprise → Integrations group in docs.json

Why

OHE ships with Laminar as its built-in tracing backend. Customers who already operate a different OTel-compatible observability platform want all conversation traces to flow into their platform with the same richness they get from Laminar today. This guide documents how to do that.

How it works

OHE's tracing layer is the Laminar Python SDK (lmnr), which wraps the OpenTelemetry SDK. The lmnr SDK respects standard OTEL_EXPORTER_OTLP_TRACES_* environment variables whenever LMNR_BASE_URL is not set. So the entire integration is an env-var change on the runtime pod — no source changes, no Helm chart patch.

The doc covers:

  • The LMNR_BASE_URLOTEL_EXPORTER_OTLP_TRACES_* switch (with a warning that LMNR_BASE_URL must be unset for the OTEL_* vars to take effect)
  • Helm (Kubernetes) and Replicated VM (Admin Console) configuration paths
  • Backend-specific config for Langfuse, Honeycomb, Tempo, and generic OTLP
  • The nested conversation trace tree that lands in the backend (conversation → conversation.run → agent.step → llm.completion + tool.execute), with LLM spans carrying gen_ai.* model/token/input/output attributes
  • Cost calculation and model-catalog registration
  • Optional OTel Collector tap for batching/retry/dual-sink, plus a keep-Laminar-and-mirror recipe
  • Troubleshooting accordion for the common failure modes

This was validated end-to-end against a self-hosted Langfuse v4 instance: traces emitted by the lmnr SDK inside a real OHE runtime pod landed in Langfuse with correct trace grouping, nesting, and observation-type classification (AGENT/CHAIN/GENERATION/TOOL).

Notes

  • The Replicated VM / Admin Console path is flagged honestly as limited — the Admin Console does not currently expose OTEL_EXPORTER_OTLP_TRACES_* fields directly, mirroring how the existing Analytics page notes the Admin Console limitation for LLM_* settings.
  • Cross-links to the existing Analytics page and the SDK Observability & Tracing guide are included.
  • The doc uses the same Mintlify components (Info, Warning, Note, Tabs/Tab, CardGroup/Card, Tree, AccordionGroup/Accordion) and voice as the existing enterprise integration pages (azure-devops, slack, external-postgres).

Related Linear ticket: OHE-3032

This PR was created by an AI agent (OpenHands) on behalf of rajshah4.

rajshah4 and others added 3 commits August 7, 2026 18:23
Add a customer-facing guide for redirecting OpenHands Enterprise conversation
traces to an external OTLP-compatible observability platform (Langfuse,
Honeycomb, Tempo, or any OTLP backend) instead of, or in addition to, the
bundled Laminar.

- New page: enterprise/integrations/observability-platforms.mdx
- Nav: added to the Enterprise > Integrations group in docs.json

Co-authored-by: openhands <openhands@all-hands.dev>
…tions nav

Co-authored-by: openhands <openhands@all-hands.dev>
@rajshah4
rajshah4 requested a review from juanmichelini August 7, 2026 23:30
@rajshah4

rajshah4 commented Aug 7, 2026

Copy link
Copy Markdown
Member Author

Closing this fork-based PR and reopening from a same-repo branch so the Mintlify preview bot fires (it does not trigger on fork-based PRs).

The new PR: #701

This comment was created by an AI agent (OpenHands) on behalf of rajshah4.

@rajshah4

rajshah4 commented Aug 7, 2026

Copy link
Copy Markdown
Member Author

Correction to my earlier comment — the new same-repo PR is #703: #703

This comment was created by an AI agent (OpenHands) on behalf of rajshah4.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant