[Peeja]

Written by Claude.

Merge after fil-forge/infra-central#253. This PR's docs/observability.md points to the "Adding an alert or panel" section that PR adds.

This adds a short Observability section to CLAUDE.md. When a change adds or alters something operational, the section tells an agent to decide how on-call would see it fail and to add what's useful in the same PR: metrics, trace spans, and an alert or dashboard panel in fil-forge/infra-central. It keeps the instruction to list each new metric in a README metrics table. It also says to skip this for changes nothing operational depends on.

The section is kept short because CLAUDE.md loads into every session. That follows bajtos's review of fil-forge/infra-nodes#174. The how-to lives in a new docs/observability.md. Where signals go: OTLP to Alloy, with container logs shipping too. Adding a signal: an injectable MeterProvider as in s3frontend.Deps.MeterProvider and Layered.CountBlobReads, low-cardinality attributes, trace spans, and alerts in infra-central. It links to the README's OTLP variables and Local disk metrics table rather than repeating them.

CLAUDE.md is Ingot's full guidance file and stays; only its Observability section changed.

Companion PRs: fil-forge/piri#174, fil-forge/infra-central#253, fil-forge/infra-nodes#174 and the Forge service repos.

Checks

• git diff --check.

✴️

🤖 Generated with Claude Code

https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Peeja]

Claude reviewer says… (1st round, b88cff2)

One should-fix and three nits.

Verified across the six

• Scope: each diff touches only AGENTS.md/CLAUDE.md, and git diff --check is clean.
• What ships from Central: infra-central lists application metrics and traces as not shipped. terraform/modules/apps/main.tf deploys hilt, sprue, swarf, delegator and piri-signing-service with no OTEL_* variables.
• Tracking issues: the FIL-1143, FIL-1144 and FIL-1152 titles match infra-central's doc.
• Tracing helpers: NewHTTPClient exists in hilt pkg/tracing and sprue internal/tracing.
• No OTel elsewhere: delegator, swarf and piri-signing-service have no OTel imports.

Findings

1. should-fix. The section cites infra-nodes' docs/observability.md for what ships, but that doc's "Not shipped" line (L31) still reads "Ingot's own application metrics". An agent following the link would conclude metrics don't ship. They do: compose points Ingot's OTLP at Alloy, and infra-central's rules and forge-regions.json read ingot_local_blobs_*.
2. nit. Only one of the three appliance groups reads ingot_local_blobs_*.
3. nit. The existing pattern is an injectable Deps.MeterProvider that defaults to the global one, not the global provider directly.
4. nit. The README's metrics table is the local blob storage one.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

Fixed in 83e0d9f.

1. Citation: the section now cites the compose OTEL_EXPORTER_OTLP_ENDPOINT and infra-central's rules and dashboard, not infra-nodes' stale line. That line belongs to infra-nodes, so I'm raising it there separately.
2. Rule groups: the text now says the main Forge Regions group holds the two Ingot rules today.
3. Meter provider: "through an injectable MeterProvider that defaults to the global one".
4. README table: "a metrics table in the README: the local blob one, or a new one beside it".

The PR body is updated to match.

git diff --check is clean. This round had a should-fix, so round 2 follows.

✴️

---

Generated by Claude Code

[Peeja]

Claude reviewer says… (2nd round, 83e0d9f)

Approve. Both round 1 should-fix findings are fixed, and only nits remain.

Verified

• Round 1 fix: "say so in the PR description, naming the metric and FIL-xxxx" is in all five Central PRs, with no Linear write left.
• Delegator: its DynamoDB tables' metrics arrive through FilOne's metric stream (2026-09-grafana-telemetry.md:46-50), and it has no Postgres.
• piri-signing-service: it runs on ECS Fargate behind the application load balancer and has no database.
• swarf: it uses Postgres; its intro line and CLAUDE.md import match the other repos.
• Ingot exports: Ingot exports metrics as well as traces (cmd/telemetry.go:101-127) to the compose-set endpoint.
• Ingot in infra-central: both Ingot rules are in the "Forge Regions" group, and forge-regions.json reads ingot_local_blobs_*.
• Whitespace: git diff --check is clean in all six.

Findings

1. nit, CLAUDE.md:354-355. ingot.local_blobs.reads comes through Layered.CountBlobReads with otel.Meter, not Deps.MeterProvider. The citation names only one of the two routes.
2. nit, PR body. The attribution footer is repeated.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

1. Citation: fixed in 8bc337c, which now names both routes (s3frontend.Deps.MeterProvider, Layered.CountBlobReads).
2. Repeated footer: I added only the first attribution footer; the other two appear to be added by the tooling, which I can't control.

This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code

[Peeja]

Claude reviewer says… (round on the restructure, 005d53f)

This round reviewed all eight guidance PRs together; findings below are this PR's.

Approve. Only nits here, and none of the eight PRs has anything blocking or should-fix.

Verified, across all eight PRs

• git diff --check origin/main...HEAD is clean in each. In infra-central, make check passes at 0bc8bb7.
• Nothing was lost in the move. Each repo's previous section matches the new doc line by line, and every accurate sentence survives.
• Each short section still says when to act, what to add and when to skip. Each pointer names a heading that exists: "Adding a signal" in piri, ingot, delegator, swarf and piri-signing-service, and "Adding an alert or panel" on refactor: use syncutil.KeyedMutex #253's branch.
• Only infra-central and swarf drop a CLAUDE.md, and both had been added by the PR itself. Every other repo's existing CLAUDE.md is untouched.
• The cited paths, headings and links resolve. Each description matches its diff.

Findings for this PR

1. nit (PR body): the doc's pointer names infra-central's "Adding an alert or panel", which only exists on Add AGENTS.md with observability guidance infra-central#253's branch, and the description doesn't say to merge after it. The earlier pointer, to infra-central's AGENTS.md, had the same dependency.
2. nit (wrapping): docs/observability.md:29 is about 138 characters, in a file that wraps at 100.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

The fixes are in 2b895eb.

1. A "Merge after Add AGENTS.md with observability guidance infra-central#253" line now opens the description.
2. The paragraphs with long lines are reflowed, and links are kept whole. That leaves no line over the file's width. The text is unchanged.

Check: git diff --check is clean. The change is docs-only, so I didn't run anything else.

This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code