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

# How to integrate HoneyHive with Databricks Agent Bricks

> HoneyHive integration for Databricks Agent Bricks and MLflow Tracing. Export agent spans over OTLP with GenAI semantic conventions.

[Databricks Agent Bricks](https://docs.databricks.com/aws/en/generative-ai/agent-bricks/) agents emit [MLflow Tracing](https://docs.databricks.com/aws/en/mlflow3/genai/tracing/) spans. HoneyHive ingests those spans over OTLP/HTTP from environment variables on the agent runtime. No HoneyHive SDK code is required in the agent.

## Prerequisites

* Databricks workspace with Model Serving, or a local/notebook environment with `mlflow>=3.11`
* A HoneyHive project API key from [**Settings > Project > API Keys**](https://app.us.honeyhive.ai/settings/project/keys)

## Provider host and OTLP traces URL

HoneyHive routes OTLP ingestion through your deployment's **API host**. Replace `<provider-host>` with the hostname shown in your HoneyHive dashboard or API settings:

```text theme={null}
https://<provider-host>/opentelemetry/v1/traces
```

Example for a US production deployment:

```text theme={null}
https://api.dp1.us.prod.honeyhive.ai/opentelemetry/v1/traces
```

## Required environment variables

Set these on the agent process **before** any MLflow tracing starts:

| Variable                               | Value                                             | Why                                                                                                                                             |
| -------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`   | `https://<provider-host>/opentelemetry/v1/traces` | HoneyHive OTLP traces endpoint                                                                                                                  |
| `OTEL_EXPORTER_OTLP_HEADERS`           | `Authorization=Bearer <HH_API_KEY>`               | Authenticates to your HoneyHive project                                                                                                         |
| `OTEL_EXPORTER_OTLP_PROTOCOL`          | `http/protobuf`                                   | HoneyHive accepts OTLP/HTTP. MLflow defaults to gRPC                                                                                            |
| `MLFLOW_ENABLE_OTEL_GENAI_SEMCONV`     | `true`                                            | Translates MLflow attributes to `gen_ai.*` so HoneyHive can show model inputs, outputs, and tokens. Without this, those fields will not show up |
| `MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT` | `true`                                            | Sends traces to both Databricks MLflow and HoneyHive. Omit for HoneyHive-only export                                                            |
| `OTEL_SERVICE_NAME`                    | e.g. `databricks-agent-bricks`                    | Optional. Groups traces by service name in HoneyHive metadata                                                                                   |

<Warning>
  Always set `MLFLOW_ENABLE_OTEL_GENAI_SEMCONV=true`. Without it, prompts, completions, and token usage will not show up in HoneyHive.
</Warning>

`MLFLOW_ENABLE_OTEL_GENAI_SEMCONV` requires **MLflow 3.11+**. Dual export uses `MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT` (MLflow 3.4+). Databricks' OpenTelemetry export page currently shows `MLFLOW_ENABLE_DUAL_EXPORT`, which MLflow does not read - use the name above.

If both `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` and `OTEL_EXPORTER_OTLP_PROTOCOL` are set, the traces-specific variable wins. Unset any leftover `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc` so `http/protobuf` takes effect.

## Configure a Model Serving agent

Pass the variables through `environment_vars` on [`agents.deploy()`](https://docs.databricks.com/aws/en/mlflow3/genai/tracing/prod-tracing):

```python theme={null}
from databricks import agents

agents.deploy(
    model_name="catalog.schema.my_agent",
    model_version=1,
    environment_vars={
        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "https://<provider-host>/opentelemetry/v1/traces",
        "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer {{secrets/my_scope/honeyhive_api_key}}",
        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
        "MLFLOW_ENABLE_OTEL_GENAI_SEMCONV": "true",
        "MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT": "true",
        "OTEL_SERVICE_NAME": "databricks-agent-bricks",
    },
)
```

Use a Databricks secret with [`{{secrets/scope/key}}`](https://docs.databricks.com/aws/en/machine-learning/model-serving/store-env-variable-model-serving) instead of pasting the API key into a notebook.

For agents already deployed, add the same variables under **Serving > endpoint > Edit > Environment variables**, then redeploy or restart the endpoint.

## Notebook or local smoke test

`mlflow.openai.autolog()` creates the model span that carries inputs, outputs, and tokens under GenAI semconv:

```python theme={null}
import os

# Set before importing mlflow / creating spans
os.environ["MLFLOW_ENABLE_OTEL_GENAI_SEMCONV"] = "true"
os.environ["MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT"] = "true"
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = (
    "https://<provider-host>/opentelemetry/v1/traces"
)
os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "http/protobuf"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "Authorization=Bearer <HH_API_KEY>"
os.environ["OTEL_SERVICE_NAME"] = "databricks-agent-bricks"

import mlflow
from openai import OpenAI

mlflow.openai.autolog()
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Reply in one short sentence: what is observability?",
        }
    ],
    max_tokens=60,
)
print(response.choices[0].message.content)
```

Use an instrumented model call (as above) for inputs and outputs in HoneyHive. With GenAI semconv on, MLflow only exports I/O from recognized LLM calls. Values you set with `set_inputs` / `set_outputs` on a plain `mlflow.start_span` wrapper do not appear in HoneyHive.

Dual export still needs an MLflow tracking URI for the Databricks MLflow half (for example `mlflow.set_tracking_uri("databricks")` in a notebook, or the workspace default on Model Serving).

```bash theme={null}
pip install "mlflow>=3.11" openai opentelemetry-exporter-otlp
```

On Databricks, use `mlflow[databricks]` when you also want traces in the workspace MLflow UI.

## What HoneyHive receives

With GenAI semconv enabled, HoneyHive shows model inputs, outputs, token usage, and parent/child relationships for instrumented agent spans. Typical shape:

```text theme={null}
Session (agent invocation)
├── LLM Call (model span: tokens, latency, model name)
├── Tool Call (tool span: name, args, result)
├── LLM Call (follow-up reasoning)
└── Tool Call (final action)
```

<Note>
  Parent/child hierarchy is preserved via OTel parent span IDs, but spans from one agent invocation may currently appear across more than one HoneyHive session row. Filter by `service.name` and `source=otlp` in Traces to see the full run.
</Note>

## Verify traces in HoneyHive

1. Invoke the agent (or run the smoke test above).
2. Open [**Traces**](https://app.us.honeyhive.ai/traces/sessions) for the project tied to your API key.
3. Look for events with `source` set to `otlp` and metadata such as `telemetry.sdk.name=mlflow` and your `OTEL_SERVICE_NAME`.
4. Open a model span and confirm inputs, outputs, and token counts appear.

If traces do not appear:

1. Confirm the endpoint ends with `/opentelemetry/v1/traces` and uses your HoneyHive API host.
2. Confirm `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, and that `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` is unset or also `http/protobuf`.
3. Confirm `Authorization=Bearer <HH_API_KEY>` matches the target project.
4. Confirm `MLFLOW_ENABLE_OTEL_GENAI_SEMCONV=true` is set before the first span.
5. Confirm `MLFLOW_ENABLE_OTLP_EXPORTER` is not set to `false`.
6. Confirm the serving endpoint can reach HoneyHive over outbound HTTPS.

## Export modes

| Mode                      | Configuration                                                                     | Result                                    |
| ------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------- |
| Dual export (recommended) | OTLP endpoint + `MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT=true` + MLflow tracking URI | Traces in Databricks MLflow and HoneyHive |
| HoneyHive only            | OTLP endpoint only (dual export unset/false)                                      | Traces go to HoneyHive instead of MLflow  |
| MLflow only (default)     | No OTLP endpoint                                                                  | Traces stay in Databricks MLflow          |

## Related

<CardGroup cols={2}>
  <Card title="OpenTelemetry concepts" icon="network-wired" href="/v2/tracing/concepts">
    How HoneyHive stores OTLP traces and GenAI span attributes
  </Card>

  <Card title="Tracing introduction" icon="list-tree" href="/v2/tracing/introduction">
    Sessions, event types, and trace hierarchy in HoneyHive
  </Card>

  <Card title="Enrich your traces" icon="tags" href="/v2/tracing/enrich-traces">
    Add metadata, user properties, and feedback to traces
  </Card>

  <Card title="Custom spans" icon="code" href="/v2/tracing/custom-spans">
    Add HoneyHive spans around business logic in your application
  </Card>
</CardGroup>

## Resources

* [MLflow OpenTelemetry export](https://mlflow.org/docs/latest/genai/tracing/opentelemetry/export/)
* [MLflow GenAI semantic conventions](https://mlflow.org/docs/latest/genai/tracing/opentelemetry/genai-semconv/)
* [Databricks OpenTelemetry export](https://docs.databricks.com/aws/en/mlflow3/genai/tracing/integrations/open-telemetry)
* [Trace agents deployed on Databricks](https://docs.databricks.com/aws/en/mlflow3/genai/tracing/prod-tracing)
* [Store environment variables / secrets for Model Serving](https://docs.databricks.com/aws/en/machine-learning/model-serving/store-env-variable-model-serving)