AGENTS.md

1# IBM.d Plugin Developer Guide
2 
3CRITICAL: Never write raw sensitive data to durable artifacts. This includes passwords, API keys, bearer tokens, SNMP communities, private keys, connection strings with embedded credentials, session cookies, community member names, customer names, customer identifiers, personal data, non-private IP addresses that can identify customers, private endpoints, account IDs, and proprietary incident details.
4 
5This guide is for developers contributing to the IBM.d plugin. For end-user documentation, see [README.md](./README.md).
6 
7## Architecture Overview
8 
9`ibm.d.plugin` is Netdata's CGO-enabled plugin for IBM workloads. It ships with collectors for DB2, IBM i (AS/400), IBM MQ, and WebSphere, all implemented with the **IBM.D framework** – a type-safe layer built on top of go.d designed to be AI-assistant friendly.
10 
11### Why a Dedicated Plugin?
12 
13- **Native libraries** – DB2 connectivity and several IBM APIs require IBM's C client libraries, so the plugin is compiled with `CGO_ENABLED=1`.
14- **Predictable code generation** – collectors describe their metrics in declarative YAML; code-gen keeps the runtime, schema, metadata, and docs in sync.
15- **Modular architecture** – reusable protocols (OpenMetrics, PMI XML, JMX bridge, MQ interfaces) make it easy to add new IBM collectors without duplicating plumbing.
16 
17## Repository Layout
18 
19| Path | Purpose |
20|------|---------|
21| `framework/` | IBM.D collector SDK: base collector, context helpers, generator tooling. See [`framework/README.md`](framework/README.md). |
22| `modules/` | All IBM collectors (AS400, DB2, MQ, WebSphere). Each module is self-contained and backed by the framework. |
23| `protocols/` | Reusable protocol clients (e.g. PMI XML parser, OpenMetrics client, JMX helper bridge, MQ PCF client). |
24| `pkg/` | Shared CGO shims (DB2 ODBC bridge, ODBC helpers) used by multiple protocols/modules. |
25| `docgen/` | Tooling to generate docs/config metadata straight from module sources. |
26| `metricgen/` | Experimental helper for generating boilerplate metric exports. |
27 
28## Auto-Generated Files
29 
30The IBM.D plugin uses code generation to keep contexts, documentation, and metadata in sync. Understanding which files are generated vs. editable is crucial for development.
31 
32### Generated Files (DO NOT EDIT)
33 
34Each module generates these files automatically:
35 
36| File | Generator | Source | Purpose |
37|------|-----------|--------|---------|
38| `zz_generated_contexts.go` | `metricgen` | `contexts.yaml` | Type-safe Go structs for metric contexts |
39| `README.md` | `docgen` | `contexts.yaml` + `config.go` + `module.yaml` | Module documentation |
40| `metadata.yaml` | `docgen` | `contexts.yaml` + `config.go` + `module.yaml` | Netdata integrations metadata |
41 
42**⚠️ Warning:** Direct edits to these files will be overwritten on the next `go generate` run.
43 
44### Source Files (EDITABLE)
45 
46| File | Purpose |
47|------|---------|
48| `contexts/contexts.yaml` | **Source of truth** for all metrics, charts, dimensions, families, priorities |
49| `config.go` | Collector configuration structure (exported to JSON schema by docgen) |
50| `module.yaml` | Module metadata (name, description, categories) |
51| All other `.go` files | Module implementation code |
52 
53### Regenerating Code
54 
55#### Regenerate a Single Module
56 
57From the module directory:
58```bash
59cd modules/as400
60go generate ./...
61```
62 
63This runs both generators:
641. **metricgen** (via `contexts/doc.go`) → regenerates `zz_generated_contexts.go`
652. **docgen** (via `generate.go`) → regenerates `README.md` and `metadata.yaml`
66 
67#### Regenerate All Modules
68 
69From the plugin root:
70```bash
71cd src/go/plugin/ibm.d
72go generate ./modules/...
73```
74 
75#### After Regeneration
76 
77Always run `gofmt` on generated Go code:
78```bash
79gofmt -w modules/*/contexts/zz_generated_contexts.go
80```
81 
82### When to Regenerate
83 
84Regenerate after modifying:
85- ✅ `contexts/contexts.yaml` (metrics definitions)
86- ✅ `config.go` (configuration structure)
87- ✅ `module.yaml` (module metadata)
88- ❌ Implementation `.go` files (no regeneration needed)
89 
90### Verifying Generated Code
91 
92After regeneration, verify the module works:
93```bash
94sudo script -c '/usr/libexec/netdata/plugins.d/ibm.d.plugin -d -m MODULE --dump=3s --dump-summary 2>&1' /dev/null
95```
96 
97## Building the Plugin
98 
99The plugin is built automatically by Netdata's CMake tree when `ENABLE_PLUGIN_IBM=On` and the IBM CLI driver is available:
100 
101```bash
102mkdir build-ibm && cd build-ibm
103cmake -DENABLE_PLUGIN_IBM=On ..
104make ibm-plugin
105```
106 
107The build target downloads the driver if it is not already present; see the packaging scripts for distro-specific logic. The resulting binary is placed under `build-ibm/ibm.d.plugin` and must remain in `usr/libexec/netdata/plugins.d/` for Netdata to load it.
108 
109## Module Development Workflow
110 
1111. Update `contexts/contexts.yaml` and `config.go` (see [Source Files](#source-files-editable)).
1122. Run `go generate ./...` in the module directory (see [Regenerating Code](#regenerating-code)).
1133. Run `gofmt -w contexts/zz_generated_contexts.go` to format generated code.
1144. Validate with `script -c 'sudo /usr/libexec/netdata/plugins.d/ibm.d.plugin -d -m MODULE --dump=3s --dump-summary 2>&1' /dev/null`.
1155. Commit **both** source files and generated files together.
116 
117## Testing & Debugging
118 
119### Command-line dump mode
120Works exactly like go.d:
121```bash
122script -c 'sudo /usr/libexec/netdata/plugins.d/ibm.d.plugin -d -m MODULE --dump=2s --dump-summary 2>&1' /dev/null
123```
124 
125### Structured fixture dumps
126Generate JSON/SQL artifacts for automated tests:
127```bash
128ibm.d.plugin --module MODULE --dump-data ./testdata/MODULE
129```
130The flag implicitly enables dump mode and exits once every job has produced at least one collection.
131 
132## Contributing Guidelines
133 
1341. Review [`framework/README.md`](framework/README.md) for IBM.D framework details.
1352. Follow the Go-area rules in [`../../AGENTS.md`](../../AGENTS.md).
1363. **Never edit auto-generated files** – see [Auto-Generated Files](#auto-generated-files) section.
1374. Always regenerate code after modifying `contexts.yaml`, `config.go`, or `module.yaml`.
1385. Run `gofmt` on generated Go files before committing.
1396. Commit **both** source and generated files together to keep them in sync.
1407. Each module directory (`modules/<name>/`) contains its own README with module-specific notes.
141 
142## Runtime Internals
143 
144- The plugin reads `/etc/netdata/ibm.d.conf` for global settings and discovers per-collector jobs under `/etc/netdata/ibm.d/*.conf`.
145- Each module provides safe stock health alarms in `src/health/health.d/`.
146- The plugin supports dynamic configuration through the Netdata Agent.
147 
148For questions or suggestions, open a GitHub issue or reach out on Netdata's community channels.
149