> 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/mapping-and-redaction.md).

# Mapping & Redaction

How Hermes maps Salesforce events to OTel signals as layered YAML config rather than code, and the three redaction controls over what leaves your org.

Two config surfaces sit behind every signal Hermes emits: the **mapping** that turns a Salesforce record into an OTel span, metric, or log, and the **redaction** rules that scrub anything sensitive out of it before export. Both are configuration, not Go code — you change them with a YAML edit or an `ORG_CONFIGS` flag and a rolling restart, not a new image.

***

## Mapping Is Data, Not Code

Hermes's mapping engine — shared by Iris and Argus behind a neutral field-source adapter — is driven entirely by YAML. Which Salesforce field becomes which OTel attribute, which event types Hermes recognizes at all, and which signal shape (span, metric, log — or some combination) a given type emits are all declared in mapping config, not hardcoded in Go. Adding a new event type, or changing which fields get redacted, is a **configuration change and a rolling restart**, not a binary release.

Only the base mapping is baked into the Hermes image — everything else is layered on top at deploy time:

* **Base mapping** — Pharos-managed, ships inside the image (`pipeline-config.iris.default.yaml` and `pipeline-config.argus.default.yaml`), covers the event types Hermes recognizes out of the box. Replace it wholesale with `PIPELINE_CONFIG_FILE` (Iris) or `ARGUS_PIPELINE_CONFIG_FILE` (Argus).
* **Per-org override** — an optional YAML file at the path set in `hermes.mapping_override_path` (see [`ORG_CONFIGS`](https://docs.pharos.ai/open-telemetry/configuration/org-configs.md)), applied over the base mapping for that org.

An Iris override only declares what differs. This excerpt from the shipped example shows the shape of the `spans` section — a static resource attribute, span-name rules, and an attribute drawn from a Triton field:

```yaml
version: "2.0"
spans:
  resource_attributes:
    - key: client.name
      value: Acme Corp
  name_rules:
    - when: action != ''
      template: '{category}/{action}'
    - template: '{category}'
  attributes:
    - key: triton.details
      from: details
      when: details != ''
    - key: salesforce.limits.cpu_time
      from: governor_limits.cpu_time
      type: int
      when: category == 'Apex' AND governor_limits != null
```

The full section-by-section reference — `spans`, `metrics`, `log_records`, `dedup`, `session`, `subscriber`, `field_parsers`, the `when:` condition syntax, and customization recipes — is on [Pipeline Config](https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md).

{% hint style="warning" %}
**Iris merges; Argus replaces.** Iris applies a per-org override by key — attributes merge fully, metric rules can change only their `when:` matcher, log rules only add new matchers — so a partial override like the one above is exactly what you want. An Argus per-org override is a **full replace**: the file discards the *entire* base mapping, not just the keys it redeclares. If an org needs an Argus override at all, that file must restate everything it wants to keep — `channels:`, `elf_event_types:`, `default_redactions:`, and `redaction_enabled` — or that part of the base mapping silently disappears for the org.
{% endhint %}

### `mapping_version`

Every mapping carries a version, and that version is surfaced on exported telemetry as the `salesforce.bridge.mapping_version` OTLP resource attribute. That means you can tell, from the backend side, exactly which mapping produced a given span, metric, or log — useful when you're rolling out a mapping override and want to confirm which orgs are on the new version.

***

## Redaction

Redaction is **opt-in per org**. By default Hermes redacts nothing: secrets, tokens, usernames, IP addresses, and any other sensitive values in Salesforce event fields are exported to your backend as-is. Enable it for every org whose compliance obligations require it. Three independent controls exist.

### 1. The curated deny-list (`hermes.redaction_enabled`)

Setting `"redaction_enabled": true` in an org's `hermes` block activates the full curated set on **both channels**: the `default_redactions` deny-list — eleven named regex rules that ship in both the Iris and the Argus default mapping, applied in order to every string attribute and every log body regardless of which field or event type produced it — plus every `redact: true` field rule that ships dormant in the default mappings.

| Rule                  | Replaces                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `password-reset-url`  | Whole URLs containing `pw-reset`, `reset-password`, `tokenized-link`, `setpasswd`, `setpwd`      |
| `oauth-bearer-token`  | `Bearer <token>` anywhere in a string                                                            |
| `raw-jwt`             | Raw JWTs (`eyJ…header.payload.signature`)                                                        |
| `access-token-param`  | `access_token=`, `refresh_token=`, `id_token=`, `api_key=`, `code=`, `session=` query parameters |
| `login-key-surrogate` | `login_key=<value>` / `LOGIN_KEY=<value>`                                                        |
| `email-address`       | Email addresses                                                                                  |
| `e164-phone`          | E.164 phone numbers (`+` and 7–15 digits)                                                        |
| `us-ssn`              | US Social Security Numbers (`###-##-####`)                                                       |
| `credit-card`         | Credit-card-shaped digit runs (13–19 digits, optionally grouped)                                 |
| `authorization-basic` | `Authorization: Basic <base64>` header values                                                    |
| `x-api-key-header`    | `X-Api-Key: <value>` header values                                                               |

Rule order matters: `password-reset-url` fires before `access-token-param`, so a reset URL is replaced as a unit rather than having its query string partially rewritten. The sweep covers log bodies as a whole as well as attributes — several Argus event types are log-only, with no per-attribute mapping step to hang a per-field rule on, so the sweep is what protects them. The one Iris/Argus difference is how the list is customised: on Iris `default_redactions` is not overridable per org (edit the base file); on Argus a per-org override replaces the whole config, deny-list included.

### 2. Per-field overrides (`hermes.redaction_overrides`)

A list of emitted attribute keys, each with a strategy, applied to that org **whether or not** `redaction_enabled` is set. Keys are the OTel attribute names as emitted, not raw Salesforce field names, and the override runs before framework attributes are added — so `salesforce.org_id`, `argus.event_type`, and `argus.channel` cannot be overridden.

| Strategy            | Behavior                                                                                                          |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `replace` (default) | Substitutes `[redacted]`, or a custom `replacement` string.                                                       |
| `drop`              | Removes the attribute from the signal entirely.                                                                   |
| `hash`              | Replaces the value with a deterministic 16-hex digest — correlatable across events without storing the raw value. |
| `mask`              | Reveals only the last four characters.                                                                            |

An omitted strategy means `replace`; an unknown strategy or an empty `field` causes the org to be **skipped at startup** with a warning. Numbers and booleans are stringified before hashing or masking. A recommended starting point:

```json
"redaction_overrides": [
  { "field": "salesforce.user.username",  "strategy": "hash" },
  { "field": "enduser.id",                "strategy": "hash" },
  { "field": "salesforce.user.email",     "strategy": "hash" },
  { "field": "network.peer.address",      "strategy": "replace", "replacement": "[ip-redacted]" },
  { "field": "client.address",            "strategy": "replace", "replacement": "[ip-redacted]" },
  { "field": "server.address",            "strategy": "replace", "replacement": "[host-redacted]" },
  { "field": "db.statement",              "strategy": "drop" },
  { "field": "http.request.body",         "strategy": "drop" },
  { "field": "http.response.body",        "strategy": "drop" }
]
```

Use `hash` for identity fields you need to correlate (same username → same hash, non-reversible), `drop` for free text that may carry payloads, and `replace` where a visible placeholder is more useful than a hash.

### 3. Allow-list mode (`redaction_mode: allow-list`)

A top-level key in the pipeline-config YAML that applies to both Iris and Argus. Instead of scrubbing known-bad patterns out of everything, it drops every string attribute and log-body value unless the attribute rule or log rule is explicitly marked `allow: true`. It is independent of the two controls above — an org can run any combination.

![A Salesforce log's structured metadata fields (org, user, severity, code location) after mapping.](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-e574788abf82afd2b64393814c64714390d1fa2c%2Fgrafana-logs-structured-metadata.png?alt=media)

{% hint style="info" %}
**Override files and redaction.** Because an Argus per-org override replaces the base config, it must repeat `redaction_enabled: true` and the `default_redactions` rules it wants — nothing is inherited. On Iris, `redaction_enabled` OR-merges: an override can turn it on, but cannot turn it back off once a lower layer set it, and the deny-list itself comes from the base file.
{% endhint %}

***

## 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>📜 Pipeline Config (YAML)</strong></td><td>Section-by-section reference for the mapping YAML</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md">Pipeline Config (YAML)</a></td></tr><tr><td><strong>🧩 ORG_CONFIGS Reference</strong></td><td>Where redaction_enabled, redaction_overrides, and mapping_override_path live</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/org-configs.md">ORG_CONFIGS Reference</a></td></tr><tr><td><strong>🔐 Security</strong></td><td>Auth, transport, and the broader data-handling posture</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/security.md">Security</a></td></tr></tbody></table>
