> 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/versioning-and-upgrades.md).

# Versioning & Upgrades

What a Hermes version number promises — the public-contract surfaces and pre-1.0 bump rules — and how to pin an image, upgrade, and roll back.

Hermes ships one versioned artifact: the runtime container image. This page defines what its version number promises and how to take an upgrade safely.

***

## Versions and Tags

* Releases are numbered `vX.Y.Z`. The GA line starts at **v0.2.0**; the release line (`0.2`) moves only with a deliberate decision, and the patch number advances with every release.
* Images are published to Docker Hub as `pharosai/hermes` (the runtime) and `pharosai/hermes-loadgen` (the load generator), as multi-arch manifests for `linux/amd64` and `linux/arm64`.
* Exactly two tag forms exist: the **immutable** `vX.Y.Z`, published once per release and never moved or reused, and the **moving** `latest`. There is no `v0.2`, no `v0`, and no commit-hash tag.
* The running version is queryable on any deployment from the image label `org.opencontainers.image.version`.

| Profile          | Tag to use                                                        | Why                                                     |
| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Production       | `pharosai/hermes:vX.Y.Z` (pin the digest in your task definition) | Every upgrade is an explicit change you tested          |
| Lab / quick test | `pharosai/hermes:latest`                                          | Newest release; changes arrive without an operator gate |

Moving tags do not redeploy anything by themselves: ECS and Container Apps resolve a tag to a digest when a task or revision starts, so picking up a new `latest` still needs a new deployment or revision.

Documentation, the Terraform modules, the dashboard packs, and the Salesforce metadata are not versioned independently — they ship at whatever version the image carries.

***

## The Public Contract

A version number is a promise about these eight surfaces. Anything not listed is an implementation detail and may change in any release.

| # | Surface                                                             | Who is affected if it moves                                     |
| - | ------------------------------------------------------------------- | --------------------------------------------------------------- |
| 1 | **Emitted telemetry** — span names, attribute keys, trace shape     | Your dashboards, alerts, and saved queries                      |
| 2 | **`ORG_CONFIGS` schema**                                            | Every deployment — the runtime refuses orgs it cannot parse     |
| 3 | **Pipeline-config YAML**                                            | Orgs with a custom base file or `mapping_override_path`         |
| 4 | **State-table schemas** — replay, ELF cursors, lease, dedup, origin | Rollback and in-flight resumption state                         |
| 5 | **Terraform module variables**                                      | Your Terraform that consumes the modules                        |
| 6 | **Runtime environment variables**                                   | Task definitions and Container App revisions                    |
| 7 | **Salesforce org requirements** — permissions and objects           | Your Salesforce administrator, who grants them before upgrading |
| 8 | **Self-instrumentation metric names**                               | Operator alerts built on those series                           |

Surface 1 is on the list on purpose: a renamed attribute breaks a dashboard as surely as a renamed config key breaks a deployment.

### Bump rules

**Removal or rename is major, addition is minor, a fix that changes nothing on the eight surfaces is patch.**

* **Major:** removing or renaming a span, attribute, or metric; changing a trace's parent/child shape for orgs that did not opt in; changing the default of an existing flag so an unedited deployment emits something different; dropping a configuration shape a previous release accepted; a state-table change an older image cannot read; removing or renaming a Terraform or environment variable; requiring a new Salesforce permission without which the runtime fails.
* **Minor:** new spans, attributes, or metric series; new behaviour behind a flag that defaults off; a new configuration shape introduced alongside the old one while the old one still parses; a new variable with a working default; a new Salesforce permission that degrades gracefully when absent; a wipe-safe state-table change.
* **Patch:** fixes that restore documented behaviour, performance work, dependency and base-image updates, documentation and dashboards.

**While the major version is zero, minor takes the role of major.** A breaking change goes to `v0.3.0`, not `v1.0.0`; anything else is `v0.2.x`. That is why no moving alias inside the major is published — a `v0` tag would cross a breaking change silently.

**Behaviour changes are recorded.** Every change to one of the eight surfaces gets an entry in the behaviour-changes ledger — what changes, who is affected, what to watch for, how to keep the old behaviour — and the release notes for each version are built from that ledger. The version number tells you something changed; the ledger tells you what.

***

## Defaults in v0.2.0

Behaviour an operator should know before adopting the GA line:

* **Cross-channel session unification is on by default** for Iris, Argus RTEM, and Argus ELF. Event Monitoring events join the user's session trace instead of shipping as standalone one-span traces. The integration user must read `AuthSession`; where it cannot, spans keep their own trace. Opt out per org with `"session_unification": {"enabled": false}`, which turns the session root off on all three channels.
* **An ambiguous per-org metric-rule override is a load error.** An Iris override naming a metric that several base rules share is refused rather than applied to whichever rule happens to come last.
* **A static access token is verified at startup** with one authenticated call, and all four runtimes (Iris, RTEM, ELF live, ELF backfill) honour `SF_ACCESS_TOKEN` + `SF_INSTANCE_URL` identically.
* **The per-org health metrics classify rejections in operation**, not only at startup: `hermes_org_auth_failures_total` moves on every credential rejection, and `hermes_org_connected` drops after two consecutive rejections, in every auth mode.
* **The Avro codec** used to decode Pub/Sub payloads was replaced with no observable change to span attributes, log records, field names, or values.

