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

# Pipeline Config (YAML)

Reference for the YAML that turns Salesforce records into OTel spans, metrics, and logs — structure, per-org merge rules, Argus extensions, and recipes.

The pipeline configuration is the YAML that controls how every Salesforce event Hermes reads is converted into OpenTelemetry signals — which span attributes are emitted, which metrics are produced, which log records are written, and how Argus channels and EventLogFile types are recognized. It is data, not code: changing a mapping is a YAML edit and a rolling restart.

***

## Where It Plugs In

Two default documents ship embedded in the Hermes image and are used when nothing else is configured:

| Runtime            | Embedded default                                           | Replace the base with                           | Per-org override                                                                                                                          |
| ------------------ | ---------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Iris               | `pipeline-config.iris.default.yaml` (version `2026.05.31`) | `PIPELINE_CONFIG_FILE=/path/to/file.yaml`       | `hermes.mapping_override_path` in [`ORG_CONFIGS`](https://docs.pharos.ai/open-telemetry/configuration/org-configs.md) — **merged** by key |
| Argus (RTEM + ELF) | `pipeline-config.argus.default.yaml`                       | `ARGUS_PIPELINE_CONFIG_FILE=/path/to/file.yaml` | `hermes.mapping_override_path` — **full replace**                                                                                         |

{% hint style="warning" %}
**A custom base file replaces the default; it does not merge into it.** Omit the `metrics` section from your `PIPELINE_CONFIG_FILE` and every Iris metric silently stops while spans and logs keep flowing. At startup Hermes logs `pipeline config loaded` with a `metric_rules` count and warns `pipeline config has NO metric rules` when that count is zero — check it after any change.
{% endhint %}

***

## File Structure (Iris)

Every section is optional; an omitted section takes the embedded default. Every `when:` condition is optional too — no condition means the rule always fires.

```yaml
version: "2.0"

spans:
  resource_attributes:        # static key=value on every span
    - key: client.name
      value: Acme Corp
  name_rules:                 # span name — first match wins
    - when: action != ''
      template: '{category}/{action}'
    - template: '{category}'
  kind_rules:                 # span kind — first match wins
    - when: category IN ['Apex', 'Integration']
      value: server
    - value: internal
  status_rules:               # span status — first match wins
    - when: level == 'ERROR'
      value: error
    - value: unset
  service_namespace_rules:    # service.namespace — first match wins
    - when: category == 'Apex'
      value: salesforce.apex
    - value: salesforce
  attributes:                 # dynamic attributes — all matches applied
    - key: triton.category
      from: category
    - key: salesforce.limits.cpu_time
      from: governor_limits.cpu_time
      type: int
      when: category == 'Apex' AND governor_limits != null

metrics:
  base_attributes:            # attributes on every metric datapoint
    - key: salesforce.org_id
      from: org_id
  metric_rules:               # one rule → one metric — all matches
    - when: duration != null
      name: triton.operation.duration
      type: histogram           # histogram | sum | gauge
      value:
        from_field: duration    # or: literal: "1" for a counter
        type: float
      extra_attributes:         # per-rule attributes on top of base_attributes
        - key: http.status_code
          from: http_status_code
          type: int
          when: http_status_code != null

log_records:
  log_rules:                  # one rule → one log record — all matches
    - when: level == 'ERROR'
      severity:
        from_field: level
      body:
        from_field: summary

dedup:
  pending_ttl_seconds: 120    # started-but-not-completed buffer
  completed_ttl_seconds: 900  # recently-completed buffer

session:
  enabled: true
  cache_ttl_minutes: 30

subscriber:
  fetch_batch_size: 100
  flush_interval_seconds: 60

field_parsers: []             # parse custom fields out of the Triton payload

default_redactions:           # the 11-rule deny-list; active when redaction_enabled is set
```

### Conditions (`when:`)

Conditions compare fields of the decoded Triton log and are evaluated once per event. Operators: `==` and `!=` for strings, `== null` / `!= null` presence guards, `>`, `>=`, `<`, `<=` for numbers, `IN ['a','b']` for set membership, `AND`, `OR`, and parentheses for precedence — for example `(category == 'Apex' OR category == 'Flow') AND level == 'ERROR'`. Field families you can reference:

| Family                                                                                                                                                                               | Notes                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Flat fields — `category`, `type`, `area`, `level`, `action`, `summary`, `details`, `user_id`, `org_id`, `session_id`, `request_id`, `duration`, `http_method`, `http_status_code`, … | Top-level Triton log fields; guard pointer-typed ones with `!= null`. |
| `error.*`                                                                                                                                                                            | Guard with `error != null`.                                           |
| `component_info.*`                                                                                                                                                                   | Always present.                                                       |
| `runtime_info.*`                                                                                                                                                                     | Pointer fields — guard with `!= null`.                                |
| `governor_limits.*`, `governor_limits_delta.*`                                                                                                                                       | Flat integers — guard with `governor_limits != null`.                 |
| `custom.*`                                                                                                                                                                           | User-defined fields; requires a `field_parsers` entry.                |

### `field_parsers`

Parse structured values out of a Triton text field so they can be used in attributes, metrics, and conditions. A parser names a `source` — `details`, `summary`, `stack`, or `action` for the corresponding `pharos__Log__c` text field, or `event` to read any field of the raw Platform Event JSON by its Salesforce API name (including custom fields Hermes has never heard of) — an optional `detect_marker` that must be present for the parser to run, and one or more sections delimited by `=== Name ===` markers, each with typed `fields` (`float`, `float-mb-to-bytes`, `int`, `string`, `bool`, `dimension-width`, `dimension-height`). Targets are `runtime_info.*` or `custom.<name>`; custom targets become usable in `from:` and `when:` automatically.

***

## Per-Org Merge Rules (Iris)

An Iris override file only declares what differs; the runtime merges it over the base by key:

| Element                                                               | Merge key | What the override can change                                                                                                                                                                      |
| --------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attribute entry                                                       | `key`     | Everything (`from`, `value`, `type`, `when`); new keys are appended                                                                                                                               |
| Metric rule                                                           | `name`    | Only the `when` matcher of an existing rule. An override naming a metric that several base rules share is a **load error** — give it a unique name in the base or add a new rule under a new name |
| Log rule                                                              | `when`    | Nothing on existing rules; new `when` values are appended                                                                                                                                         |
| `dedup`, `default_redactions`, `async`, `channels`, `elf_event_types` | —         | Not overridable per org; edit the base file                                                                                                                                                       |

To change a metric or log rule's body per org, add a new rule under a unique name and, if needed, narrow the base rule's `when` so the two do not both fire.

**Argus** has no merge: a per-org override replaces the whole Argus config, so it must contain the complete `channels`, `elf_event_types`, and `default_redactions` sections the org needs — see [Mapping & Redaction](https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md).

***

## Argus Per-Type Extensions

These fields appear on `channels` and `elf_event_types` entries in the Argus config and have no effect on Iris.

| Field                   | Values                                                                      | Effect                                                                                                                                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sample_rate`           | `0.0`–`1.0`, default `1.0`                                                  | Fraction of events to emit. Sampling is **deterministic per `REQUEST_ID`**, so Iris, RTEM, and ELF all sample the same request in or out together and cross-channel traces stay whole.                                                                                           |
| `dedup.mode`            | `surface-select` (default), `suppress`, `emit-as-supplement`, `emit-always` | How an event family present on both RTEM and ELF is reconciled. `surface-select` needs no state store; the other three use fingerprints in `ARGUS_DEDUP_STORE`. See [Cross-Surface Correlation](https://docs.pharos.ai/open-telemetry/hermes/correlation.md#rtem-and-elf-dedup). |
| `async.threshold_hours` | Hours; defaults to the org's `hermes.elf.async_link_threshold_hours` (18)   | Marks the type as asynchronous work and sets the nest-vs-fork threshold. No shipped type declares `async` by default.                                                                                                                                                            |

***

## Recipes

**Add a static label to every span**

```yaml
spans:
  resource_attributes:
    - key: client.name
      value: Acme Corp
```

**Expose a Triton field that isn't a span attribute yet**

```yaml
spans:
  attributes:
    - key: triton.area
      from: area
      when: area != ''
```

**Add a custom metric — HTTP error count by status code**

```yaml
metrics:
  metric_rules:
    - when: category == 'Integration' AND http_status_code >= 400
      name: custom.integration.http.errors
      type: sum
      value:
        literal: "1"
      extra_attributes:
        - key: http.method
          from: http_method
          when: http_method != null
        - key: http.status_code
          from: http_status_code
          type: int
```

**Capture WARNING Apex logs as OTel log records** — by default only `ERROR` and `Integration` logs produce log records; add a rule (keeping the default one) for WARNING Apex logs:

```yaml
log_records:
  log_rules:
    - when: level == 'WARNING' AND category == 'Apex'
      severity:
        value: WARNING
      body:
        from_field: summary
      attributes:
        - key: triton.category
          from: category
        - key: salesforce.request_id
          from: request_id
          when: request_id != null
```

Severity accepts `from_field` or a fixed `value` (`ERROR`, `WARNING`, `INFO`, `DEBUG`, `FINE`, `FINER`, `FINEST`).

**Disable governor-limit span attributes** — in a base file, remove the `salesforce.limits.*` entries (and the `salesforce.limits.*.delta` entries) from `spans.attributes`. The governor-limit **metrics** (`apex.governor.*`) are separate `metric_rules`; remove those too if you want neither.

**Increase dedup TTLs for slow Flow environments**

```yaml
dedup:
  pending_ttl_seconds: 300
  completed_ttl_seconds: 1800
```

***

## Validation

Hermes parses the file at startup and exits with a descriptive error on an invalid file. On success it logs `pipeline config loaded` with the counts of attribute, metric, and log rules; compare them with what you expect. Every exported signal carries the file's `version` as the `salesforce.bridge.mapping_version` resource attribute, so you can confirm from the backend which mapping produced it. Pipeline-config changes are picked up on the next restart or revision — see [Applying Configuration Changes](https://docs.pharos.ai/open-telemetry/configuration/operations.md#applying-configuration-changes).

***

## 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>🗺️ Mapping &#x26; Redaction</strong></td><td>Layering model and the three redaction controls</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/mapping-and-redaction.md">Mapping &amp; Redaction</a></td></tr><tr><td><strong>🧩 ORG_CONFIGS Reference</strong></td><td>mapping_override_path and the redaction flags</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/org-configs.md">ORG_CONFIGS Reference</a></td></tr><tr><td><strong>🏷️ Versioning &#x26; Upgrades</strong></td><td>The pipeline-config schema is one of the eight versioned surfaces</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/versioning-and-upgrades.md">Versioning &amp; Upgrades</a></td></tr></tbody></table>
