| 1 | # IBM.d Plugin Developer Guide |
| 2 | |
| 3 | CRITICAL: 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 | |
| 5 | This 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 | |
| 30 | The 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 | |
| 34 | Each 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 | |
| 57 | From the module directory: |
| 58 | ```bash |
| 59 | cd modules/as400 |
| 60 | go generate ./... |
| 61 | ``` |
| 62 | |
| 63 | This runs both generators: |
| 64 | 1. **metricgen** (via `contexts/doc.go`) → regenerates `zz_generated_contexts.go` |
| 65 | 2. **docgen** (via `generate.go`) → regenerates `README.md` and `metadata.yaml` |
| 66 | |
| 67 | #### Regenerate All Modules |
| 68 | |
| 69 | From the plugin root: |
| 70 | ```bash |
| 71 | cd src/go/plugin/ibm.d |
| 72 | go generate ./modules/... |
| 73 | ``` |
| 74 | |
| 75 | #### After Regeneration |
| 76 | |
| 77 | Always run `gofmt` on generated Go code: |
| 78 | ```bash |
| 79 | gofmt -w modules/*/contexts/zz_generated_contexts.go |
| 80 | ``` |
| 81 | |
| 82 | ### When to Regenerate |
| 83 | |
| 84 | Regenerate 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 | |
| 92 | After regeneration, verify the module works: |
| 93 | ```bash |
| 94 | sudo 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 | |
| 99 | The plugin is built automatically by Netdata's CMake tree when `ENABLE_PLUGIN_IBM=On` and the IBM CLI driver is available: |
| 100 | |
| 101 | ```bash |
| 102 | mkdir build-ibm && cd build-ibm |
| 103 | cmake -DENABLE_PLUGIN_IBM=On .. |
| 104 | make ibm-plugin |
| 105 | ``` |
| 106 | |
| 107 | The 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 | |
| 111 | 1. Update `contexts/contexts.yaml` and `config.go` (see [Source Files](#source-files-editable)). |
| 112 | 2. Run `go generate ./...` in the module directory (see [Regenerating Code](#regenerating-code)). |
| 113 | 3. Run `gofmt -w contexts/zz_generated_contexts.go` to format generated code. |
| 114 | 4. Validate with `script -c 'sudo /usr/libexec/netdata/plugins.d/ibm.d.plugin -d -m MODULE --dump=3s --dump-summary 2>&1' /dev/null`. |
| 115 | 5. Commit **both** source files and generated files together. |
| 116 | |
| 117 | ## Testing & Debugging |
| 118 | |
| 119 | ### Command-line dump mode |
| 120 | Works exactly like go.d: |
| 121 | ```bash |
| 122 | script -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 |
| 126 | Generate JSON/SQL artifacts for automated tests: |
| 127 | ```bash |
| 128 | ibm.d.plugin --module MODULE --dump-data ./testdata/MODULE |
| 129 | ``` |
| 130 | The flag implicitly enables dump mode and exits once every job has produced at least one collection. |
| 131 | |
| 132 | ## Contributing Guidelines |
| 133 | |
| 134 | 1. Review [`framework/README.md`](framework/README.md) for IBM.D framework details. |
| 135 | 2. Follow the Go-area rules in [`../../AGENTS.md`](../../AGENTS.md). |
| 136 | 3. **Never edit auto-generated files** – see [Auto-Generated Files](#auto-generated-files) section. |
| 137 | 4. Always regenerate code after modifying `contexts.yaml`, `config.go`, or `module.yaml`. |
| 138 | 5. Run `gofmt` on generated Go files before committing. |
| 139 | 6. Commit **both** source and generated files together to keep them in sync. |
| 140 | 7. 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 | |
| 148 | For questions or suggestions, open a GitHub issue or reach out on Netdata's community channels. |