feat(observability): add structured tags to all 10 counters (#35)

[blehnen]

Closes #35.

Summary

• All 10 counters on Meter "FrigateRelay" now emit structured tags so dashboards can pivot by subscription, camera, action, validator, reason, and component. Tag matrix matches the inventory in Add structured tags (camera/action/subscription) to FrigateRelay meters #35 with one structural amendment captured in .shipyard/phases/13/CONTEXT-13.md D5: events.received is tagged with camera + label only (the increment site is pre-subscription-match; tagging by subscription would have changed the counter's semantic meaning).
• Tag construction is centralized via 10 new internal static void Increment* helpers on DispatcherDiagnostics so every call site is a one-liner and a future tag drift becomes a single-file edit. The eviction callback in ChannelActionDispatcher consumes the full evicted DispatchItem (no callback-shape change). Per-counter XML doc-comments list the tag set + cardinality rule + the "if you add a counter here, update docs/observability.md" reminder.
• New tests/FrigateRelay.Host.Tests/Observability/CounterTagMatrixTests.cs adds 10 MeterListener-based tag-presence tests (one per counter). Each test asserts the expected tag KEYS, that VALUES match the test-scenario sentinels, and that event_id is absent — a per-test cardinality-bomb tripwire so a future contributor adding an 11th counter test cannot silently omit the rule.
• Cross-phase change: the Phase-9 test ErrorsUnhandled_*_Untagged (which asserted errors.unhandled carried no tags) is renamed _TaggedWithComponent and updated to assert the new component=EventPump tag. Operators gain per-subsystem error triage; Phase 9's deliberately-tagless decision is intentionally overruled.
• CHANGELOG [Unreleased] ### Added entry. docs/observability.md is referenced as forthcoming (lands in PR Document metrics + add sample Grafana dashboard (docs/observability.md) #36 / Wave 2 of Phase 13).

What this is NOT

• Not the dashboard / docs work — docs/observability.md, docker/observability/ and the Grafana dashboard JSON ship in PR Document metrics + add sample Grafana dashboard (docs/observability.md) #36 (Wave 2 of Phase 13).
• Not the BlueIris template collapse — that's PR refactor(blueiris): collapse BlueIrisUrlTemplate into a thin wrapper around EventTokenTemplate (allowlist drift cleanup) #34 (Wave 3).

Test plan

• CI green on ubuntu-latest and windows-latest (Linux + Windows warnings-as-errors gate).
• dotnet build FrigateRelay.sln -c Release reports 0 warnings, 0 errors locally.
• bash .github/scripts/run-tests.sh --skip-integration reports 239 tests, 0 failures (up from 229 baseline = +10 from CounterTagMatrixTests).
• git grep '"event_id"' src/FrigateRelay.Host/Dispatch/ returns empty (CONTEXT-13 hard rule: event_id is the cardinality-bomb tag and must never appear at an increment site).
• git grep -nE 'App\.Metrics|OpenTracing|Jaeger\.' src/ still empty (architectural invariant unchanged).
• Spot-check that aggregate Prometheus queries that don't filter on tags still return the same totals as v1.0.x scrapers — metric names persist, only series cardinality grows.

Follow-ups

• ID-29 (filed): eviction-callback log captures stale plugin.Name from loop variable. Pre-existing closure-capture pattern surfaced by this refactor; counter tags themselves are correct. One-line fix in a follow-up PR.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Implemented structured telemetry with component-specific tags across all diagnostic counters for improved observability and monitoring.
  • Added component tag to unhandled error metrics to better categorize failures by subsystem.

• Documentation

  • Advanced project roadmap to Phase 13: v1.1 observability and structural cleanup planning.
  • Updated project scope with v1.1 observability goals and verification criteria.

• Tests

  • Added comprehensive tag validation tests to ensure metrics emit correct structured tags and prevent high-cardinality tagging.

[coderabbitai]

Warning

Rate limit exceeded

@blehnen has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 41 minutes and 31 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 23485f8a-60a8-4f98-b8be-5b217af92304

📥 Commits

Reviewing files that changed from the base of the PR and between 6928164 and 4f2b874.

📒 Files selected for processing (2)

• .shipyard/ROADMAP.md
• tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs

📝 Walkthrough

Walkthrough

Phase 13 advances Shipyard to v1.1 with observability focus. Structured tags are added to all FrigateRelay counters via new DispatcherDiagnostics helper methods. Existing increment sites are refactored to use helpers, centralizing tag construction. Counter tag matrix tests enforce tagging contracts.

Changes

Observability Infrastructure & Tagging

Layer / File(s)	Summary
Planning & Versioning .shipyard/HISTORY.md, .shipyard/PROJECT.md, .shipyard/ROADMAP.md, .shipyard/STATE.json, .shipyard/STATE.json.sha256	Shipyard advanced from Phase 12 to Phase 13. New v1.1 scope documented: structured counter tags, observability docs/dashboard/compose stack, and BlueIrisUrlTemplate allowlist consolidation. Phase 13 open questions captured (per-counter tag ownership, Makefile verify-observability, Grafana version, error-message contracts).
Changelog CHANGELOG.md	Unreleased section updated to note 10 counters now instrumented with structured tags via DispatcherDiagnostics.Increment* helpers, event_id tag forbidden via CI grep, and errors.unhandled now carries component tag.
Helper Method Infrastructure src/FrigateRelay.Host/Dispatch/DispatcherDiagnostics.cs	Added 10 internal static increment helpers encapsulating tag construction for each counter (e.g., IncrementActionsDispatched, IncrementErrorsUnhandled). Each helper derives tags from EventContext/DispatchItem and enforces no event_id. Updated XML docs with counter inventory, tag keys, and cardinality rules.
Dispatcher Integration src/FrigateRelay.Host/Dispatch/ChannelActionDispatcher.cs	Updated 5 increment sites to call DispatcherDiagnostics helpers instead of manually constructing TagList: eviction → IncrementDrops(item, "channel_full"); enqueue → IncrementActionsDispatched(item); validators passed/rejected → IncrementValidatorsPassed/Rejected(item, name); success/exhausted/failure → IncrementActionsSucceeded/Exhausted/Failed(item).
Event Pump Integration src/FrigateRelay.Host/EventPump.cs	Updated 3 increment sites to use helpers: received → IncrementEventsReceived(context); matched → IncrementEventsMatched(context, subName); unhandled error → IncrementErrorsUnhandled("EventPump").
Test Coverage tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs	Updated existing test method ErrorsUnhandled_Increments_OnPumpFault_Once_Untagged → ErrorsUnhandled_Increments_OnPumpFault_Once_TaggedWithComponent to assert component tag is present with value "EventPump".
Tag Matrix Validation tests/FrigateRelay.Host.Tests/Observability/CounterTagMatrixTests.cs	Added CounterTagMatrixTests suite with 10 test methods (one per counter) using MeterListener to capture and assert exact tag key sets, verify sentinel tag values, and forbid event_id. Includes helper methods for listener setup, tag extraction, and fixture construction.

Sequence Diagram

sequenceDiagram
    participant EventPump
    participant ChannelActionDispatcher
    participant DispatcherDiagnostics
    participant Meter as Counter/Meter<br/>(FrigateRelay)

    EventPump->>DispatcherDiagnostics: IncrementEventsReceived(context)
    DispatcherDiagnostics->>Meter: Add(1, tags: camera, label)
    
    EventPump->>DispatcherDiagnostics: IncrementEventsMatched(context, sub)
    DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, label)
    
    EventPump->>ChannelActionDispatcher: EnqueueAsync(event)
    ChannelActionDispatcher->>DispatcherDiagnostics: IncrementActionsDispatched(item)
    DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, action)
    
    ChannelActionDispatcher->>ChannelActionDispatcher: Validate(item)
    ChannelActionDispatcher->>DispatcherDiagnostics: IncrementValidatorsPassed/Rejected(item, name)
    DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, validator, action)
    
    ChannelActionDispatcher->>ChannelActionDispatcher: ExecuteAsync(plugin)
    alt Success
        ChannelActionDispatcher->>DispatcherDiagnostics: IncrementActionsSucceeded(item)
        DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, action)
    else Exhausted
        ChannelActionDispatcher->>DispatcherDiagnostics: IncrementExhausted(item)
        DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, action)
    else Failed
        ChannelActionDispatcher->>DispatcherDiagnostics: IncrementActionsFailed(item)
        DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, action)
    end
    
    alt Channel Full
        ChannelActionDispatcher->>DispatcherDiagnostics: IncrementDrops(item, "channel_full")
        DispatcherDiagnostics->>Meter: Add(1, tags: subscription, camera, reason)
    end
    
    EventPump->>DispatcherDiagnostics: IncrementErrorsUnhandled("EventPump")
    DispatcherDiagnostics->>Meter: Add(1, tags: component)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Add structured tags (camera/action/subscription) to FrigateRelay meters #35 (linked): This PR directly implements the structured tagging proposal from Issue #35 — all 10 counters now have the tag inventory specified (camera/label/subscription/action/validator/reason/component), helper methods centralize tag construction, and CI enforcement + cardinality docs prevent event_id tagging.
