Skip to content

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

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

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

Conversation

@leoparente

@leoparente leoparente commented Nov 17, 2026 •

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 — Net-positive change. Policy-level and per-target attributes are threaded consistently through label building, Prometheus name conversion, and refusal/rollback paths, with sanitized keys and consistently-escaped values reaching exposition output. No correctness or security 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.11 · 3689k in (95% cached) · 22k out

@leoparente leoparente changed the title feat(policies): attributes on every series of a policy (MON-445) feat(policies): attributes on every series of a policy Nov 17, 2026
@leoparente leoparente closed this Nov 17, 2026
@leoparente
leoparente deleted the feat/MON-445-policy-attributes branch November 17, 2026 01:15
@github-actions

Copy link
Copy Markdown

LCOV of commit 197b7b6 during Debug Builds #291

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

Files changed coverage rate: n/a

Full coverage report

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