> 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/org-configs.md).

# ORG\_CONFIGS Reference

Reference for the ORG\_CONFIGS schema — the top-level export block, per-org Salesforce auth and tuning, plus state-store selectors and process-wide env vars.

Hermes takes essentially all of its configuration from environment variables, and secrets — Salesforce private keys, backend tokens — come **only from your cloud's secrets vault** (Secrets Manager on AWS, Key Vault on Azure), never from the container image or a checked-in file. The single most important variable is `ORG_CONFIGS`: the JSON document that names the export destination and describes every org Hermes talks to. The whole document is the one secret you store.

***

## Document Shape

```json
{
  "honeycomb": { "api_key": "hcaik_…" },
  "signals": "traces,metrics,logs",
  "resource_attributes": { "deployment.environment": "prod" },
  "session": { "max_spans_per_trace": 5000 },
  "orgs": [
    {
      "org_id": "00Dxx0000000001AAA",
      "service_name": "hermes-sales",
      "sf": {
        "login_url": "https://login.salesforce.com",
        "client_id": "3MVG9…",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n…\n-----END RSA PRIVATE KEY-----",
        "username": "hermes-integration@example.com"
      },
      "hermes": {
        "iris": {},
        "rtem": { "channels": ["LoginEventStream", "ApiEventStream"] },
        "elf":  { "event_types": ["Login", "ApexExecution"], "parallelism": 2 },
        "redaction_enabled": true
      }
    }
  ]
}
```

The export destination is declared **once, at the top level**, as exactly **one** backend block. Everything Hermes can derive — endpoints, auth headers, dataset names — it derives, so you write only what is yours. A single Hermes process runs **1 to 20 orgs**, each with its own Salesforce credentials and Iris/RTEM/ELF tuning.

***

## Top-Level Export Configuration

Exactly one of the five backend blocks is present; **its presence selects the backend**. There is no `backend` string field.

| Block       | Fields                                            | What Hermes derives                                                                                                                                                                                                                                                                                        |
| ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collector` | `endpoint`, `headers`, `insecure`                 | `endpoint` defaults to `http://127.0.0.1:4317`, the sidecar address. Set it (for example `http://otel-collector:4317`, with `insecure: true`) only when the Collector runs as a separate service. Other keys in this object are for the Collector's own exporters and are ignored by Hermes.               |
| `honeycomb` | `api_key`, `dataset`, `endpoint`, `headers`       | `endpoint` defaults to `https://api.honeycomb.io` (set it for an EU instance); `dataset` defaults to the org's `service_name`; the `x-honeycomb-team` / `x-honeycomb-dataset` headers are built at startup.                                                                                                |
| `splunk`    | `realm` (**required**), `access_token`, `headers` | `endpoint` = `ingest.<realm>.observability.splunkcloud.com:443`; the `x-sf-token` header is built at startup. The direct path accepts **traces only** — `signals` resolves to `traces` when omitted; naming metrics or logs is warned and those exports fail. Use `collector` for Splunk metrics and logs. |
| `otlp`      | `endpoint` (**required**), `headers`, `insecure`  | Nothing — a generic OTLP/gRPC destination (New Relic, Dynatrace, LogScale, a self-hosted receiver). You supply the endpoint and any auth header.                                                                                                                                                           |
| `file`      | `path` (**required**)                             | Nothing. Writes OTLP JSONL locally for inspection; local and debugging use only.                                                                                                                                                                                                                           |

Alongside the block:

| Key                           | Purpose                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| `signals`                     | CSV allowlist of `traces`, `metrics`, `logs` shared by every org. Empty means all three.                |
| `resource_attributes`         | Shared base map of OTel resource attributes; each org's own map is merged over it, org winning per key. |
| `session.max_spans_per_trace` | Deployment-wide default for the session-trace span-count cap (see below).                               |