• Document metrics + add sample Grafana dashboard (docs/observability.md) #36: Related observability issue that depends on this PR's tagging foundation; the dashboard and Grafana configuration scope in #36 becomes actionable only after counters are tagged.

Poem

🐰 Hops with glee at metrics so fine,
Tags flow through each counter's line,
Camera, label, action unite,
No cardinality blight!
Observability shines so bright. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: adding structured tags to all 10 counters in the observability domain, which aligns with issue #35.
Description check	✅ Passed	The PR description is comprehensive and follows the template structure with summary, type of change (new feature), detailed checklist items, test plan, and follow-ups, addressing all major aspects of the change.
Linked Issues check	✅ Passed	All acceptance criteria from issue #35 are met: every increment site uses helper methods passing structured tags; 10 MeterListener tests assert tag presence and absence of event_id; XML doc-comments document tags and cardinality rules; and git grep verification is part of the test plan.
Out of Scope Changes check	✅ Passed	All code changes align with issue #35 scope: adding tags to 10 counters, centralizing tag construction, and adding validation tests. Documentation-only updates to HISTORY/ROADMAP/PROJECT are ancillary to PR delivery and do not introduce out-of-scope features.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 41 minutes and 31 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs (1)

202-207: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Stale section comment contradicts the updated test.

