project-writing-go-modules-framework-v2

name	project-writing-go-modules-framework-v2
description	Use when creating or migrating a Go go.d collector to framework V2, touching CollectorV2, metrix.CollectorStore, ChartTemplateYAML/charts.yaml, charttpl/chartengine, V2 host scopes/vnodes, or V2 collector tests. Focuses on concise maintainer-preferred V2 collector patterns.

Writing Go go.d Modules With Framework V2

Use with project-writing-collectors. Keep this skill loaded for style; read source files for evidence.

Read First

• Contract: src/go/plugin/framework/collectorapi/collector.go
• Framework-change workflow: src/go/plugin/framework/docs/changing-framework-code.md
• Canonical new-collector guide: src/go/plugin/go.d/docs/how-to-write-a-collector.md
• Helper-package guide: src/go/plugin/go.d/docs/helper-packages.md
• V1-to-V2 migration guide: src/go/plugin/go.d/docs/migrate-v1-to-v2.md
• Runtime/chart lifecycle: src/go/plugin/framework/chartengine/README.md
• Template format: src/go/plugin/framework/charttpl/README.md
• Host scopes/vnodes: .agents/skills/project-writing-go-modules-framework-v2/go-v2-host-scope.md
• Primary modern example: src/go/plugin/go.d/collector/cato_networks/. Use focused pieces from it, not the whole collector shape.
• Older V2 collectors can still be useful for local patterns, but review them for stale style before treating them as examples.

Decision Discipline

• You MUST aim for the clean end state, not the smallest collector diff. If a framework capability is missing and the problem is general, design the framework change instead of hiding the issue in collector-local glue.
• If any framework-scope package changes, stop and satisfy src/go/plugin/framework/docs/changing-framework-code.md before writing code.
• You MUST re-check scope after each coherent batch. If the work reveals an independent collector cleanup, framework fix, or integration-doc change, either defer it explicitly or land it separately before continuing.

Core Style

• New collectors MUST implement collectorapi.CollectorV2 from src/go/plugin/framework/collectorapi/collector.go and register via CreateV2.
• New() SHOULD own defaults, metrix.NewCollectorStore(), typed metric instruments, and test seams.
• V2 collectors MUST write metrics through metrix.CollectorStore during Collect() and provide chart template YAML through ChartTemplateYAML(); embedded charts.yaml is RECOMMENDED.
• Collect(ctx) MUST return error and write metrics to metrix; it MUST NOT return a V1 map[string]int64.
• Long-running side-effect loops that must start only with the running job MAY implement optional collectorapi.CollectorV2Runner. Run(ctx) MUST return promptly after cancellation. Do not start operational polling from Init() or Check(), because DynCfg test and autodetection use those methods without starting the runtime job.
• Collector Cleanup(ctx) MUST be idempotent. The framework may call it more than once, including after partial Init / Check setup.
• Files SHOULD stay boring: public lifecycle methods in collector.go, setup helpers in init.go when needed, orchestration in collect.go, distinct upstream operations in collect_<operation>.go, metrics in metrix.go / write_metrics.go, focused tests.
• Before adding custom HTTP, selector, logging, command-execution, SQL, ping, or log-file plumbing, check src/go/plugin/go.d/docs/helper-packages.md and reuse an existing helper when it fits.
• If Functions exist, isolate them in a <name>func/ subpackage with a narrow Deps interface declared there. The Function package MUST NOT import the collector package or hold *Collector.
• If a single-instance collector exposes Creator.SharedFunctions, its MethodHandler(job) receives the running canonical runtime job and the public Function shape has no __job parameter. Use job.Collector() to bind the Function handler to collector-owned state; do not add a package-global registry to bridge Function dispatch. The Function is still job-backed: publication waits for the canonical job to be running and available, and dispatch rejects unavailable jobs before calling .

Metrics And Charts

• Instruments SHOULD be created once when the metric surface is known.
• Use store.Write().SnapshotMeter("") for normal metrics.
• Use Vec(...) for labels, Gauge for current values, Counter.ObserveTotal() for source counters, and StateSet for fixed one-active-state values.
• Metric names MUST be stable and selected by charts.yaml.
• In charts.yaml, use version: v1, context_namespace, instances.by_labels, instances.optional_by_labels, and label_promotion where their operator-facing behavior is needed.
• Charts SHOULD omit algorithm for normal type-driven behavior. At runtime, chartengine maps metrix counters to incremental dimensions and gauges or other kinds to absolute, including dynamically built charttpl.Chart values. Metric names and suffixes do not determine the algorithm.
• A chart MAY set algorithm to intentionally override runtime kind for every dimension in that chart. This is also REQUIRED when differently typed series are deliberately aggregated into the same rendered dimension; otherwise, contributors to one rendered dimension MUST have the same runtime kind. Chartengine does not diagnose violations at runtime, so real-path collector tests MUST enforce this authoring rule.
• Mixed counter and gauge dimensions MAY share one authored chart when they render as distinct dimensions; each omitted algorithm is resolved from that dimension's matched series kind.
• A live metric identity MUST keep a stable runtime kind while its dimension is materialized. A kind change does not redefine an existing Netdata dimension; its creation-time wire algorithm remains until expiry and recreation.
• Histogram bucket charts use range bucket values from metrix.ReadFlatten() and chartengine forces them to heatmap. Bucket dimensions are named by the bare le upper-bound value and ordered numerically with +Inf last. Do NOT add collector-local cumulative-bucket workaround metrics or a bucket-mode option for V2 charts.
• Put multipliers, divisors, hidden flags, and float formatting in the chart template, not ad hoc chart-emission code.
• When instance identity omits labels—either because instances.by_labels does not select them or an instances.optional_by_labels key is absent—multiple source series can map to one rendered dimension. The effective MUST match the metric meaning. Set it on the chart; it applies to every dimension. Absence means ; available reducers are , , , and unweighted ( forces floating-point emission). Use separate charts when metrics need different reducers. Metric kind is not enough to infer this policy: gauges may be additive stocks, states, timestamps, limits, or averages.

