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

# Iris

Iris is the Triton/Pharos application-telemetry bridge — it subscribes to pharos\_\_Log\_Event\_\_e and converts your Triton instrumentation into OTel signals.

Iris is the channel of Hermes that bridges your **Triton** instrumentation into OpenTelemetry. It subscribes to the `/event/pharos__Log_Event__e` Platform Event topic over the Salesforce Pub/Sub API, decodes the Triton log payload carried in each event, and emits OTel spans, metrics, and logs for Apex, Flow, Integration, and LWC activity — with no changes to your existing Triton setup.

***

## Span Pairing & Dedup

Triton logs the start and completion of a unit of work as two separate log records. Iris pairs a started span with its matching completed span to produce a single span with an accurate duration, rather than emitting two disconnected events.

Each gRPC fetch pulls up to 100 Platform Events per request (`fetchBatchSize`) — matching the Salesforce Pub/Sub API's own per-fetch limit, so a single fetch is as large as Salesforce will ever hand back anyway.

Because Platform Events can arrive out of order or be redelivered, Iris deduplicates pairs at two levels:

* **Intra-batch** — duplicate or repeated start/complete pairs within the same fetched batch of events.
* **Cross-batch** — a short in-progress buffer holds started-but-not-yet-completed spans (`pending_ttl_seconds`, 120 s), and a separate completed buffer holds recently-completed spans (`completed_ttl_seconds`, 900 s). Together they let a completion that arrives in a later batch still find its match, and suppress an exact re-publish of a pair Iris already emitted. Both TTLs are tunable in the [pipeline config](https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md).

***

## Session Enrichment

Triton's `LogTrigger` populates session fields from `AuthSession` at log time, using Platform Cache. Iris normally reads that same session context straight from the log, and only falls back to a Salesforce REST query against `AuthSession` when those session fields aren't already present on the log. That fallback query needs `AuthSession` read access, which comes with the `Hermes_Argus` permission set; a running user holding only `Hermes_Iris` skips it and works from whatever session context the log already carries.

With that session context, Iris creates a **session umbrella span** — a single span representing the user's authenticated session — and re-parents the individual request and transaction spans underneath it. The session also owns the trace: when a session is resolved, the trace ID is derived from the session ID, so everything a user did in that session lands in one trace rather than one trace per transaction (see [Architecture](https://docs.pharos.ai/open-telemetry/hermes/architecture.md#deterministic-identity-idconv) for the full derivation order).

{% hint style="info" %}
This umbrella extends beyond Iris by default: **cross-channel session unification** re-parents Argus RTEM and ELF spans under the same session umbrella too, so a session's Triton and Salesforce Event Monitoring telemetry share one trace. See [Cross-Surface Correlation](https://docs.pharos.ai/open-telemetry/hermes/correlation.md) for how it works and how to opt out.
{% endhint %}

![An Iris trace in Honeycomb: a session umbrella span over the transaction and per-operation LWC and Apex spans, with browser performance fields.](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c6fbaeb37661034385a9ce310994e0933921a2dc%2Fhoneycomb-trace-waterfall.png?alt=media)

***

## LWC Direct-Push Path

Lightning Web Component telemetry can be high-frequency and latency-sensitive, so Iris supports a path that bypasses Platform Events entirely:

1. A **client-side JS converter** running in the browser derives the same trace and span IDs Iris would derive server-side — byte-identical, so LWC spans line up with the rest of the trace without any coordination.
2. The converted payload is sent to a **stateless Apex proxy** (`TritonOtelProxy`).
3. The proxy forwards it through a **Named Credential**.
4. The Named Credential delivers it straight to your OTel collector.

This lets browser-generated telemetry reach your backend directly, without adding load to the `pharos__Log_Event__e` pipeline.

***

## Export Modes

Whether Iris uses the Platform Event path, the LWC direct-push path, or both is controlled by `OTel_Configuration__mdt.Export_Mode__c`:

| Mode      | Behavior                                                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Off`     | Hermes/Iris OTel export is disabled for the org.                                                                                                                                |
| `LWC_Go`  | Both paths are active: LWC telemetry uses the client-side direct-push path described above, while Apex/Flow/Integration telemetry flows through the Go (Iris) Pub/Sub pipeline. |
| `Go_Only` | All telemetry, including LWC, flows through the Go (Iris) Pub/Sub pipeline; the LWC direct-push path is not used.                                                               |

{% hint style="info" %}
Export mode is set per org on `OTel_Configuration__mdt` and determines whether the LWC direct-push path is used. See [salesforce-setup.md](https://docs.pharos.ai/open-telemetry/configuration/salesforce-setup.md) for setup details.
{% endhint %}

Beyond `Export_Mode__c`, the server-side fields Iris reads from `OTel_Configuration__mdt` are `serviceName`, `orgId`, `serviceNamespace`, `honeycombDataset`, `enableTraces`, `enableMetrics`, and `enableLogs`.

***

## Throughput

The Iris fetch/export loop is **synchronous** — each batch of events is exported before the next batch is fetched. In practice, that makes the OTLP round-trip to your backend the bottleneck, not Iris's own processing.

Converter throughput was measured with a Go microbenchmark of the decode → convert path (no export) on an Apple M4 Max developer workstation: about 600K log records per second, or roughly 323 µs per 200 mixed LWC/Apex/Flow logs. Iris input is bounded by Salesforce Platform Event delivery — tens of events per second per org — so converter capacity is not the limiting factor in a deployment; the Pub/Sub ingestion path and the export round-trip to your collector or backend are.

***

## 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>🏛️ Architecture</strong></td><td>One image, many binaries — entrypoints, signal shapes, deterministic IDs</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/architecture.md">Architecture</a></td></tr><tr><td><strong>☁️ Salesforce Setup</strong></td><td>Configure the External Client App, JWT auth, and Export_Mode</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/salesforce-setup.md">Salesforce Setup</a></td></tr><tr><td><strong>🛠️ Pharos Triton Instrumentation</strong></td><td>How Triton produces the logs Iris converts</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/pharos-triton-instrumentation.md">Pharos Triton Instrumentation</a></td></tr></tbody></table>
