Skip to content

fix(metrics): report a corrupt hooks.json once, not every export - #23101

Merged
KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/webhook-count-probe-warns-once
Oct 22, 2026
Merged

KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:claude/webhook-count-probe-warns-once

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A hooks.json that does not parse is reported in the gateway log once, not once per metrics export interval.

The kirocrew.inventory.webhooks.registered gauge calls webhooks.registered_context_count() every export interval (60 s by default). That function read hooks.json through webhooks._read_json, which logs webhook store unreadable (<path>): <error> at WARNING on every failed parse. A file that stays corrupt therefore adds a WARNING to gateway.log every minute. That goes around the probe's own _note_probe_failure, which exists to warn once and drop repeats to DEBUG. The message also calls the file the "webhook store", though hooks.json is shared with the script-hook store. The Opus review on #22223 named this.

Why it matters

An operator with metrics on and one bad byte in hooks.json gets 1,440 identical warnings a day, which bury everything else in the log. The probe's warn-once rule was written to prevent exactly that.

Not a goal

  • Changing _read_json. Its warning stays for the webhook store's own readers and writers, where a failed read refuses an operation.
  • Changing what the gauge reports: still no observation and a counted probe failure for a corrupt file, 0 for a missing one.
  • Repairing or replacing a corrupt hooks.json.

What changed (motivation → approach → change)

  • Symptom: one webhook store unreadable WARNING per export interval while hooks.json is corrupt.
  • Cause: registered_context_count, whose only caller is the gauge, read through _read_json, which logs every failure. The function's contract is to answer (0, False) for an unreadable file and leave the reporting to its caller.
  • Change: registered_context_count parses the file itself with the same read_bytes_with_retry + json.loads that _read_json uses. A missing file is still (0, True), and a parse or read error is (0, False), now without a log line. The probe still counts every failure and warns once (_note_probe_failure).
  • The metrics.md row for the gauge now says the read does not log and the probe reports a corrupt file once.

Backwards compatibility

Compatible: the function returns the same pair for every input, and its only caller is the gauge. The one difference is a log line that is no longer written.

Removes nothing: no path, field, key or validator is removed; the probe's warning and failure count still report the fault.

Tests

  • test_registered_webhooks_corrupt_file_warns_once_across_export_intervals (new, test/metrics/test_inventory_gauges.py) reads a corrupt hooks.json through the probe three times. It asserts exactly one WARNING is logged (the probe's, naming 'webhooks') and the failure count is 3.
  • Red before: with origin/main's webhooks.py the new test fails: the warnings include webhook store unreadable (...hooks.json): Expecting property name enclosed in double quotes ... on every read.
  • The existing missing-file, empty-object, corrupt-file and non-object tests in the same file still pass unchanged.
  • Local runs: test/metrics/test_inventory_gauges.py and every test/test_webhook*.py file (335 passed, 1 skipped). black (my hunk; webhooks.py is on the black baseline and black's diff does not touch it), isort, flake8, mypy on the changed module, check_black_formatting.py, check_comment_history.py, check_brand_name.py and docs-lint.sh are clean.

Manual verification

N/A — unit coverage sufficient: the test drives the real probe and reader against a real corrupt file and reads the log records, which is the whole behaviour.

Related Issues

Closes #23098

Follows the Opus review finding on #22223.

Pattern harvest

Not generalizable: a reader that logs on failure is right for the store it serves. The defect was one caller, a periodic probe, borrowing it while it already reports failures itself.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

The webhook-registration gauge reads hooks.json through
webhooks.registered_context_count once per export interval. That read
went through _read_json, which logs "webhook store unreadable" at
WARNING on every failed parse, so a file that stayed corrupt logged
once a minute and went around the probe's own warn-once note.

registered_context_count now parses the file itself and returns
(0, False) on a parse or read error without logging. The probe still
counts every failure and warns once.

Closes kirodotdev#23098

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and KiroCrewCaptain as code owners October 22, 2026 13:41
@leonlaiyc
leonlaiyc requested a review from CrysisDeu October 22, 2026 13:41
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision c8c7e9064de8c443def9217210829523f24f730d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of c8c7e9064de8c443def9217210829523f24f730d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The rewritten read sorts every input into the same outcome _read_json did (a decode error is a ValueError), so only the per-interval log line goes away, and the probe's warn-once note still reports the fault.

Notes

  • The read-and-parse is now duplicated from _read_json. If a third quiet reader shows up, move the shared read-and-classify step into one helper that leaves logging to its caller, instead of making a third copy.

[DESIGN-REVIEWED] c8c7e90

Description read

[DESCRIPTION-READ] 88828d5db300df7732c207a5a979226683437353dbb383a5030e84cc6a8c3fa6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of c8c7e9064de8c443def9217210829523f24f730d via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The fix is at the cause: the periodic caller stops borrowing a reader that logs, and _read_json keeps its warning for the store's own readers and writers.

What this change ships

Inventory (3 items) — 3 justified

Intent: an operator whose hooks.json stays corrupt should see one warning in the gateway log, not one every metrics export interval. FIX.

  1. A corrupt hooks.json no longer adds a webhook store unreadable WARNING every export interval. The probe's own warn-once message reports it once instead — justified
  2. The metrics.md gauge row and the registered_context_count docstring now say the read does not log — justified
  3. A new test checks that three probe reads of a corrupt file log exactly one WARNING and count 3 failures — justified

[FIRST-PRINCIPLES-REVIEWED] c8c7e90

Description read

[DESCRIPTION-READ] 92aaf2e3fb4d420cd75b497a238f400fd76a943ed53407c3dccc8db4fd351129

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed c8c7e9064de8c443def9217210829523f24f730d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c8c7e90

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed c8c7e9064de8c443def9217210829523f24f730d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c8c7e90

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 22, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 22, 2026 16:04

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: the webhook registration count reads hooks.json without the store reader's per-read warning, so a corrupt file is reported once by the metrics probe instead of on every export interval; a new test pins the single warning. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/metrics.md.

@KiroCrewCaptain
KiroCrewCaptain merged commit 0ce632d into kirodotdev:main Oct 22, 2026
102 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A corrupt hooks.json logs "webhook store unreadable" every metrics export interval

2 participants