From 88dbb4c3353f751b0d330c70430e3f2f9249420b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 16:34:42 +0000 Subject: [PATCH 1/4] Add AGENTS.md with observability guidance Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Petra Jaros Claude-Session: https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ --- AGENTS.md | 23 +++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 24 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2b14e11 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# Agent Guidelines + +## Observability + +When a change adds or alters behavior someone depends on, decide how on-call +would see it working and see it fail, and add that in the same PR where it is +useful. Skip it for changes nothing operational depends on. + +- **Logs are what reaches Grafana today.** This service runs in Forge Central, + whose CloudWatch logs and AWS metrics (load balancer, ECS, RDS) ship to + Grafana; its own metrics don't yet + ([FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152): Ship + metrics from swarf, delegator and piri-signing-service to Grafana). Log a + failure an operator would act on at error level, with the context needed to + act on it (DIDs and CIDs, never key material), in a stable message an alert + can match. +- **Metrics.** When a feature's health is best read as a number, such as a + failure count, a queue depth or the time of the last success, note it on + [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152) so it is + instrumented when the service exports metrics. +- **Alerts and dashboard panels** live in fil-forge/infra-central, under + `terraform/envs/grafana/`; its `AGENTS.md` says how to add them. Open a + companion PR there, or say in this PR that one is needed. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 305021ebd78fb051295ad9f80d9a0dd12f98337d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 16:42:21 +0000 Subject: [PATCH 2/4] Address round 1 review of the observability guidance Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Petra Jaros Claude-Session: https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ --- AGENTS.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b14e11..f46d535 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Agent Guidelines +Swarf is the UCAN revocation service; `README.md` describes running it and its CLI. + ## Observability When a change adds or alters behavior someone depends on, decide how on-call @@ -15,9 +17,10 @@ useful. Skip it for changes nothing operational depends on. act on it (DIDs and CIDs, never key material), in a stable message an alert can match. - **Metrics.** When a feature's health is best read as a number, such as a - failure count, a queue depth or the time of the last success, note it on - [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152) so it is - instrumented when the service exports metrics. + failure count, a queue depth or the time of the last success, say so in the + PR description, naming the metric and + [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152), so it can + be carried to the issue and instrumented when the service exports metrics. - **Alerts and dashboard panels** live in fil-forge/infra-central, under `terraform/envs/grafana/`; its `AGENTS.md` says how to add them. Open a companion PR there, or say in this PR that one is needed. From 7ff3da09d74ce5b34d97744ebb5bd52dc669c5e4 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 19:17:21 +0000 Subject: [PATCH 3/4] Keep the always-loaded guidance short, and move the how-to to docs Following bajtos's review of fil-forge/infra-nodes#174: the guidance file loads into every session, so its Observability section is now a short reminder of what to add and when to skip it, with a pointer to docs/observability.md, which holds the detail. A CLAUDE.md that only imported AGENTS.md is gone where this PR added one: Claude Code reads AGENTS.md itself from v2.1.277. Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Petra Jaros Claude-Session: https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ --- AGENTS.md | 23 +++++------------------ CLAUDE.md | 1 - docs/observability.md | 23 +++++++++++++++++++++++ 3 files changed, 28 insertions(+), 19 deletions(-) delete mode 100644 CLAUDE.md create mode 100644 docs/observability.md diff --git a/AGENTS.md b/AGENTS.md index f46d535..3d81440 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,21 +6,8 @@ Swarf is the UCAN revocation service; `README.md` describes running it and its C When a change adds or alters behavior someone depends on, decide how on-call would see it working and see it fail, and add that in the same PR where it is -useful. Skip it for changes nothing operational depends on. - -- **Logs are what reaches Grafana today.** This service runs in Forge Central, - whose CloudWatch logs and AWS metrics (load balancer, ECS, RDS) ship to - Grafana; its own metrics don't yet - ([FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152): Ship - metrics from swarf, delegator and piri-signing-service to Grafana). Log a - failure an operator would act on at error level, with the context needed to - act on it (DIDs and CIDs, never key material), in a stable message an alert - can match. -- **Metrics.** When a feature's health is best read as a number, such as a - failure count, a queue depth or the time of the last success, say so in the - PR description, naming the metric and - [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152), so it can - be carried to the issue and instrumented when the service exports metrics. -- **Alerts and dashboard panels** live in fil-forge/infra-central, under - `terraform/envs/grafana/`; its `AGENTS.md` says how to add them. Open a - companion PR there, or say in this PR that one is needed. +useful: logs, and an alert or dashboard panel in fil-forge/infra-central. Skip +it for changes nothing operational depends on. When a feature's health is best +read as a number, say so in the PR description, naming the metric and +[FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152). "Adding a +signal" in `docs/observability.md` says how to do each. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 43c994c..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -@AGENTS.md diff --git a/docs/observability.md b/docs/observability.md new file mode 100644 index 0000000..5260e25 --- /dev/null +++ b/docs/observability.md @@ -0,0 +1,23 @@ +# Observability + +How this service's failures reach on-call, and what a change adds so that they +do. + +## Adding a signal + +- **Logs are what reaches Grafana today.** This service runs in Forge Central, + whose CloudWatch logs and AWS metrics (load balancer, ECS, RDS) ship to + Grafana; its own metrics don't yet + ([FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152): Ship + metrics from swarf, delegator and piri-signing-service to Grafana). Log a + failure an operator would act on at error level, with the context needed to + act on it (DIDs and CIDs, never key material), in a stable message an alert + can match. +- **Metrics.** When a feature's health is best read as a number, such as a + failure count, a queue depth or the time of the last success, say so in the PR + description, naming the metric and + [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152), so it can + be carried to the issue and instrumented when the service exports metrics. +- **Alerts and dashboard panels** live in fil-forge/infra-central, under + `terraform/envs/grafana/`; its `docs/observability.md` ("Adding an alert or panel") says how to add them. Open a + companion PR there, or say in this PR that one is needed. From 72018b490d9123dcbbbf7992d8210001fe6f298e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 19:37:28 +0000 Subject: [PATCH 4/4] Rewrap docs/observability.md Review round on the guidance restructure: some paragraphs were never reflowed after the pointer edit. Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Petra Jaros Claude-Session: https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ --- docs/observability.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/observability.md b/docs/observability.md index 5260e25..ae228b3 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -19,5 +19,6 @@ do. [FIL-1152](https://linear.app/filecoin-foundation/issue/FIL-1152), so it can be carried to the issue and instrumented when the service exports metrics. - **Alerts and dashboard panels** live in fil-forge/infra-central, under - `terraform/envs/grafana/`; its `docs/observability.md` ("Adding an alert or panel") says how to add them. Open a - companion PR there, or say in this PR that one is needed. + `terraform/envs/grafana/`; its `docs/observability.md` ("Adding an alert or + panel") says how to add them. Open a companion PR there, or say in this PR + that one is needed.