feat: Add PZ metrics for tag count BED-7841

[AD7ZJ]

Description

Instrument the number of nodes tagged by privilege zones or user tags.

Motivation and Context

Resolves https://specterops.atlassian.net/browse/BED-7841

How Has This Been Tested?

This new metric is verified in an existing integration test. Also tested locally to produce the following output on /metrics:

# TYPE bh_analysis_pzm_node_tags_total counter
bh_analysis_pzm_node_tags_total{action="tag_added",position="1"} 0
bh_analysis_pzm_node_tags_total{action="tag_added",position="owned"} 0
bh_analysis_pzm_node_tags_total{action="tag_removed",position="1"} 0
bh_analysis_pzm_node_tags_total{action="tag_removed",position="owned"} 0

Screenshots (optional):

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist:

• I have met the contributing prerequisites
  • Assigned myself to this PR
  • Added the appropriate labels
  • Associated an issue: Issues and Pull Requests README #672
  • Read the Contributing guide: https://github.com/SpecterOps/BloodHound/wiki/Contributing
• I have ensured that related documentation is up-to-date
  • Open API docs
  • Code comments (GoDocs / JSDocs)
• I have followed proper test practices
  • Added/updated tests to cover my changes
  • All new and existing tests passed

Summary by CodeRabbit

• Chores
  • Added Prometheus metrics integration for the analysis subsystem and wired those metrics into global metrics registration so tag add/remove events are recorded with position context.
• Tests
  • Updated integration tests to verify the new metrics are emitted and that tag lifecycle counters (adds/removals and position grouping) behave as expected during analysis.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Prometheus instrumentation for privilege-zone tag changes: defines a counter vector with action and position labels, records tag additions/removals in AGT tagging, asserts counters in AGT tests, and registers the metrics during BHCE metrics setup.

Changes

Analysis subsystem Prometheus metrics

Layer / File(s)	Summary
Prometheus counter definition and registration infrastructure packages/go/analysis/metrics.go	Defines the unexported Prometheus counter vector pzNodeTagCounterVec, implements tagToPosition(model.AssetGroupTag) for the position label, and adds RegisterAnalysisMetrics(registerer prometheus.Registerer) error to register the metric.
Analysis metrics registration wiring packages/go/metricsregistration/metricsregistration.go	Imports the analysis package and calls analysis.RegisterAnalysisMetrics from RegisterBHCEMetrics, returning a wrapped error if registration fails.
Privilege zone tag metrics recording in AGT packages/go/analysis/agt.go	Imports the Prometheus client and increments pzNodeTagCounterVec for tag_added and tag_removed after per-tag in-memory node tagging, using action and position labels derived from the tag.
AGT tests assert metric values packages/go/analysis/agt_test.go, go.mod	Adds Prometheus test imports, resets the counter vector in relevant subtests, and asserts expected tag_added/tag_removed counter values (including the computed position label). go.mod gains an indirect test dependency.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and clearly describes the main feature addition: adding Prometheus metrics for privilege zone tag counts, directly aligned with the PR's primary objective.
Description check	✅ Passed	The PR description is well-structured, includes all required sections from the template, provides clear context (with Jira ticket BED-7841), detailed testing information with metric output examples, and confirms all checklist items are completed.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch BED-7841--Metrics-pz-tag-count

---

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

[coderabbitai]

🧹 Nitpick comments (1)

packages/go/analysis/agt_test.go (1)

434-514: 💤 Low value

Tier tag test looks good; consider adding owned tag coverage.

The new tier tag subtest comprehensively validates the position label calculation for tier tags. Test coverage now includes label tags (2 subtests) and tier tags (1 subtest). For completeness, consider adding a similar test for AssetGroupTagTypeOwned to verify the "owned" position label, though it would exercise the same code path as label tags.

🤖 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 `@packages/go/analysis/agt_test.go` around lines 434 - 514, Add a parallel
subtest that covers AssetGroupTagTypeOwned like the existing tier subtest:
create an owned tag via bhDB.CreateAssetGroupTag with
model.AssetGroupTagTypeOwned, create a selector via
bhDB.CreateAssetGroupTagSelector, create nodes that should be added and nodes
that already carry the tag to be removed (using graph.Transaction CreateNode and
attaching tagKind where needed), call tagAssetGroupNodesForTag(testCtx, bhDB,
graphDB, tag, exclusionSet, nodesToUpdate), and assert nodesToUpdate length and
pzNodeTagCounterVec counts with
prometheus.Labels{"action":"tag_added","position":"owned"} and
{"action":"tag_removed","position":"owned"} to verify the "owned" position
label; mirror the setup steps from the tier subtest and reuse symbols
tagAssetGroupNodesForTag, pzNodeTagCounterVec, CreateAssetGroupTag,
CreateAssetGroupTagSelector, and tag.ToKind() for locating the code to copy.

🤖 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.

Nitpick comments:
In `@packages/go/analysis/agt_test.go`:
- Around line 434-514: Add a parallel subtest that covers AssetGroupTagTypeOwned
like the existing tier subtest: create an owned tag via bhDB.CreateAssetGroupTag
with model.AssetGroupTagTypeOwned, create a selector via
bhDB.CreateAssetGroupTagSelector, create nodes that should be added and nodes
that already carry the tag to be removed (using graph.Transaction CreateNode and
attaching tagKind where needed), call tagAssetGroupNodesForTag(testCtx, bhDB,
graphDB, tag, exclusionSet, nodesToUpdate), and assert nodesToUpdate length and
pzNodeTagCounterVec counts with
prometheus.Labels{"action":"tag_added","position":"owned"} and
{"action":"tag_removed","position":"owned"} to verify the "owned" position
label; mirror the setup steps from the tier subtest and reuse symbols
tagAssetGroupNodesForTag, pzNodeTagCounterVec, CreateAssetGroupTag,
CreateAssetGroupTagSelector, and tag.ToKind() for locating the code to copy.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 26d5a81e-3e40-400d-aa9b-fb0bff78e6d0

📥 Commits

Reviewing files that changed from the base of the PR and between 9332765 and c7c6524.

📒 Files selected for processing (3)

• packages/go/analysis/agt.go
• packages/go/analysis/agt_test.go
• packages/go/analysis/metrics.go

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/go/analysis/agt.go