| 1 | # Recipe: update an existing collector integration |
| 2 | |
| 3 | Use this when a collector's metrics, chart contexts, configuration, |
| 4 | alerts, or generated docs change. The goal is to keep runtime behavior, |
| 5 | metadata, taxonomy, docs, and CI validation in one coherent PR. |
| 6 | |
| 7 | ## 0. Read first |
| 8 | |
| 9 | - `../SKILL.md` -- integrations lifecycle overview. |
| 10 | - `../consistency.md` -- what the collector consistency rule requires |
| 11 | and what CI enforces. |
| 12 | - `../schema-reference.md` -- exact `metadata.yaml` and |
| 13 | `taxonomy.yaml` fields. |
| 14 | |
| 15 | ## 1. Identify what changed |
| 16 | |
| 17 | From the collector directory, list the changed surfaces: |
| 18 | |
| 19 | - runtime `.go` / script code; |
| 20 | - `metadata.yaml` metric contexts, units, dimensions, setup, alerts; |
| 21 | - `taxonomy.yaml` dashboard TOC placement; |
| 22 | - `config_schema.json`; |
| 23 | - stock `.conf`; |
| 24 | - `health.d/*.conf`; |
| 25 | - generated `integrations/<slug>.md` and `README.md` symlink. |
| 26 | |
| 27 | If chart contexts are added, removed, renamed, or moved between dynamic |
| 28 | and static emission, update `taxonomy.yaml` in the same PR. |
| 29 | |
| 30 | ## 2. Update `metadata.yaml` |
| 31 | |
| 32 | Keep `metrics.scopes[].metrics[].name` aligned with the collector's |
| 33 | actual emitted chart contexts. Keep units and descriptions aligned with |
| 34 | the code. If a collector emits runtime-only dynamic contexts, declare |
| 35 | the guardrail in metadata: |
| 36 | |
| 37 | ```yaml |
| 38 | metrics: |
| 39 | dynamic_context_prefixes: |
| 40 | - prefix: snmp. |
| 41 | reason: SNMP profiles emit device-specific contexts at runtime. |
| 42 | ``` |
| 43 | |
| 44 | Use `dynamic_collect_plugins` only when a stable context-name prefix is |
| 45 | not available. |
| 46 | |
| 47 | ## 3. Update `taxonomy.yaml` |
| 48 | |
| 49 | Check whether the existing taxonomy still owns every static context |
| 50 | exactly once: |
| 51 | |
| 52 | ```bash |
| 53 | python3 integrations/gen_taxonomy.py --check-only |
| 54 | ``` |
| 55 | |
| 56 | Rules of thumb: |
| 57 | |
| 58 | - plain strings in structural `items:` own contexts; |
| 59 | - `type: context` widgets reference contexts but do not own them; |
| 60 | - every literal widget reference must be owned elsewhere or carry an |
| 61 | explicit `unresolved` escape hatch; |
| 62 | - dynamic collectors use `type: selector` with declared |
| 63 | `context_prefix:` or `collect_plugin:`; |
| 64 | - pick section IDs from `integrations/taxonomy/sections.yaml`. |
| 65 | |
| 66 | For a modern go.d V2 ownership reference, compare against |
| 67 | `src/go/plugin/go.d/collector/cato_networks/taxonomy.yaml`. If the change needs |
| 68 | grid or table widget examples, compare against |
| 69 | `src/go/plugin/go.d/collector/mysql/taxonomy.yaml`. |
| 70 | |
| 71 | ## 4. Update the remaining collector artifacts |
| 72 | |
| 73 | Keep these synchronized when the corresponding behavior changes: |
| 74 | |
| 75 | - `config_schema.json` for dynamic configuration; |
| 76 | - stock `.conf` for user-visible defaults; |
| 77 | - `health.d/*.conf` and `metadata.yaml.modules[].alerts[]`; |
| 78 | - generated docs via the integrations pipeline. |
| 79 | |
| 80 | Do not hand-edit generated `integrations/<slug>.md` files. |
| 81 | |
| 82 | ## 5. Run local validation |
| 83 | |
| 84 | From the repo root: |
| 85 | |
| 86 | ```bash |
| 87 | python3 integrations/gen_integrations.py |
| 88 | python3 integrations/gen_taxonomy.py --check-only |
| 89 | python3 integrations/check_collector_taxonomy.py --pr-diff master...HEAD |
| 90 | python3 -m unittest integrations.tests.test_taxonomy |
| 91 | python3 integrations/gen_docs_integrations.py -c go.d.plugin/<module> |
| 92 | python3 integrations/gen_doc_collector_page.py |
| 93 | python3 integrations/gen_doc_secrets_page.py |
| 94 | # If service-discovery rules or sdext metadata changed: |
| 95 | python3 integrations/gen_doc_service_discovery_page.py |
| 96 | ``` |
| 97 | |
| 98 | Use the repo-local `.venv/bin/python` when one exists for the current |
| 99 | worktree. If your local base branch is not `master`, adjust the `--pr-diff` |
| 100 | range to the PR base. |
| 101 | |
| 102 | If service-discovery rules or `sdext` metadata changed, run |
| 103 | `python3 integrations/gen_doc_service_discovery_page.py` and commit |
| 104 | `src/collectors/SERVICE-DISCOVERY.md`; this is not handled by CI for you. |
| 105 | |
| 106 | ## 6. Before opening the PR |
| 107 | |
| 108 | Run: |
| 109 | |
| 110 | ```bash |
| 111 | git status --short |
| 112 | git status --porcelain | |
| 113 | rg '^(\?\?|!!| M|M |A |AM) integrations/(integrations\.(js|json)|taxonomy\.json)$' || true |
| 114 | ``` |
| 115 | |
| 116 | Commit source changes, generated docs, and taxonomy updates together. |
| 117 | Do not commit gitignored runtime artifacts such as |
| 118 | `integrations/integrations.js`, `integrations/integrations.json`, or |
| 119 | `integrations/taxonomy.json`. |
| 120 | |
| 121 | The generated-artifact status grep MUST return no output before the PR is |
| 122 | opened. If it reports one of those files, remove the local generated artifact |
| 123 | from the commit/worktree state rather than committing it. |