Skip to content

feat(policies): attributes on every series of a policy - #816

Draft
leoparente wants to merge 7 commits into
developfrom
feat/policy-attributes
Draft

leoparente wants to merge 7 commits into
developfrom
feat/policy-attributes

Conversation

@leoparente

Copy link
Copy Markdown
Contributor

(Tracked in MON-445.) A policy can now carry attributes: key/value pairs that pktvisor puts on every series of every handler of that policy, in the OTLP push and in Prometheus output. Netprobe targets can override them per target. The aim is to let a collector attach context such as a NetBox site, tenant or device id to the series a policy produces.

What changed

  • Policy attributes. A top-level attributes mapping next to kind, input, handlers and config. Policy::series_labels is now the one place the per-handler and merged-handlers export paths build their labels: the policy's attributes, then policy and handler on top. A policy without attributes, or with a null one, exports exactly what it did before. JSON output is unchanged.
  • Values stay as written. Values are read as the YAML scalar's text ("007" stays 007), never through Configurable.
  • Prometheus names. OTLP keeps a key as written. Prometheus output writes it with each character outside [A-Za-z0-9_] as _, one per code point (netbox.site.name becomes netbox_site_name). The serializer now writes converted names straight into the line, and builds its static-label set only when static labels exist.
  • Refused at load, naming the policy (and the target) and the key:
    • a key that is empty, not valid UTF-8, or does not start with an ASCII letter;
    • two keys that share a Prometheus name;
    • a map, list, null or empty value;
    • a key that is, or becomes after conversion, a label pktvisor sets on the policy's series: policy, handler, tap, le, quantile, any static label, and each handler's own labels (StreamHandler::own_label_names).
      A refused policy rolls back like any other load failure.
  • Netprobe per-target attributes under input.config.targets.<name>.attributes, laid over the policy's key by key, then target. They are read from the policy YAML and kept out of the input's config, so policies that differ only in them share one input. A new AbstractMetricsManager::on_new_bucket hook hands the immutable map to each fresh bucket under the bucket lock. Merged buckets carry it through specialized_merge.
  • Legacy /metrics: the default policy's attributes are included.
  • Docs: README, RFC 76, and the netprobe and flow handler READMEs. Flow takes policy-level attributes only; device_map is unchanged.

Compatibility

  • An older pktvisor ignores policy-level attributes. It reads per-target attributes as input config, so an all-digit value past 2^64 makes it refuse the policy, and policies that differ only in target attributes get separate inputs.
  • Values containing \ followed by three digits are rewritten by the existing label-value escaping. The docs say so.

Tests

  • New: src/tests/test_policy_attributes.cpp (policy, target, refusal and rollback, shared input, null, YAML error location), plus additions to test_prometheus_serializer.cpp, test_core_server.cpp, handlers/netprobe/test_net_probe.cpp and inputs/netprobe/test_netprobe.cpp.
  • ctest on macOS (Debug): 24/25. unit-tests-input-netprobe fails on the same two TCP-timeout cases on unchanged develop on this machine; the new case in that suite passes.

Merge order

🤖 Generated with Claude Code

leoparente and others added 7 commits November 16, 2026 21:00
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… sets

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tes as none

Keys must be non-empty valid UTF-8 starting with an ASCII letter; a null
attributes is none; the input node is kept as is without target attributes
so YAML errors keep their position; Prometheus names map one _ per code
point; the legacy /metrics path carries the policy's attributes. Docs say
what an older pktvisor does with target attributes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@nbl-ai-review

nbl-ai-review Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

AI Code Review — risk tier: Full · dimensions run: correctness, security

Advisory only. A human owns the merge decision.

Summary — This is a net-positive change. Policy attributes are plumbed consistently through Policy::series_labels, the Prometheus/OTLP export paths, and netprobe per-target overrides, with load-time validation guarding against colliding or reserved label names. The feature is config-driven (operator-authored YAML) and values are properly escaped at every output sink, so no injection or correctness defects were found.

No findings.

🤖 AI Code Review · run · prompts: code-review/v1 · models: claude-sonnet-5/medium · context: description · 0 comment(s) · 0 prior AI review(s) · usage: $2.01 · 4378k in (97% cached) · 16.6k out

@github-actions

Copy link
Copy Markdown

LCOV of commit 197b7b6 during Debug Builds #292

Summary coverage rate:
  source files: 151
  lines.......: 88.4% (21019 of 23772 lines)
  functions...: 82.2% (2216 of 2696 functions)
  branches....: no data found
Message summary:
  no messages were reported

Files changed coverage rate: n/a

Full coverage report

@leoparente

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T12:32:45.935900Z 197b7b6 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 197b7b63cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant