Recipe: update an existing collector integration

Use this when a collector's metrics, chart contexts, configuration, alerts, or generated docs change. The goal is to keep runtime behavior, metadata, taxonomy, source documentation, and CI validation coherent. Generated integration pages may ship in the source PR or through the automatic post-merge regeneration PR.

0. Read first

• ../SKILL.md -- integrations lifecycle overview.
• ../consistency.md -- what the collector consistency rule requires and what CI enforces.
• ../schema-reference.md -- exact metadata.yaml and taxonomy.yaml fields.

1. Identify what changed

From the collector directory, list the changed surfaces:

• runtime .go / script code;
• metadata.yaml metric contexts, units, dimensions, setup, alerts;
• taxonomy.yaml dashboard TOC placement;
• config_schema.json;
• stock .conf;
• health.d/*.conf;
• generated integrations/<slug>.md and README.md symlink.

If chart contexts are added, removed, renamed, or moved between dynamic and static emission, update taxonomy.yaml in the same PR.

2. Update metadata.yaml

Keep metrics.scopes[].metrics[].name aligned with the collector's actual emitted chart contexts. Keep units and descriptions aligned with the code. If a collector emits runtime-only dynamic contexts, declare the guardrail in metadata:

metrics:
  dynamic_context_prefixes:
    - prefix: snmp.
      reason: SNMP profiles emit device-specific contexts at runtime.

Use dynamic_collect_plugins only when a stable context-name prefix is not available.

3. Update taxonomy.yaml

Check whether the existing taxonomy still owns every static context exactly once:

python3 integrations/gen_taxonomy.py --check-only

Rules of thumb:

• plain strings in structural items: own contexts;
• type: context widgets reference contexts but do not own them;
• every literal widget reference must be owned elsewhere or carry an explicit unresolved escape hatch;
• dynamic collectors use type: selector with declared context_prefix: or collect_plugin:;
• pick section IDs from integrations/taxonomy/sections.yaml.

For a modern go.d V2 ownership reference, compare against src/go/plugin/go.d/collector/cato_networks/taxonomy.yaml. If the change needs grid or table widget examples, compare against src/go/plugin/go.d/collector/mysql/taxonomy.yaml.

4. Update the remaining collector artifacts

Keep these synchronized when the corresponding behavior changes:

• config_schema.json for dynamic configuration;
• stock .conf for user-visible defaults;
• health.d/*.conf and metadata.yaml.modules[].alerts[];
• generated docs through the explicitly selected same-PR or post-merge route.

Do not hand-edit generated integrations/<slug>.md files.

5. Run local validation

From the repo root:

python3 integrations/gen_integrations.py
python3 integrations/gen_taxonomy.py --check-only
python3 integrations/check_collector_taxonomy.py --pr-diff master...HEAD
python3 -m unittest integrations.tests.test_taxonomy
# When committing generated docs in this PR:
python3 integrations/gen_docs_integrations.py -c go.d.plugin/<module>
python3 integrations/gen_doc_collector_page.py
python3 integrations/gen_doc_secrets_page.py
# If service-discovery rules or sdext metadata changed:
python3 integrations/gen_doc_service_discovery_page.py

Skip the three generated-doc commands when the source PR explicitly selects the automatic post-merge regeneration route. check-markdown.yml and generate-integrations.yml run them in CI.

Use the repo-local .venv/bin/python when one exists for the current worktree. If your local base branch is not master, adjust the --pr-diff range to the PR base.

If service-discovery rules or sdext metadata changed, run python3 integrations/gen_doc_service_discovery_page.py and commit src/collectors/SERVICE-DISCOVERY.md; this is not handled by CI for you.

6. Before opening the PR

Run:

git status --short
git status --porcelain |
  rg '^(\?\?|!!| M|M |A |AM) integrations/(integrations\.(js|json)|taxonomy\.json)$' || true

Commit source and taxonomy changes together. Either commit regenerated docs in the same PR or state that generate-integrations.yml will open the post-merge regeneration PR; do not leave the delivery route implicit. Do not commit gitignored runtime artifacts such as integrations/integrations.js, integrations/integrations.json, or integrations/taxonomy.json.

The generated-artifact status grep MUST return no output before the PR is opened. If it reports one of those files, remove the local generated artifact from the commit/worktree state rather than committing it.