***

## Upgrading

Hermes upgrades are rolling restarts; no database migration is required between supported versions.

1. **Check the release notes** for behaviour changes touching the surfaces you depend on.
2. **Import the new image** into your registry (ECR or ACR) and pin the new tag or digest in the runtime stage's `terraform.tfvars`.
3. **Apply and roll:** AWS — `terraform apply`, then `aws ecs update-service --task-definition <family>:<N>` and `aws ecs wait services-stable`; Azure — `terraform apply` (or `az containerapp update --image …`), which creates a new revision. Commands are in the [AWS](https://docs.pharos.ai/open-telemetry/configuration/aws.md#applying-changes-upgrading-and-rolling-back) and [Azure](https://docs.pharos.ai/open-telemetry/configuration/azure.md#applying-changes-upgrading-and-rolling-back) runbooks.
4. **Verify** — `/health` 200, `/stats` lists every org, the startup log lines are present, `hermes_org_connected` reads 1, and a fresh span lands in the backend.

**Order of operations when a release changes the `ORG_CONFIGS` schema.** Compatibility is one-directional: a new image reads the old document, an old image cannot read the new one and skips every org. Deploy the image, confirm the running revision is the new one, and only then rewrite the secret. Rewriting the secret first is the failure mode that takes a deployment down. The flat `hermes.otel` export shape is the current example — see [Migrating from the Flat Shape](https://docs.pharos.ai/open-telemetry/configuration/org-configs.md#migrating-from-the-flat-shape).

**Custom pipeline-config files.** If you set `PIPELINE_CONFIG_FILE`, `ARGUS_PIPELINE_CONFIG_FILE`, or `hermes.mapping_override_path`, validate the file against the target version's [Pipeline Config](https://docs.pharos.ai/open-telemetry/configuration/pipeline-config.md) reference before upgrading. No action is needed if you use the embedded defaults.

### Pre-upgrade checklist

* [ ] `ORG_CONFIGS` parses with the target image (run it in a non-production environment with the same document shape).
* [ ] If the secret already uses a newer schema, the target image is not **older** than the loader that understands it.
* [ ] Backend headers and custom YAML overrides still load.
* [ ] Queries and alerts in your backend do not assume labels the release renamed.
* [ ] The replay, cursor, dedup, lease, origin, and trace-map stores are reachable from the new task or revision.

***

## State Tables

The state tables are resumption state, not telemetry. Wiping one can cause re-processing or a window without dedup suppression, but never deletes Salesforce data.

| Store                       | Wipe consequence                                               |
| --------------------------- | -------------------------------------------------------------- |
| Replay cursor (Iris / RTEM) | Subscribes from `LATEST`, skipping the 72-hour Pub/Sub backlog |
| ELF live cursor             | Re-ingests from the current day                                |
| ELF backfill cursor         | Restarts the backfill job from the beginning                   |
| Lease                       | Workers re-claim files                                         |
| Dedup                       | Suppression window resets — duplicates possible for a while    |
| Origin                      | Async threshold decisions reset to own-trace-plus-link         |
| Trace-map                   | Stitching misses fall open to deterministic derivation         |

***

## Rolling Back

1. Identify the previous image tag or digest from your deployment history.
2. Revert: AWS — `aws ecs update-service --task-definition <previous>` with `--force-new-deployment`; Azure — `az containerapp revision activate --revision <previous>`.
3. Verify with the same checks as an upgrade.
4. No state rollback is required — the previous image reads the same tables with the same schema. If a cursor table was wiped during diagnosis, re-ingestion starts from the current day (ELF) or `LATEST` (Iris/RTEM).

***

## 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>🟠 AWS Deployment</strong></td><td>Upgrade and rollback commands for ECS</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/aws.md">AWS Deployment</a></td></tr><tr><td><strong>🔵 Azure Deployment</strong></td><td>Upgrade and rollback commands for Container Apps</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/azure.md">Azure Deployment</a></td></tr><tr><td><strong>🧩 ORG_CONFIGS Reference</strong></td><td>Schema surface #2, including the flat-shape migration</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/org-configs.md">ORG_CONFIGS Reference</a></td></tr><tr><td><strong>📡 Self-Instrumentation Metrics</strong></td><td>Schema surface #8</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/self-metrics.md">Self-Instrumentation Metrics</a></td></tr></tbody></table>
