| 1 | # Go Area Instructions |
| 2 | |
| 3 | This file routes Go-specific work under `src/go/`. Repository-wide rules in |
| 4 | the repo-root `AGENTS.md` still apply. More specific `AGENTS.md` files under |
| 5 | subdirectories override this file for that subtree. Paths below are |
| 6 | repo-relative unless stated otherwise. |
| 7 | |
| 8 | ## Sensitive Data |
| 9 | |
| 10 | The repo-root `AGENTS.md` sensitive-data policy applies in full to all durable |
| 11 | Go artifacts, including code comments, docs, specs, skills, and SOWs. |
| 12 | |
| 13 | ## Mandatory Development Principles |
| 14 | |
| 15 | The repo-root clean-end-state and scope-discipline principles are mandatory and |
| 16 | apply in full. For Go work, enforce them explicitly when changing collectors, |
| 17 | framework code, runtime behavior, `metrix`, chart templates, Functions, |
| 18 | topology, 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/sow/specs/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/sow/specs/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 | |
| 94 | Changes to shared Go framework code are high-blast-radius work. Before changing |
| 95 | these areas, read `src/go/plugin/framework/docs/changing-framework-code.md`. |
| 96 | That guide is the canonical owner of the framework-change scope list, required |
| 97 | design note, validation expectations, and artifact checks. |
| 98 | |
| 99 | Framework-change implementation MUST NOT begin until the applicable approval |
| 100 | tier in that guide is satisfied. You SHOULD prefer a clean framework extension |
| 101 | over collector-local glue, global variables, or private package coupling when |
| 102 | the problem is general. |
| 103 | |
| 104 | ## Batching And Review |
| 105 | |
| 106 | - Changes SHOULD stay atomic. If a collector or framework task grows, split it |
| 107 | into coherent batches before review becomes difficult. |
| 108 | - At every batch boundary, you MUST re-evaluate clean end state and scope. If |
| 109 | the branch now contains independent work, pause and submit that work |
| 110 | separately or defer it before continuing. |
| 111 | - Changes MUST NOT mix framework changes, collector migrations, and |
| 112 | integration-doc regeneration unless they are required for one coherent |
| 113 | behavior change. |
| 114 | - For Go test style, follow the repo-root `AGENTS.md` "Go test style" section. |