AGENTS.md

1# Go Area Instructions
2 
3This file routes Go-specific work under `src/go/`. Repository-wide rules in
4the repo-root `AGENTS.md` still apply. More specific `AGENTS.md` files under
5subdirectories override this file for that subtree. Paths below are
6repo-relative unless stated otherwise.
7 
8## Sensitive Data
9 
10The repo-root `AGENTS.md` sensitive-data policy applies in full to all durable
11Go artifacts, including code comments, docs, specs, skills, and SOWs.
12 
13## Mandatory Development Principles
14 
15The repo-root clean-end-state and scope-discipline principles are mandatory and
16apply in full. For Go work, enforce them explicitly when changing collectors,
17framework code, runtime behavior, `metrix`, chart templates, Functions,
18topology, tests, specs, or skills.
19 
20- You MUST prefer the clean framework or collector shape over preserving a
21  smaller diff.
22- You MUST re-check scope after each coherent batch. If a separate framework fix,
23  collector cleanup, or docs rewrite becomes necessary, split it into its own
24  step or submit it independently before continuing.
25- You SHOULD use RFC-style requirement language (`MUST`, `SHOULD`, `MAY`) in
26  Go-area specs, skills, and instructions when documenting enforceable rules.
27 
28## Task Routing
29 
30| Work area | Start here | Notes |
31|---|---|---|
32| New go.d collector | `src/go/plugin/go.d/docs/how-to-write-a-collector.md` | New go.d collectors use framework V2. |
33| Migrating go.d V1 collector to V2 | `src/go/plugin/go.d/docs/migrate-v1-to-v2.md` | Preserve public contracts unless a breaking change is explicitly approved. |
34| go.d V2 implementation details | `.agents/skills/project-writing-go-modules-framework-v2/SKILL.md`, `src/go/pkg/metrix/README.md`, `src/go/plugin/framework/charttpl/README.md`, `src/go/plugin/framework/chartengine/README.md` | Use the skill for maintainer style and the READMEs for framework API contracts. Editing `metrix` or framework packages is framework-gated work. |
35| go.d helper packages | `src/go/plugin/go.d/docs/helper-packages.md` | Check existing HTTP, config-option, matcher, logger, socket, command, SQL, ping, log-file, and cloud-auth helpers before adding custom plumbing. |
36| Collector design across plugins | `.agents/skills/project-writing-collectors/SKILL.md` | Use for NIDL, cardinality, obsoletion, missing data, logging, and config discipline. |
37| Integration metadata, taxonomy, generated docs | `.agents/skills/integrations-lifecycle/SKILL.md`, `.agents/skills/integrations-lifecycle/consistency.md` | Source artifacts and generated artifacts MUST stay synchronized. |
38| IBM.d work | `src/go/plugin/ibm.d/AGENTS.md` | IBM.d has a generator-driven workflow; go.d V2 layout rules MUST NOT be applied there. |
39| Function handlers | `src/go/plugin/framework/functions/README.md`, `src/go/tools/functions-validation/README.md` | Collector Functions SHOULD be isolated behind narrow dependencies. |
40| Topology payloads | `.agents/skills/project-create-topology/SKILL.md`, `.agents/skills/project-create-topology/topology-function-schema.md`, `src/go/pkg/topology/v1` | New topology producers MUST use the production `netdata.topology.v1` schema. |
41| Host scopes / vnodes | `.agents/skills/project-writing-go-modules-framework-v2/go-v2-host-scope.md`, `src/go/plugin/go.d/collector/azure_monitor/` | Use host scopes when one job emits metrics for resources that SHOULD appear as separate Netdata nodes. |
42| Matchers/selectors | `src/go/pkg/matcher/README.md` | Prefer existing matcher APIs over custom selector grammars. |
43| Core framework changes | `src/go/plugin/framework/docs/changing-framework-code.md` and `Core Framework Change Gate` below | The applicable approval tier MUST be satisfied before implementation. |
44 
45## New go.d Collector Rules
46 
47- New go.d collectors MUST implement `collectorapi.CollectorV2` from
48  `src/go/plugin/framework/collectorapi/collector.go` and register via
49  `CreateV2`. This includes writing metrics through `metrix.CollectorStore` and
50  providing `ChartTemplateYAML()`.
51- New go.d collector guidance MUST NOT teach or copy the V1
52  `Collect() map[string]int64` pattern for new
53  collectors.
54- Collector runtime, metric, chart, config, alert, taxonomy, and documentation
55  changes MUST follow the repository collector consistency policy. The detailed
56  checklist lives in `.agents/skills/integrations-lifecycle/consistency.md`.
57- Public config options SHOULD be added only when they represent a real
58  operator decision. Implementation tuning such as page sizes, scan windows,
59  retry limits, and cadence SHOULD use internal constants unless user control is
60  clearly justified.
61- New collectors MUST NOT inherit unsupported config knobs from adjacent
62  collectors or generic templates.
63- Collector-local globals, singletons, adapters, caches, or glue layers that
64  substitute for missing shared framework/helper capabilities are
65  framework-scope work and MUST follow
66  `src/go/plugin/framework/docs/changing-framework-code.md` before
67  implementation.
68- If the collector exposes Functions, put Function code in a dedicated
69  `<name>func/` package behind a narrow `Deps` interface declared in that
70  package. The Function package MUST NOT import the collector package or hold
71  `*Collector`.
72- If the collector emits topology, it MUST use `netdata.topology.v1`, the Go
73  producer model in `src/go/pkg/topology/v1`, and validate payloads against
74  `src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json`. New producers MUST NOT use
75  legacy topology payloads.
76- If one job emits metrics for multiple remote resources that SHOULD appear as
77  separate Netdata nodes, it MUST use V2 host scopes/vnodes.
78 
79## go.d V1-to-V2 Migration Rules
80 
81- V1-to-V2 migrations MUST start with
82  `src/go/plugin/go.d/docs/migrate-v1-to-v2.md`.
83- Migrations MUST preserve chart IDs, contexts, dimensions, config keys,
84  defaults, health lookups, metadata, taxonomy, stock config, and service
85  discovery behavior unless the user explicitly approves a breaking change.
86- Compatibility migration SHOULD be separate from enrichment such as new labels,
87  host scopes, topology, Functions, or config expansion.
88- Completed migrations MUST NOT keep a runtime V1-to-V2 bridge. Temporary V1
89  logic can be used during development for parity checks, but it MUST be
90  removed from the final migrated collector.
91 
92## Core Framework Change Gate
93 
94Changes to shared Go framework code (`metrix`, `chartengine`, `charttpl`, the job
95runtime, `collectorapi`) are high-blast-radius: this code runs in EVERY collector,
96most of it on the per-cycle hot path. Before changing these areas, read
97`src/go/plugin/framework/docs/changing-framework-code.md` — the canonical owner of
98the framework-change scope list, required design note, validation expectations, and
99artifact checks. Implementation MUST NOT begin until that guide's applicable
100approval tier is satisfied.
101 
102- Clean extension over glue: prefer a clean framework extension over
103  collector-local globals, singletons, adapters, or private-package coupling when
104  the problem is general.
105- Behavior preservation: when a framework change also touches shipped collectors,
106  preserve their observable behavior (chart IDs, contexts, dimensions, config keys,
107  defaults) and validate representative consumers, not only the framework package
108  (see "Validation For Go Changes").
109- metrix contract: `metrix` keeps one descriptor per metric NAME, resolved
110  atomically at commit and bounded — a name idle past `expireAfterSuccessCycles +
111  descriptorGraceCycles` is evicted, and re-registers cleanly afterward. A consumer
112  that caches per-name state across cycles MUST couple its lifetime to the optional
113  `metrix.DescriptorRetention` accessor. See `src/go/pkg/metrix/README.md`
114  ("Descriptor Lifecycle and Retention").
115 
116## Evidence Before Complexity
117 
118Readability and maintainability are the default for Go control-plane and
119framework code. Complexity needs evidence; a plausible future problem is not a
120requirement.
121 
122- Code MUST NOT introduce population, byte, concurrency, queue, retry, or
123  backpressure limits, nor add accounting, scheduling, pooling, caching, custom
124  data structures, or lifecycle machinery, unless the design follows from a
125  concrete correctness, liveness, protocol, compatibility, or security contract,
126  a documented scale requirement, or a measured production workload.
127- The justification MUST identify the input or producer, the failure being
128  prevented, the expected scale, and why simpler slices, maps, channels, or
129  direct ownership are insufficient. A round number, hypothetical abuse case,
130  or benchmark in isolation is not evidence of a product requirement.
131- Protocol- and security-derived bounds MUST remain tied to their source with a
132  concise rationale and boundary tests. Do not generalize one per-item bound
133  into an aggregate process policy without separate evidence.
134- When a limit has no valid requirement, remove the policy and its coupled
135  machinery. Raising it to an effectively unreachable value is not the clean
136  end state.
137- Do not add allocation- or latency-oriented complexity until the path is shown
138  to be hot by its production frequency, a profile, or representative benchmark.
139  Once a path is established as hot, follow "Hot-Path And Benchmark Discipline."
140 
141## Hot-Path And Benchmark Discipline
142 
143metrix commit/collect, per-sample/per-write, and per-cycle code are hot paths that
144run for every collector on every cycle.
145 
146- Before/after REQUIRED: a hot-path change MUST include before/after
147  `go test -bench` numbers (use `git stash` for the "before" baseline), not just
148  "tests pass".
149- Allocation count is the gate: assert allocs stay within the intended envelope
150  (e.g. a sparse commit stays ~O(touched), never O(retained)). `ns/op` is a
151  dev-machine trend indicator, NOT a CI gate — label it as such inline, and never
152  record a personal name in the file.
153- State the complexity envelope explicitly (e.g. "commit is O(live-series +
154  touched + distinct-names)") and prove the change did not introduce an
155  O(samples)/O(retained)/O(n^2) regression.
156- Keep bench comments in sync with the code they measure, in the same change, with
157  self-contained wording (no round/session references).
158 
159## Go Formatting
160 
161`gofmt` and `goimports` are the baseline. This repository additionally
162RECOMMENDS (not CI-enforced) a fuller formatting pipeline that keeps line
163wrapping tight and keyed struct literals readable:
164 
1651. `golines -m 120 -t 4 -w <paths>` — join over-wrapped signatures/calls and
166   split lines past ~120 columns. SKIP this step if `golines` is not installed
167   (`go install github.com/segmentio/golines@latest`).
1682. `go run ./tools/expandstructs <paths>` — put each keyed struct-literal field
169   on its own line. Formats source in-process with `go/format`.
1703. `goimports -w <paths>` — order imports.
171 
172Conventions this encodes:
173 
174- Keep a signature / call / return / composite literal on ONE line when it fits
175  within ~120 columns; wrap only when it does not.
176- Keyed struct literals of a named type go ONE field per line.
177 
178`gofmt`/`goimports` cannot express these two rules, so they are not CI-enforced;
179re-run the pipeline if code drifts. See `tools/expandstructs/README.md`.
180 
181## Validation For Go Changes
182 
183Run the narrowest command that actually exercises the change; do not claim
184full-project validation from a narrow one.
185 
186- Always: formatted per "Go Formatting" above (at minimum `gofmt` clean) and
187  `go vet ./<pkg>/` clean.
188- Unit: `go test -count=1 ./<pkg>/...` for every package you touched.
189- Concurrency: add `-race` for concurrency-sensitive packages (`metrix`, the job
190  runtime, `plugin/agent/jobmgr`).
191- Shared framework code: ALSO build and test representative consumers (a couple of
192  real collectors) plus `-race ./plugin/agent/jobmgr/`, so a framework change is
193  proven against real users, not just its own package.
194- Reproduce a reviewer-reported bug as a FAILING test first, then fix to green
195  (repo-wide working-style rule).
196- Prefer `testify/require` for test prerequisites and `testify/assert` for
197  comparisons when applicable. Use `t.Fatal` or `t.Fatalf` directly when it
198  represents genuine test control flow or has no clearer assertion equivalent.
199 
200## Go Review And Reachability
201 
202- Start review at the declared interface and the shipped production adapter.
203  Inspect implementation internals behind that boundary only when the contract
204  leaves relevant behavior unspecified or concrete evidence points across it.
205  Do not make a caller responsible for arbitrary private behavior of every
206  implementation.
207- Before deleting Go code as unused, check all relevant reference forms:
208  selector reads and writes, struct literals, constructor arguments, method
209  values, interface satisfaction, reflection, build-tagged and platform files,
210  generated code, and test-only injection. A call-site-only search is not proof
211  of unreachability.
212 
213## Batching And Review
214 
215- Changes SHOULD stay atomic. If a collector or framework task grows, split it
216  into coherent batches before review becomes difficult.
217- At every batch boundary, you MUST re-evaluate clean end state and scope. If
218  the branch now contains independent work, pause and submit that work
219  separately or defer it before continuing.
220- Changes MUST NOT mix framework changes, collector migrations, and
221  integration-doc regeneration unless they are required for one coherent
222  behavior change.
223- Multi-round review: checkpoint-commit each validated change before its review and
224  squash at PR time; if findings keep clustering in one subsystem (~2-3 rounds),
225  stop patching and fix the class (repo-wide review rules).
226- For Go test style, follow the repo-root `AGENTS.md` "Go test style" section.
227