> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/open-telemetry/configuration/backends.md).

# Backend Configuration

Config-time detail for Hermes's OTLP export — choosing a backend block, endpoint format rules, Collector wiring, and a setup runbook per backend.

[Backends & Routing](https://docs.pharos.ai/open-telemetry/hermes/backends.md) covers the concept — direct mode versus Collector mode, and what each backend carries. This page is the config-time counterpart: the backend block you declare at the top level of [`ORG_CONFIGS`](https://docs.pharos.ai/open-telemetry/configuration/org-configs.md), the rules every endpoint must satisfy, and how a Collector is wired. Each backend then has its own runbook.

***

## Choosing the Block

| You want                                                                                      | Declare                                                    | Notes                                                                                              |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Honeycomb, all three signals, no Collector                                                    | `honeycomb: { api_key, dataset }`                          | Endpoint and headers derived. Set `endpoint` for an EU instance.                                   |
| Splunk Observability Cloud, traces only                                                       | `splunk: { realm, access_token }` plus `signals: "traces"` | Endpoint derived from `realm`.                                                                     |
| Splunk with metrics, Datadog, Grafana Cloud, self-hosted LGTM, or fan-out to several backends | `collector: {}`                                            | Bare `{}` is the sidecar at `http://127.0.0.1:4317`; the vendor credential lives in the Collector. |
| Any other OTLP/gRPC endpoint                                                                  | `otlp: { endpoint, headers }`                              | You supply everything.                                                                             |
| Local inspection                                                                              | `file: { path }`                                           | JSONL on disk; not for production.                                                                 |

One block per document; a per-org block overrides it wholesale for that org. Two blocks at one level is a load error.

***

## Endpoint Format Rules

Every endpoint — derived or written — must be **`host:port`** or **scheme + host** (`https://api.example.com`). An OTLP URL that includes an HTTP path, such as `https://example.com/v1/traces`, is **rejected at load time** for that org rather than silently mishandled. Vendor setup pages often show path-suffixed HTTP URLs; those are for OTLP/HTTP, which Hermes does not speak directly.

Plaintext to a non-loopback endpoint needs `insecure: true` on the `collector` or `otlp` block; a loopback sidecar needs nothing.

***

## Collector Mode Wiring

With a `collector` block, Hermes sends every signal over OTLP/gRPC to the Collector, and the Collector's own exporters do the vendor-specific work. Two common wirings:

* **Sidecar** — a Collector container in the same ECS task or Container App, reached at the default `http://127.0.0.1:4317`. The AWS and Azure Terraform modules support this topology; the sidecar's exporter credentials (a Splunk HEC token, a Datadog API key, a Grafana Cloud token) are read from the extra keys you place in the same `collector` object, which Hermes itself ignores.
* **Service** — a Collector running as its own service, reached by DNS (`http://otel-collector:4317`, `insecure: true` on a private network, or TLS).

```mermaid
flowchart LR
  subgraph side["Sidecar (default)"]
    direction LR
    h1["Hermes"] -->|"OTLP/gRPC<br/>127.0.0.1:4317"| c1["Collector<br/>holds vendor credential"]
  end
  subgraph svc["Separate service"]
    direction LR
    h2["Hermes"] -->|"OTLP/gRPC<br/>otel-collector:4317<br/>insecure or TLS"| c2["Collector service<br/>holds vendor credential"]
  end
  c1 -->|"vendor exporter"| v1["Backend"]
  c2 -->|"vendor exporter"| v2["Backend"]
  style c1 fill:#37474f,stroke:#212121,color:#fff
  style c2 fill:#37474f,stroke:#212121,color:#fff
```

In both topologies `ORG_CONFIGS` carries only the `collector` block — the vendor API key or token is configured on the Collector's exporter, never on Hermes. A minimal Collector pipeline receives OTLP/gRPC on `4317`, batches, and exports to the vendor. For Prometheus-family metric stores add `deltatocumulative` on the metrics pipeline and raise `out_of_order_time_window` to 72h or more — see [Metric Temporality](https://docs.pharos.ai/open-telemetry/hermes/backends.md#metric-temporality).

***

## Service Identity Across Backends

Every runbook below uses the same two conventions:

* `service.name` identifies the surface — `hermes-iris`, `hermes-argus-rtem`, `hermes-argus-elf` — or, in a multi-org deployment, one `service_name` per org with the surface on the `hermes.channel` resource attribute (`iris`, `argus-rtem`, `argus-elf`). Pick one convention per deployment and filter on it consistently.
* The Salesforce org is `salesforce.org_id` on Iris spans and `salesforce.org.id` on Argus spans; cross-channel queries match both.

For a combined Iris + Argus deployment, route every surface to **one** dataset, environment, or tenant — spans for one request share a `trace_id` and only stitch within a single dataset.

***

## Per-Backend Runbooks

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🐝 Honeycomb</strong></td><td>Two API keys, dataset strategy, boards, triggers, SLOs, troubleshooting</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/backends/honeycomb.md">Honeycomb</a></td></tr><tr><td><strong>🟢 Splunk Observability Cloud</strong></td><td>Direct vs. Collector mode, realm and token, APM, dashboards, troubleshooting</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/backends/splunk.md">Splunk Observability Cloud</a></td></tr><tr><td><strong>🐶 Datadog</strong></td><td>Collector route, site selection, facets, dashboards, troubleshooting</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/backends/datadog.md">Datadog</a></td></tr><tr><td><strong>📈 Grafana Cloud &#x26; LGTM</strong></td><td>Cloud and self-hosted tracks, Alloy fan-out, temporality, troubleshooting</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/backends/grafana.md">Grafana Cloud &amp; LGTM</a></td></tr></tbody></table>

***

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🎯 Backends &#x26; Routing</strong></td><td>Direct vs. Collector mode and what each backend carries</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/backends.md">Backends &amp; Routing</a></td></tr><tr><td><strong>🧩 ORG_CONFIGS Reference</strong></td><td>The full block and per-org field reference</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/org-configs.md">ORG_CONFIGS Reference</a></td></tr><tr><td><strong>🩺 Operations &#x26; Validation</strong></td><td>Health checks, validation checklist, troubleshooting</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/operations.md">Operations &amp; Validation</a></td></tr></tbody></table>
