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

# Honeycomb

> Connect Honeycomb so OpenSRE can query traces

## Overview

OpenSRE queries Honeycomb for distributed traces — identifying slow spans, high-error services, and query patterns correlated with incidents.

## Prerequisites

* Honeycomb account (classic or environments-based)
* API key with query access

## Setup

### Option 1: Interactive CLI

```bash theme={null}
opensre integrations setup honeycomb
```

You will be prompted for the API key, dataset (defaults to `__all__`), and API URL.

### Option 2: Environment variables

Add to your `.env`:

```bash theme={null}
HONEYCOMB_API_KEY=your-api-key
HONEYCOMB_DATASET=your-dataset      # optional, defaults to __all__
HONEYCOMB_API_URL=https://api.honeycomb.io  # optional
```

| Variable            | Default                    | Description                                              |
| ------------------- | -------------------------- | -------------------------------------------------------- |
| `HONEYCOMB_API_KEY` | —                          | **Required.** Honeycomb API key                          |
| `HONEYCOMB_DATASET` | `__all__`                  | Dataset to query (classic) or `__all__` for environments |
| `HONEYCOMB_API_URL` | `https://api.honeycomb.io` | Override for EU region or proxies                        |

### Option 3: Persistent store

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "honeycomb-prod",
      "service": "honeycomb",
      "status": "active",
      "credentials": {
        "api_key": "your-api-key",
        "dataset": "__all__",
        "base_url": "https://api.honeycomb.io"
      }
    }
  ]
}
```

Store credentials use `base_url` (not `HONEYCOMB_API_URL`).

### Option 4: Multi-instance

For multiple Honeycomb environments or keys, use [multi-instance](/docs/platform/multi-instance-integrations) with `HONEYCOMB_INSTANCES`:

```bash theme={null}
HONEYCOMB_INSTANCES='[
  {"name":"prod","tags":{"env":"prod"},"credentials":{"api_key":"...","dataset":"__all__","base_url":"https://api.honeycomb.io"}},
  {"name":"eu","tags":{"env":"eu"},"credentials":{"api_key":"...","dataset":"__all__","base_url":"https://api.eu1.honeycomb.io"}}
]'
```

When `HONEYCOMB_INSTANCES` is set, the single-instance `HONEYCOMB_*` variables are ignored.

## Credentials

1. In Honeycomb, go to **Account** → **API Keys**
2. Click **Create API Key**
3. Set the environment and enable **Query Data** permission
4. Copy the key

<Tip>
  Use `__all__` as the dataset to query across all datasets in an environment. For EU accounts, set `HONEYCOMB_API_URL=https://api.eu1.honeycomb.io`.
</Tip>

## Tools

| Tool                     | Use it for                                   |
| ------------------------ | -------------------------------------------- |
| `query_honeycomb_traces` | Trace and span groups related to an incident |

Arguments the planner commonly supplies:

| Argument             | Default                 | Description                    |
| -------------------- | ----------------------- | ------------------------------ |
| `dataset`            | from config (`__all__`) | **Required** at tool call time |
| `service_name`       | —                       | Filter spans for a service     |
| `trace_id`           | —                       | Look up a specific trace       |
| `time_range_seconds` | `3600`                  | Lookback window                |
| `limit`              | `20`                    | Result cap                     |

## Verify

```bash theme={null}
opensre integrations verify honeycomb
```

Expected output:

```
SERVICE     SOURCE      STATUS   DETAIL
honeycomb   local env   passed   Connected to https://api.honeycomb.io (environment production) and queried dataset __all__
```

## Troubleshooting

| Symptom                         | Fix                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**            | Confirm the API key is correct and has Query Data permission                                         |
| **Dataset not found**           | Use `__all__` or check the exact dataset name in Honeycomb                                           |
| **EU account unreachable**      | Set `HONEYCOMB_API_URL=https://api.eu1.honeycomb.io`                                                 |
| **Multiple Honeycomb accounts** | Use `HONEYCOMB_INSTANCES` — see [Multi-instance integrations](/docs/platform/multi-instance-integrations) |

## Security

* Use a dedicated **read-only** API key scoped to query access.
* Store the API key in `.env` or your secret manager — not in source control.