Collectors Metadata YAML

Collector metadata.yaml: The Page The User Reads

metadata.yaml is the source of the integration page on Learn and of the catalog row that leads to it. Users open that page to decide whether to run the collector, what they will get, what it needs, and what it costs. Every field in it is product copy for an operator, not developer documentation. This skill owns what each field says and how it reads.

Ownership

• This skill: the content of every collector metadata.yaml field: what it answers, in what order, in what shape, for whom. Rules are cross-plugin. ibm.d metadata is generated by docgen and never edited: module.yaml holds the identity and the overview description, contexts.yaml the metric rows; every other field (method, permissions, default behavior, keywords, option rows, prerequisites, examples, troubleshooting) is a constant in docgen's metadata template (src/go/plugin/ibm.d/docgen/main.go, see integrations-lifecycle/ibm-d.md), so applying these rules there means changing the template. config.go feeds the schema and README, not the options table.
• .agents/skills/integrations-lifecycle/: mechanics. JSON schemas, generators, validation commands, artifacts and banners, the ibm.d generation chain, and the cross-type page meta-description derivation contract (description-authoring.md).
• .agents/skills/collectors-go-design/config-schema.md: the DynCfg form. Option wording shared between the form and the options table has one owner there (sections 7 and 8); this skill points to it.
• .agents/skills/collectors-go-design/operator-surface.md: which options exist and what an operator decides. Decided before this skill applies.

How The Page Is Rendered

Facts every rule below relies on (integrations/templates/overview/collector.md and siblings):

• The template owns the heading hierarchy (h1 title; h2 Overview, Setup, Troubleshooting, Alerts, Metrics, and Live Data when the collector has Functions; h3 to h6 inside them, down to one h5 per option depth block and one h6 per example). Field text is inserted under those headings as-is.
• Field text is Markdown rendered by Docusaurus on Learn. Paragraphs, lists, tables, inline code, fenced code, links, and ::: admonitions (note, tip, caution) pass through the generator untouched.
• Some empty fields are not empty on the page. auto_detection, limits, and performance_impact render a template placeholder sentence that asserts something about the collector (see overview.md). An empty field is a claim.
• The first sentence of metrics_description is the catalog row and the page meta description; its mechanics and length contract are in integrations-lifecycle/description-authoring.md.
• Generated pages under integrations/ and the README.md symlink are outputs. Fix the source; never edit them.

The Reading Model

• The reader is an operator scanning a page, deciding in this order: what is this, what do I get, what do I need, what does it cost, how do I set it up, what went wrong. Fields are ordered that way by the template; write each field for the question it sits under.
• Readers stop when they have enough. The first paragraph of every field MUST stand alone; detail follows in decreasing importance.
• Readers skip walls of text ("I ain't reading all that"). Long content is fine when it is structured: one idea per paragraph, lists for enumerations, tables for items that share attributes, an admonition for what must not be missed. Length is a symptom to check, not the rule; an unstructured 120-word paragraph fails, a 400-word field made of a table and three short paragraphs may pass.
• Operator voice. The page describes what the collector does as the operator sees it: connections, requests, commands, files, permissions, what it creates and deletes, what it never touches. Engine vocabulary (journal, state machine, reconciliation, plan compiler, snapshot) MUST NOT appear; define any unavoidable term at first use.

Routing By Field Family

Depth Boundary

Content that does not answer its field's question does not stay in the field. Route it:

• Another field on the page owns it (a permission belongs in additional_permissions, a knob in its option row's detailed_description, a failure in troubleshooting, a chart in its metric description).
• The collector's profile format documentation (profile-format.md) owns it, for profile-driven collectors.
• A docs/guides page owns it when it is an operator procedure spanning several products.
• It is developer content (internal stages, caches, bounds nobody configures, ownership resolution). It belongs in the collector's ARCHITECTURE.md or in code, is never linked from the page, and leaves the page.
• Nothing owns it: cut it.

Safety Of The Markdown

Field text travels through the generator into MDX. These break the Learn build or the page silently:

• Placeholders in angle brackets (<service-name>, <region>) parse as JSX. Put them in backticks, like every other code-shaped expression (option names, paths, values).
• Generics and any other angle-bracket syntax in prose (Vec<u32>, HashMap<K,V>) parse the same way. Backticks.
• A bare < before a digit (<100 ms) fails the build. Write "under 100 ms" (or < when the symbol must stay).
• Smart quotes from editors and an unbalanced backtick break code detection. Use ASCII quotes; balance backticks.
• Tables need a header separator row and the same number of cells on every row; an admonition needs its closing ::: on its own line.
• Learn's ingest escapes only bare {, <=, %<, <->, and <details><summary>. test_collector_metadata checks the rest here; anything it misses appears on the next Learn deploy preview, not in this repo's CI.

Review Checklist

Before committing a collector metadata.yaml (or an ibm.d module.yaml) change:

1. Regenerate and read the page: python3 integrations/gen_integrations.py, then python3 integrations/gen_docs_integrations.py -c <plugin>/<module> (for example go.d.plugin/cloudwatch), open the collector's file under integrations/, read it as the operator top to bottom once, then git restore the regenerated page. The first script writes only gitignored outputs (integrations.js, integrations.json); the second writes the page.
2. Every field answers its own question (the family file's contract), leads with what matters, and would survive the reader stopping after its first paragraph.
3. No field is over-scoped: no headings, at most two or three bold captions, at most one admonition, no glossary before the reader knows what the collector does.
4. Empty auto_detection, limits, or performance_impact only where the placeholder sentence is true. A collector covered by a service-discovery rule, or with a cardinality cap or a metered API, fills them.
5. No engine vocabulary; every term defined at first use; no developer links (ARCHITECTURE.md, source files).
6. Statements verified against the code, not against the previous prose: permissions, defaults, what is created or deleted, limits, addresses probed.
7. Markdown safety items above; then python3 -m unittest integrations.tests.test_collector_metadata (the mechanical checks of this skill) and the pipeline validation in integrations-lifecycle/description-authoring.md (gen_docs_integrations.py --check, test_descriptions).
8. Generated hunks under integrations/ are not part of the commit; the post-merge regeneration owns them.