> 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/hermes/architecture.md).

# Architecture

How Hermes is built — one Docker image with many runtime binaries, deterministic trace identity, and a YAML mapping engine shared by every channel.

Hermes ships as a single Docker image containing several independent runtime binaries. Which ones you run, and how, depends on your deployment size — but every binary shares the same identity model and the same config-driven mapping engine.

***

## One Image, Many Binaries

| Entrypoint           | Binary                            | Role                                                                                                 |
| -------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `iris`               | `/iris`                           | Pub/Sub subscriber for `pharos__Log_Event__e`                                                        |
| `argus-rtem`         | `/argus-rtem`                     | One Pub/Sub subscriber per org × channel                                                             |
| `argus-elf`          | `/argus-elf -mode=live\|backfill` | Batch `EventLogFile` puller; live and backfill share the runtime but keep separate cursor namespaces |
| `hermes`             | `/hermes -runtimes=…`             | Combined supervisor — launches selected runtimes as child processes                                  |
| `hermes-healthcheck` | health-probe binary               | Container health probe                                                                               |

The combined `hermes` supervisor is meant for **local, trial, and small-customer deployments** — it launches the runtimes you select as child processes inside one container. Production deployments generally prefer running `iris`, `argus-rtem`, and `argus-elf` as **separate services**, so each can scale and restart independently.

```mermaid
graph TD
  H["hermes supervisor"] --> I["iris"]
  H --> R["argus-rtem"]
  H --> E["argus-elf"]
  I --> X["Shared OTLP exporter"]
  R --> X
  E --> X
  X --> B["Your OTel backend"]
  style H fill:#37474f,stroke:#212121,color:#fff
  style B fill:#2e7d32,stroke:#1b5e20,color:#fff
```

Each runtime — whether launched by the supervisor or run standalone — converts its own event stream into OTel signals and pushes them through the same shared exporter to your backend.

***

## Three Signals From One Event

Every event Hermes processes — an Apex transaction, a Flow execution, a login, a report run — can produce up to three correlated OpenTelemetry signals:

* **Spans** for the execution itself: start, duration, parent/child structure. This is the signal Event Monitoring alone can't produce.
* **Metrics** for volume, latency, and governor-limit consumption.
* **Logs** for auth, security, and state-change facts — a login, a permission denial, a metadata change — as OTel log records rather than spans.

Not every event type emits all three. Some event types are log-only, or log-plus-metric with no span; which signals a type emits is declared per type in the mapping YAML.

![A Salesforce execution as an OpenTelemetry span, carrying triton.\* and salesforce.\* attributes, in Grafana Tempo.](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c0e3e0004c312e1e556c2098da4f2dac5cc48218%2Fgrafana-trace-span-attributes.png?alt=media)

***

## Deterministic Identity (`idconv`)

Hermes derives trace and span IDs deterministically from Salesforce identifiers instead of generating random ones at each hop, so runtimes that never talk to each other still converge on the same trace. The shared `idconv` package is used by `iris`, `argus-rtem`, `argus-elf`, and the browser-side LWC JavaScript converter, which follows the same derivation as the Go pipeline and produces byte-identical IDs for the same input.

How a trace ID is derived depends on which identifier is available:

| Channel                         | Identifier                  | Derivation                                                                                                                                                                                                                                                      |
| ------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Iris and Argus                  | Resolved Salesforce session | Org-salted hash of the session ID — the session is the top of the hierarchy (session → transaction → request → work), so it owns the trace. This is the default path when cross-channel session unification is on.                                              |
| Iris                            | Triton `transactionId`      | Hyphens stripped and **passed through unhashed**. The value must already be 32 hex characters; a non-hex value cannot be encoded as an OTLP trace ID, so that span or log is dropped at export and counted in `hermes_export_dropped_total{reason="trace_id"}`. |
| Iris (no transaction) and Argus | Salesforce `REQUEST_ID`     | Org-salted MD5 hash. The org ID is normalized to its 15-character form first, so Iris (which reads a 15-character org ID off the event) and Argus (18 characters, from configuration) salt identically.                                                         |

Span IDs are always 16 hex characters: an LWC span UUID keeps its first 16 hex characters; Apex, Flow, request, and session spans use `MD5(identifier)[:16]`; a Triton span ID that is not hex is folded into the same hash rather than dropped.

Because the derivation is deterministic rather than assigned by a central service, spans, metrics, and logs from different runtimes converge on one trace as long as they share the same underlying identifier. See [Cross-Surface Correlation](https://docs.pharos.ai/open-telemetry/hermes/correlation.md) for how Iris and Argus traces are joined, segmented, and capped.

***

## Mapping Is Data, Not Code

The rules that decide which Salesforce field becomes which OTel attribute — and which event types Hermes recognizes at all — live in YAML, not in Go. Adding a new event type, or changing which fields a mapping redacts, is a configuration change and a rolling restart, not a new binary release.

Only the **base mapping** ships baked into the Docker image. Everything customer-facing — org configuration, mapping overrides, redaction rules, Terraform sizing, image tag — lives outside the image and is applied without rebuilding it. See [Pipeline Config](https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md) for the YAML reference and [Mapping & Redaction](https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md) for how overrides and redaction are applied per org.

***

## 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>🌈 Iris</strong></td><td>The Triton/Pharos application-telemetry bridge</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/iris.md">Iris</a></td></tr><tr><td><strong>👁️ Argus</strong></td><td>The Salesforce Event Monitoring bridge</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/argus.md">Argus</a></td></tr><tr><td><strong>🔗 Cross-Surface Correlation</strong></td><td>How Iris and Argus traces stay stitched together</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/correlation.md">Cross-Surface Correlation</a></td></tr></tbody></table>