Custom `headers` are accepted only on `collector` and `otlp`; the Honeycomb and Splunk headers are derived from `api_key` / `access_token`. If you need a custom header on a Honeycomb or Splunk export, use an `otlp` block with the vendor endpoint and build the auth header yourself, or route through a Collector.

***

## Per-Org Fields

| Field                                                  | Required               | Purpose                                                                                                                                                                                                                                             |
| ------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org_id`                                               | Yes                    | Salesforce org ID, 15- or 18-character. Partition key for state stores; emitted as `salesforce.org_id`.                                                                                                                                             |
| `sf.client_id`                                         | Yes                    | External Client App consumer key.                                                                                                                                                                                                                   |
| `sf.private_key`                                       | Yes                    | RSA private key in PEM form, newlines escaped as `\n`. The PEM text itself — the whole document is what lives in the vault.                                                                                                                         |
| `sf.username`                                          | Yes                    | Integration user Hermes authenticates as (JWT Bearer).                                                                                                                                                                                              |
| `sf.login_url`                                         | No                     | `https://login.salesforce.com` (default) or `https://test.salesforce.com` for sandboxes.                                                                                                                                                            |
| `service_name`                                         | From two orgs, **yes** | Per-org OTel `service.name` — the key your dashboards, datasets, and queries are built on. Defaults to `hermes` for a single org; never derived from `org_id`. In a multi-org document an org without it is skipped.                                |
| `signals`                                              | No                     | Per-org override of the shared allowlist.                                                                                                                                                                                                           |
| `resource_attributes`                                  | No                     | Extra resource attributes merged over the shared map. Exporter-managed keys (`service.name`, `salesforce.org_id`, `hermes.channel`, `salesforce.bridge.mapping_version`) cannot be overridden.                                                      |
| `collector` / `honeycomb` / `splunk` / `otlp` / `file` | No                     | A per-org backend block, same fields and derivations as the top level, replacing the shared destination **wholesale** for this org. Rare: one org exporting elsewhere, or a lab org writing to `file`.                                              |
| `hermes.iris`                                          | No                     | Object; presence (even `{}`) enables the Iris runtime. When none of `iris`, `rtem`, `elf` is present, all three are enabled.                                                                                                                        |
| `hermes.iris.event_topic`                              | No                     | Pub/Sub topic; default `/event/pharos__Log_Event__e`.                                                                                                                                                                                               |
| `hermes.rtem`                                          | No                     | Object; presence enables Argus RTEM.                                                                                                                                                                                                                |
| `hermes.rtem.channels`                                 | No                     | Channel list. Omitted or empty = every channel the effective mapping names (16 in the default); `*` is never subscribable.                                                                                                                          |
| `hermes.rtem.max_streams`                              | No                     | Reserved stream limit per org; default `1`.                                                                                                                                                                                                         |
| `hermes.rtem.fetch_batch_size`                         | No                     | Pub/Sub fetch size; default `100`.                                                                                                                                                                                                                  |
| `hermes.elf`                                           | No                     | Object; presence enables Argus ELF.                                                                                                                                                                                                                 |
| `hermes.elf.poll_interval_seconds`                     | No                     | Daily discovery loop interval; default `1800`.                                                                                                                                                                                                      |
| `hermes.elf.hourly_poll_interval_seconds`              | No                     | Hourly discovery loop interval; default `1800`. Requires the Event Monitoring hourly add-on and a dedup store (`ARGUS_DEDUP_STORE`).                                                                                                                |
| `hermes.elf.disable_hourly`                            | No                     | `true` turns the Hourly loop off for this org; default `false`.                                                                                                                                                                                     |
| `hermes.elf.event_types`                               | No                     | ELF event types to ingest. Empty = every type the mapping declares (34 in the default).                                                                                                                                                             |
| `hermes.elf.parallelism`                               | No                     | Concurrent ELF workers per org; default `2`.                                                                                                                                                                                                        |
| `hermes.elf.backfill`                                  | No                     | `"off"` (default), `"full-window"`, or `"from:YYYY-MM-DD"`.                                                                                                                                                                                         |
| `hermes.elf.async_link_threshold_hours`                | No                     | Nest-vs-fork threshold for async events; default `18`. Needs `ARGUS_ORIGIN_STORE` for cross-process consistency.                                                                                                                                    |
| `hermes.mapping_override_path`                         | No                     | Path to this org's pipeline-config override YAML (Iris merges, Argus replaces — see [Mapping & Redaction](https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md)).                                                           |
| `hermes.self_metrics`                                  | No                     | Object; presence (even `{}`) pushes Hermes's own metrics to this org's backend. `interval_seconds` defaults to `30`. See [Self-Instrumentation Metrics](https://docs.pharos.ai/open-telemetry/configuration/self-metrics.md).                       |
| `hermes.redaction_enabled`                             | No                     | Activates the curated redaction set; default `false`.                                                                                                                                                                                               |
| `hermes.redaction_overrides`                           | No                     | Per-field `{field, strategy[, replacement]}` list, applied regardless of `redaction_enabled`. Strategies `replace` (default), `drop`, `hash`, `mask`. A bad entry skips the org.                                                                    |
| `hermes.trace_stitching.mode`                          | No                     | `off` (default) or `iris_map`. Any other value skips the org.                                                                                                                                                                                       |
| `hermes.trace_stitching.map_ttl_hours`                 | No                     | Trace-map entry TTL; default `48`.                                                                                                                                                                                                                  |
| `hermes.session_unification.enabled`                   | No                     | Cross-channel session umbrella on Iris, RTEM, and ELF. **Default `true`**; `false` opts the org out on all three. Requires `AuthSession` read, granted by the `Hermes_Argus` permission set.                                                        |
| `hermes.session.max_spans_per_trace`                   | No                     | Span-count cap that starts a new session-trace epoch. Precedence: this field (including an explicit `0` = disabled) → top-level `session.max_spans_per_trace` → `HERMES_SESSION_MAX_SPANS_PER_TRACE` → built-in `5000`. Heavy-span orgs: 2000–3000. |

***

## Examples

**Three orgs behind a sidecar Collector**, each with its own `service_name`, sharing the destination and merging resource attributes:

```json
{
  "collector": {},
  "signals": "traces,metrics,logs",
  "resource_attributes": { "deployment.environment": "prod" },
  "orgs": [
    { "org_id": "00Dxx0000000001AAA", "service_name": "hermes-sales",
      "sf": { "client_id": "…", "private_key": "…", "username": "hermes@sales.example.com" },
      "hermes": { "iris": {}, "rtem": {}, "elf": {} } },
    { "org_id": "00Dxx0000000002AAA", "service_name": "hermes-service",
      "resource_attributes": { "business.unit": "service" },
      "sf": { "client_id": "…", "private_key": "…", "username": "hermes@service.example.com" },
      "hermes": { "rtem": {}, "elf": { "event_types": ["Login", "API", "ApexExecution"] } } },
    { "org_id": "00Dxx0000000003AAA", "service_name": "hermes-sandbox",
      "sf": { "login_url": "https://test.salesforce.com", "client_id": "…", "private_key": "…", "username": "hermes@sandbox.example.com" },
      "hermes": { "iris": {} } }
  ]
}
```

**Per-org override to a local file** — a lab org writing JSONL while the rest of the document exports to Splunk:

```json
{
  "splunk": { "realm": "us1", "access_token": "…" },
  "signals": "traces",
  "orgs": [
    { "org_id": "00Dxx0000000001AAA", "service_name": "hermes-prod", "sf": { "…": "…" } },
    { "org_id": "00Dxx0000000009AAA", "service_name": "hermes-lab",
      "file": { "path": "/tmp/hermes-lab.jsonl" },
      "sf": { "…": "…" } }
  ]
}
```

***

## Load-Time Errors

| Error                                                                                                  | Scope                                                                 |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Two or more top-level backend blocks                                                                   | The **whole document** fails to load — fan-out is the Collector's job |
| An org with no export configuration after the shared block is applied                                  | That **org** is skipped with a warning; the others keep running       |
| Two backend blocks on one org                                                                          | That org                                                              |
| `splunk` without `realm`, `otlp` without `endpoint`, `file` without `path`                             | That org                                                              |
| An endpoint carrying an HTTP path (`https://…/v1/traces`) — endpoints are `host:port` or scheme + host | That org                                                              |
| `service_name` missing when the document declares more than one org                                    | That org                                                              |
| Unknown `trace_stitching.mode`, bad `redaction_overrides` entry, unrecognised `elf.backfill` value     | That org                                                              |

If every org is skipped the load fails outright, so a single-org deployment with a broken block does not start silently. Search the startup log for `skipping org due to config error`.

***

## Migrating from the Flat Shape

Earlier documents declared the destination per org under `hermes.otel.*`. That shape still parses for one release, with a deprecation warning naming the org, and an org that keeps it wins over the shared block. Mixing it with any new-shape field on the same org (`service_name`, `signals`, `resource_attributes`, or a backend block) is a load-time error — migrate an org whole.

| Deprecated field                                      | Write instead                                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `hermes.otel.backend`                                 | Nothing — the block you declare is the backend                                                                   |
| `hermes.otel.endpoint`                                | Derived; `otlp.endpoint` when nothing can be derived, or `collector.endpoint` / `honeycomb.endpoint` to override |
| `hermes.otel.headers` / `hermes.otel.insecure`        | `collector.headers` / `otlp.headers` and `collector.insecure` / `otlp.insecure`                                  |
| `hermes.otel.honeycomb_api_key` / `honeycomb_dataset` | `honeycomb.api_key` / `honeycomb.dataset`                                                                        |
| `hermes.otel.splunk_realm` / `splunk_access_token`    | `splunk.realm` / `splunk.access_token`                                                                           |
| `hermes.otel.debug_file_path`                         | `file.path`                                                                                                      |
| `hermes.otel.service_name`                            | `service_name` on the org                                                                                        |
| `hermes.otel.signals`                                 | `signals`, shared or per org                                                                                     |
| `hermes.otel.resource_attributes`                     | `resource_attributes`, shared and/or per org                                                                     |

{% hint style="warning" %}
**Deploy the image before rewriting the secret.** A new image reads the old shape; an old image cannot read the new one and skips every org. See [Versioning & Upgrades](https://docs.pharos.ai/open-telemetry/configuration/versioning-and-upgrades.md).
{% endhint %}

***

## Legacy Single-Org Env Vars

`ORG_CONFIGS` is the configuration surface. Single-org `SF_*` and `OTEL_*` environment variables apply **only when `ORG_CONFIGS` is unset** — a fallback for a single-org local run, not an alternate way to configure an org alongside `ORG_CONFIGS`. That is also where the username-password (`SF_PASSWORD`) and static-token (`SF_ACCESS_TOKEN` + `SF_INSTANCE_URL`) auth modes live; both are ignored with a warning whenever `ORG_CONFIGS` is set. See [Security](https://docs.pharos.ai/open-telemetry/hermes/security.md#authentication).

***

## State-Store Selectors

Several Hermes subsystems keep small pieces of durable state — a replay cursor, a lease, a dedup fingerprint — each backed by a **selectable store**, chosen per subsystem via its own environment variable. The AWS and Azure Terraform modules set these to DynamoDB and Table Storage respectively.

| Selector                | Backs                                                                                              | Accepted values                                                                                                   |
| ----------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `REPLAY_STORE`          | Pub/Sub replay-ID bookkeeping (Iris, RTEM)                                                         | `file`, `dynamodb`, `table_storage`                                                                               |
| `CURSOR_STORE`          | Per-(org, event type) ELF cursor position                                                          | `file`, `dynamodb`, `table_storage`                                                                               |
| `LEASE_STORE`           | Per-`EventLogFile` claim for ELF live workers (TTL-based, no heartbeat)                            | `noop` (default; safe for one replica per org), `dynamodb`, `table_storage`. An unknown value is a startup error. |
| `STREAM_LEASE_STORE`    | Stream-ownership lease making single-active-per-stream enforced for Iris and RTEM across processes | `noop` (default), `dynamodb`, `table_storage`. Self-metric `hermes_stream_lease_is_leader`.                       |
| `ARGUS_DEDUP_STORE`     | RTEM ↔ ELF dedup fingerprints; also required for the ELF Hourly loop                               | `none`/`noop`, `memory`, `dynamodb`, `redis`, `table_storage`/`azuretable`                                        |
| `ARGUS_ORIGIN_STORE`    | Async nest-vs-fork origin timestamps                                                               | `none`/`noop`, `memory`, `dynamodb`, `azuretable`/`table_storage`                                                 |
| `HERMES_TRACEMAP_STORE` | `(org_id, REQUEST_ID) → trace_id` map and the session-root claim shared by Iris and Argus          | `file` (default), `dynamodb`, `azuretable`/`table_storage`                                                        |

These are distinct stores for distinct pieces of state — a dedup fingerprint and a trace-map entry are never the same record, even when both live in the same DynamoDB account. Each selector has companion variables for its table name and connection (for example `LEASE_DYNAMODB_TABLE`, `STREAM_LEASE_TABLE_STORAGE_CONN`), which the Terraform modules set for you.

***

## Process-Wide Environment Variables

| Variable                                                                                               | Sets                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIPELINE_CONFIG_FILE` / `ARGUS_PIPELINE_CONFIG_FILE`                                                  | A custom Iris / Argus base pipeline-config YAML, replacing the embedded default. See [Pipeline Config](https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md). |
| `HERMES_SESSION_TRACE_SEGMENT`                                                                         | Session trace time-segment width (Go duration, e.g. `6h`); default off. Set identically on every runtime. Datadog deployments should set a window under 18h.                    |
| `HERMES_SESSION_MAX_SPANS_PER_TRACE`                                                                   | Process-wide default for the span-count cap; consulted only when neither the org nor the document sets one.                                                                     |
| `HEALTH_MULTI_ORG_MODE`                                                                                | How per-org health rolls up into `/health`: `all` (default), `any`, `majority`.                                                                                                 |
| `HEALTH_PORT`                                                                                          | Health server port; default `8080`.                                                                                                                                             |
| `ARGUS_ELF_POLL_INTERVAL_SECONDS` / `ARGUS_ELF_HOURLY_POLL_INTERVAL_SECONDS` / `ARGUS_ELF_EVENT_TYPES` | Process-wide defaults for the matching `hermes.elf.*` fields; an explicit per-org value wins.                                                                                   |
| `ARGUS_ELF_DISABLE_HOURLY`                                                                             | Kill-switch for the Hourly loop — **always wins** over any org's `hermes.elf.disable_hourly`.                                                                                   |
| `CLOUD_METRICS`                                                                                        | `cloudwatch` or `azure_monitor` — publishes `argus_elf_lag_seconds` to the cloud autoscaler and lag alarm.                                                                      |

***

## 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>🎯 Backend Configuration</strong></td><td>Per-backend detail behind each block, with runbooks</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/backends.md">Backend Configuration</a></td></tr><tr><td><strong>🗺️ Mapping &#x26; Redaction</strong></td><td>What redaction_enabled and redaction_overrides do</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md">Mapping &amp; Redaction</a></td></tr><tr><td><strong>🔗 Cross-Surface Correlation</strong></td><td>session_unification, trace_stitching, and session caps explained</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/correlation.md">Cross-Surface Correlation</a></td></tr><tr><td><strong>🟠 AWS Deployment</strong> / <strong>🔵 Azure Deployment</strong></td><td>Where the document is stored and how a change is applied</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/aws.md">AWS Deployment</a></td></tr></tbody></table>