The section header at line 203 still reads "with NO tags" but the test was renamed and the assertion now verifies component = "EventPump". Anyone reading the comment before the assertion body will be misled.

✏️ Proposed fix

-    // Test 8: errors.unhandled increments ONCE with NO tags when IEventSource throws
+    // Test 8: errors.unhandled increments ONCE with component="EventPump" tag when IEventSource throws

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs` around
lines 202 - 207, Update the stale test section header comment that currently
says "with NO tags" to reflect the test's new behavior: change the header to
indicate the error is tagged with the component (e.g., "errors.unhandled
increments ONCE when IEventSource throws, TAGGED with component 'EventPump'") or
remove the misleading phrase; ensure this comment sits immediately above the
test method ErrorsUnhandled_Increments_OnPumpFault_Once_TaggedWithComponent so
it accurately describes the assertion that the counter is tagged with component
= "EventPump".

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.shipyard/ROADMAP.md:
- Around line 415-417: Update the "Phase Count" section to reflect the new Phase
13: change the line that reads "**12 phases.** Within the 8–14 range requested.
Phases 1–2 parallelizable after the `.sln` exists; Phases 3–12 sequential." to
state "**13 phases.** Within the 8–15 range requested. Phases 1–2 parallelizable
after the `.sln` exists; Phases 3–13 sequential." so the total count and the
sequential phase range both match the added phase.

---

Outside diff comments:
In `@tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs`:
- Around line 202-207: Update the stale test section header comment that
currently says "with NO tags" to reflect the test's new behavior: change the
header to indicate the error is tagged with the component (e.g.,
"errors.unhandled increments ONCE when IEventSource throws, TAGGED with
component 'EventPump'") or remove the misleading phrase; ensure this comment
sits immediately above the test method
ErrorsUnhandled_Increments_OnPumpFault_Once_TaggedWithComponent so it accurately
describes the assertion that the counter is tagged with component = "EventPump".

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3412a27e-f740-41f8-aa2a-05225f166766

📥 Commits

Reviewing files that changed from the base of the PR and between 085283b and 6928164.

📒 Files selected for processing (11)

• .shipyard/HISTORY.md
• .shipyard/PROJECT.md
• .shipyard/ROADMAP.md
• .shipyard/STATE.json
• .shipyard/STATE.json.sha256
• CHANGELOG.md
• src/FrigateRelay.Host/Dispatch/ChannelActionDispatcher.cs
• src/FrigateRelay.Host/Dispatch/DispatcherDiagnostics.cs
• src/FrigateRelay.Host/EventPump.cs
• tests/FrigateRelay.Host.Tests/Observability/CounterIncrementTests.cs
• tests/FrigateRelay.Host.Tests/Observability/CounterTagMatrixTests.cs