Compatibility Rules

• For V1-to-V2 migrations, start with src/go/plugin/go.d/docs/migrate-v1-to-v2.md.

Migration Hard Stops

• A collector using V1 chart Vars is blocked until framework support, an approved equivalent design, or explicit breaking-alert approval exists.

• collecttest.AssertChartCoverage is not chart-identity parity; it cannot prove old chart IDs, family, priority, lifecycle, labels, or alert variables.

• A finished migration MUST pass an import/runtime-path audit proving no V1 collection path or V1 map-to-metrix bridge remains reachable from normal execution.

• Temporary V1-to-V2 parity bridges MAY be used during development, but the finished collector MUST NOT keep a runtime V1 map-to-metrix bridge.

• For migrations, first create a compatibility manifest covering chart IDs, contexts, dimension IDs/names, labels, config keys, DynCfg schema keys, stock config, alerts, docs, and lifecycle behavior.

• Migrations MUST preserve existing public contracts unless the SOW records an explicit breaking decision.

• Migrations MUST keep old YAML/JSON field names. Add new config as opt-in when cardinality, cost, or user-visible identity could surprise existing users.

• Collector integration artifacts MUST follow .agents/skills/integrations-lifecycle/consistency.md; do not preserve a partial local artifact checklist in V2 collector work.

• MUST NOT log raw secrets, DSNs, bearer tokens, or URLs with embedded credentials.

Hot-Path Logging

• Collectors MUST NOT emit Warningf/Errorf every collection cycle for a recoverable partial failure. Use the built-in logger limiter: c.Limit("collector:stable-operation-key", 1, time.Hour).Warningf(...).
• Limiter keys MUST be stable and low-cardinality. Use operation names, not entity IDs, labels, URLs, raw errors, or user-controlled values.
• Once() is reset by JobV2.runOnce(), so it is useful inside one cycle only; it is not cross-cycle spam protection.
• Full collection failure SHOULD still return an error with context so the job retry path handles it. Limit only fail-soft warnings/errors where collection continues with partial or stale data.

Chart Label Identity

• Labels used by instances.by_labels, a present nonblank instances.optional_by_labels key, or a dimension name_from_label define chart or dimension identity. Changing one creates a new chart or dimension; collectors MUST NOT use identity churn merely to refresh metadata.
• Use instances.optional_by_labels only when a source conditionally exposes a bounded, sufficiently stable, operator-useful identity axis. Missing and blank values are omitted; present values create refined instances. Authors MUST assess value count and churn, and MUST NOT create a duplicate aggregate chart when NIDL/query aggregation already provides that view.
• Optional-label presence or value transitions create a new chart while the old chart follows normal lifecycle expiry. A template MUST choose lifecycle limits appropriate for the source's observed churn.
• A present optional identity contributes both its key and value to the chart-ID suffix (for example, pid="1234" becomes _pid_1234); missing or blank optional identities contribute nothing.
• label_promotion defines non-identity chart metadata. Chartengine reconciles its effective intersection across every routed contributor, including an empty source-label set, and emits a complete replacement only when it changes.
• Collectors MUST continue publishing numeric samples at their required cadence. A label-only replacement updates chart metadata; it is not a substitute for numeric sample-and-hold output.

Host Scopes

• Host scopes SHOULD be used only after a product decision says the data belongs on a generated vnode.
• ScopeKey and GUID MUST be deterministic.
• Collector-generated vnodes MUST set _vnode_type=<source>.
• Host-scope cardinality MUST be bounded and documented. Collectors SHOULD NOT create VM/disk/NIC/path/sensor scopes by default.
• Scope identity MUST use stable IDs. Human-readable names SHOULD be hostnames or promoted labels only.

Tests

At minimum, V2 work MUST include these tests, or the PR/SOW MUST justify why a specific item does not apply:

• config YAML/JSON serialization compatibility;
• Init, Check, Collect, and Cleanup lifecycle coverage;
• explicit metric-store cycle tests with BeginCycle, success commit, and abort on expected collection errors;
• chart-template schema/decode/validate/compile coverage;
• chart coverage assertions for fixtures expected to materialize all dimensions;
• host-scope tests when scopes/vnodes are used.

Pre-PR Check

• A finished V1-to-V2 migration MUST NOT keep a runtime map[string]int64 collection path or V1 map-to-metrix bridge.
• The PR description or design note MUST enumerate affected collector consistency artifacts and justify every artifact that did not need a matching change. SHOULD-level exceptions and escape hatches MUST be reviewer-visible.
• Existing public chart/metric/config identity MUST be preserved unless the SOW records an explicit breaking decision.
• New labels and scopes MUST be bounded and documented.
• Enrichment SHOULD be split from the V2 compatibility migration when possible.