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

# Analytics

> Deploy Laminar for trace analysis in OpenHands Enterprise.

This guide walks you through enabling Laminar in OpenHands Enterprise (OHE) so conversations automatically send traces for observability and analysis.

For SDK-level tracing concepts, OTEL environment variables, and non-Laminar backends, see [Observability & Tracing](https://docs.openhands.dev/sdk/guides/observability.md).

## Who This Is For

This guide is for users who want to deploy Laminar alongside OpenHands Enterprise and inspect traces from Enterprise conversations.

## Why Laminar in OHE?

Laminar helps you understand what your OpenHands deployment is doing in production:

* Inspect prompts, tool calls, answers, and nested agent behavior in Laminar's [trace views](https://laminar.sh/docs/platform/viewing-traces).
* Use [session replay for browser agents](https://laminar.sh/docs/tracing/browser-agent-observability) when conversations drive browser automation.
* For Helm installs, define [signals](https://laminar.sh/docs/signals/introduction) to classify failures, measure outcomes, and monitor recurring patterns across many traces.

For more information on evaluating skills, see [Evaluating Agent Skills](https://www.openhands.dev/blog/evaluating-agent-skills).

## Prerequisites

Before you begin, complete the [Quick Start guide](https://docs.openhands.dev/enterprise/quick-start.md).

## Enable Analytics

> [tab] VM Install (Admin Console)
>
> > [!NOTE]
> >
> > VM installs currently support trace collection, but do not support Laminar signals. The Admin Console configures the Laminar Project API Key only; the installer sets the remaining Laminar connection values automatically.
>
> You should see an **Analytics Configuration** section on the application configuration page.
>
> Check the **Enable Analytics** box to have the installer set up and configure Laminar for analytics.
>
> ![Configure Analytics](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-configure-analytics.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=61ddfbb42a3007cd4ba5a3919422ad45)

> [tab] Kubernetes (Helm)
>
> If you deployed OpenHands Enterprise into your own Kubernetes cluster using Helm, enable Laminar in your `values.yaml` override file.
>
> ```yaml theme={null}
> laminar:
>   enabled: true
>   global:
>     # Set to "aws" or "gcp" to match your cluster.
>     cloudProvider: "aws"
>
>   frontend:
>     ingress:
>       enabled: true
>       hostname: "analytics.<your-base-domain>"
>       tls:
>         enabled: true
>         secretName: "laminar-frontend-tls"
>     env:
>       # Must equal the frontend hostname above; the Keycloak callback URL is derived from it.
>       nextauthUrl: "https://analytics.<your-base-domain>"
>       nextPublicUrl: "https://analytics.<your-base-domain>"
>     extraEnv:
>       - name: AUTH_KEYCLOAK_ID
>         valueFrom:
>           secretKeyRef:
>             name: keycloak-realm
>             key: client-id
>       - name: AUTH_KEYCLOAK_SECRET
>         valueFrom:
>           secretKeyRef:
>             name: keycloak-realm
>             key: client-secret
>       - name: AUTH_KEYCLOAK_ISSUER
>         value: "https://auth.<your-base-domain>/realms/allhands"
>
>   appServer:
>     # Use an app-server ingress on GCP or other L7 ingress setups.
>     ingress:
>       enabled: true
>       hostname: "laminar-api.<your-base-domain>"
>       tls:
>         enabled: true
>         secretName: "laminar-app-server-tls"
>
>     # On AWS, use a Network Load Balancer instead of appServer.ingress
>     # if your runtimes send traces directly over TCP.
>     loadBalancer:
>       enabled: false
> ```
>
> Keep `laminar.enabled: false` until your ingress, TLS, and storage class settings match your cluster.

## Deploy

> [tab] VM Install (Admin Console)
>
> OpenHands will begin deploying. You can expect the deployment status to transition from **Missing** to **Unavailable** to **Ready**. This typically takes 10-15 minutes.
>
> ![Deployment in progress](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-deploy-in-progress.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=780d6367d09a1f8e7aeb9a60ba7c25d8)
>
> Click **Details** next to the deployment status to monitor individual resources. Resources shown in orange are still deploying, so wait until all resources are ready.
>
> ![Deployment status details](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-deployment-status-details.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=6a8ea4ee3f42125611e75ef380d8bf46)

> [tab] Kubernetes (Helm)
>
> Apply your updated `values.yaml` override file:
>
> ```bash theme={null}
> helm upgrade openhands oci://registry.replicated.com/openhands/openhands \
>   --namespace openhands \
>   --values values.yaml
> ```
>
> Wait for the Laminar workloads, ingress, and TLS resources to become ready.

## Access the Laminar UI

Once the deployment status shows **Ready**, navigate to the Laminar frontend URL:

* VM install: `https://analytics.<your-base-domain>`
* Kubernetes install: the hostname configured in `laminar.frontend.ingress.hostname`

Click the **Continue with Keycloak** button:

![Laminar Keycloak Auth](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-keycloak-auth.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=cbdeecc21b920b579ad3da3eb291e9d1)

> [!NOTE]
>
> For the **Continue with Keycloak** flow to succeed, the Keycloak client referenced by the `keycloak-realm` Secret must allow the Laminar callback. Its **Valid Redirect URIs** must include `https://analytics.<your-base-domain>/api/auth/callback/keycloak` and its **Web Origins** must include `https://analytics.<your-base-domain>`.
>
> These must match the hostname in `laminar.frontend.ingress.hostname`. If your DNS uses the simple (single-level) layout — for example `analytics.<your-base-domain>` rather than a nested `analytics.app.<your-base-domain>` — confirm the redirect URI matches that hostname exactly, otherwise Keycloak rejects the login with an `Invalid parameter: redirect_uri` error.

If you want more background on Laminar Cloud versus self-hosting outside OHE, see Laminar's official [hosting options](https://laminar.sh/docs/hosting-options).

## Create a Laminar Project

Create a project in the Laminar UI:

![Laminar Create Project](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-create-project.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=e3ef12290be1f26646b0b4d0f10c3fd9)

Once a project has been created, Laminar is ready to listen for traces.

![Laminar Listen Traces](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-listen-traces.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=d564233d383f473d2c14e52d4e171f57)

## Create an Ingest-Only API Key

Always use ingest-only API keys when deploying OHE.

Ingest-only keys are recommended because OHE only needs permission to write traces. They cannot be used to read trace data.

![Configure Laminar Ingest Only Key](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-ingest-only-key.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=70a9a09fd9a67f8f082c44bf13eab7a7)

## Set the Laminar Project API Key

This is the same `LMNR_PROJECT_API_KEY` described in the [SDK observability guide](https://docs.openhands.dev/sdk/guides/observability.md).

> [tab] VM Install (Admin Console)
>
> Set the ingest-only key as the **Laminar Project API Key** in the Admin Console configuration.
>
> ![Configure Laminar Project API Key](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-configure-key.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=1cb28a8e99ad1da3fe10a926a993f450)
>
> Click **Save config**.

> [tab] Kubernetes (Helm)
>
> Create a Kubernetes Secret for the ingest-only project key:
>
> ```bash theme={null}
> kubectl create secret generic lmnr-project-api-key \
>   --namespace openhands \
>   --from-literal=LMNR_PROJECT_API_KEY=<your-ingest-only-key>
> ```
>
> Create a Secret for the Laminar app-server base URL:
>
> ```bash theme={null}
> kubectl create secret generic lmnr-base-url \
>   --namespace openhands \
>   --from-literal=LMNR_BASE_URL=https://laminar-api.<your-base-domain>
> ```
>
> Then reference those Secrets from your `values.yaml` override file:
>
> ```yaml theme={null}
> laminar:
>   enabled: true
>   apiKeyFromSecret:
>     name: lmnr-project-api-key
>     key: LMNR_PROJECT_API_KEY
>   baseUrlFromSecret:
>     name: lmnr-base-url
>     key: LMNR_BASE_URL
>   forceHttp: true
> ```
>
> If your self-hosted Laminar app server exposes a non-default HTTP port, set `laminar.httpPort`.

## Configure Runtime Environment Variables

> [tab] VM Install (Admin Console)
>
> VM installs configure analytics through the Admin Console. After analytics is enabled and the Laminar Project API Key is saved, the installer automatically configures:
>
> ```yaml theme={null}
> LMNR_BASE_URL: "http://laminar-app-server-service"
> LMNR_PROJECT_API_KEY: "<your-ingest-only-key>"
> LMNR_FORCE_HTTP: "true"
> LMNR_HTTP_PORT: "8000"
> ```
>
> The Admin Console does not currently expose `LLM_*` settings for Laminar AI features. VM installs currently send traces to Laminar, but do not support Laminar signals.

> [tab] Kubernetes (Helm)
>
> In OHE, environment variables whose names start with `LMNR_` or `LLM_` are forwarded to the SDK runtime. This lets you configure Laminar ingestion settings and the LLM settings used for Laminar-backed workflows.
>
> For example, you can point the runtime at the managed Laminar endpoint and use an ingest-only project key:
>
> ```yaml theme={null}
> LMNR_BASE_URL: "https://laminar-api.<your-base-domain>"
> # Ingest-only API key, not a read-capable secret:
> LMNR_PROJECT_API_KEY: ""
> LMNR_FORCE_HTTP: "true"
> ```
>
> The chart sets `LMNR_PROJECT_API_KEY`, `LMNR_BASE_URL`, `LMNR_FORCE_HTTP`, and `LMNR_HTTP_PORT` from the `laminar` values above. If you need to override one of them directly, set it under the top-level `env` values in your `values.yaml`.
>
> You can also control which LLM Laminar uses for its AI features — chat-with-trace, SQL-with-AI, and [signals](https://laminar.sh/docs/signals/introduction) — by forwarding the standard `LLM_*` variables. Add these values under the top-level `env` values:
>
> ```yaml theme={null}
> env:
>   LLM_PROVIDER: "openai"
>   LLM_API_KEY: "<your-openai-or-gateway-key>"
>   LLM_BASE_URL: "https://llm-proxy.<your-base-domain>"
>   LLM_MODEL_SMALL: "gpt-5.4-mini"
>   LLM_MODEL_MEDIUM: "gpt-5.4-mini"
>   LLM_MODEL_LARGE: "gpt-5.5"
> ```
>
> `LLM_PROVIDER` accepts `gemini` (Laminar's default), `openai`, or `bedrock`, and `LLM_MODEL_SMALL` / `LLM_MODEL_MEDIUM` / `LLM_MODEL_LARGE` are optional per-tier model overrides. Set `LLM_PROVIDER` 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. Set `LLM_API_KEY` for `gemini`, `openai`, and OpenAI-compatible gateways; use AWS credentials instead for `bedrock`.
>
> For the full set of supported values, see Laminar's official [self-hosting configuration reference](https://laminar.sh/docs/self-hosting/configuration).

## Deploy Updated Configuration

Deploy the configuration change after setting the Laminar Project API Key.

> [tab] VM Install (Admin Console)
>
> Click **Deploy** in the Admin Console.
>
> ![Laminar Deploy Again](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-deploy-again.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=3567ab8beee56ba2166657b3e26efd4c)
>
> For a VM install walkthrough, watch the recap:
>
> <video controls src="https://github.com/user-attachments/assets/0cdf1625-3246-4388-a989-765f00d33ffb" />

> [tab] Kubernetes (Helm)
>
> Apply your updated `values.yaml` override file:
>
> ```bash theme={null}
> helm upgrade openhands oci://registry.replicated.com/openhands/openhands \
>   --namespace openhands \
>   --values values.yaml
> ```

Wait for the deployment to complete.

## Start a Conversation

Navigate to the OpenHands UI at `https://app.<your-base-domain>`. Start a new conversation and try a prompt.

![Start a Conversation](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-openhands-conversation.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=b56b9978b4f3dd5b1112ce0b39371ee8)

Your conversations will now automatically send traces to Laminar.

![Laminar Trace](https://mintcdn.com/allhandsai/cSWtxxDdwY5-Y2BK/enterprise/images/laminar-trace.png?fit=max\&auto=format\&n=cSWtxxDdwY5-Y2BK\&q=85\&s=067d1eb77207dabd5647cfe0a522af27)

## Query Traces with SQL

Use [Laminar's CLI](https://laminar.sh/docs/platform/cli) for expected read-only access to trace data. The CLI authenticates as your Laminar user, not with the ingest-only project API key configured for OpenHands trace collection.

For Laminar Cloud:

```bash theme={null}
lmnr-cli login
lmnr-cli sql query "SELECT * FROM traces ORDER BY start_time DESC LIMIT 1"
```

For self-hosted Laminar, point the CLI at your frontend and API before logging in:

```bash theme={null}
export LMNR_FRONTEND_URL=https://example.com
export LMNR_BASE_URL=https://api.example.com
export LMNR_HTTP_PORT=8000

lmnr-cli login
lmnr-cli sql query "SELECT * FROM traces ORDER BY start_time DESC LIMIT 1"
```

For scripts that need to call the SQL endpoint directly, send a `POST` request to `/v1/sql/query` with a read-capable Laminar project API key:

```bash theme={null}
curl https://api.lmnr.ai/v1/sql/query \
  -H "Authorization: Bearer $LMNR_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT * FROM traces ORDER BY start_time DESC LIMIT 10"}'
```

For self-hosted Laminar, replace `https://api.lmnr.ai` with your Laminar API endpoint.

## What to Do Next in Laminar

Once traces are flowing, use Laminar's official docs to go deeper:

* [Viewing Traces](https://laminar.sh/docs/platform/viewing-traces) to inspect a single conversation in transcript, tree, or timeline views.
* For Helm installs, [Signals](https://laminar.sh/docs/signals/introduction) to extract structured outcomes or failure modes across many traces.
* [Session replay for browser agents](https://laminar.sh/docs/tracing/browser-agent-observability) to debug browser-based automations.
* [Observability for OpenHands Software Agent SDK](https://laminar.sh/docs/tracing/integrations/openhands-sdk) for the OpenHands-specific tracing model.

## Next Steps

> [card] [Observability & Tracing](https://docs.openhands.dev/sdk/guides/observability.md)
>
> Learn the full OpenHands tracing model, OTEL configuration options, and non-Laminar backends.

> [card] [Prompting Best Practices](https://docs.openhands.dev/openhands/usage/tips/prompting-best-practices.md)
>
> Get more reliable traces by improving the prompts you give your agents.

> [card] [Contact Support](https://openhands.dev/contact)
>
> Reach out to the OpenHands team for deployment assistance or questions.


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