| 1 | # Keep Network Flows on Monitor Anything |
| 2 | |
| 3 | **One-line summary:** `src/collectors/COLLECTORS.md` is the generated Learn "Monitor anything with Netdata" page; Network Flows entries appear there only when `integrations/gen_doc_collector_page.py` treats the top-level `flows` category as a section. |
| 4 | |
| 5 | ## What Updates The Page |
| 6 | |
| 7 | `src/collectors/COLLECTORS.md` is generated, not hand-authored. The local and CI command is: |
| 8 | |
| 9 | ```bash |
| 10 | python3 integrations/gen_integrations.py |
| 11 | python3 integrations/gen_doc_collector_page.py |
| 12 | ``` |
| 13 | |
| 14 | `gen_integrations.py` produces the runtime |
| 15 | `integrations/integrations.js` catalog. `gen_doc_collector_page.py` |
| 16 | then reads that catalog and atomically replaces |
| 17 | `src/collectors/COLLECTORS.md`. The file is committed because it is |
| 18 | the source document that Learn ingests for the "Monitor anything with |
| 19 | Netdata" page. |
| 20 | |
| 21 | The CI workflow that checks documentation PRs also runs this path before Learn ingest: |
| 22 | |
| 23 | - `.github/workflows/check-markdown.yml` runs `gen_integrations.py`, `gen_docs_integrations.py`, `gen_doc_collector_page.py`, and `gen_doc_secrets_page.py` before `learn/ingest/ingest.py`. |
| 24 | - `.github/workflows/generate-integrations.yml` runs the same generator family after metadata changes land on `master` and opens a regeneration PR. |
| 25 | |
| 26 | ## Why Flows Need Explicit Handling |
| 27 | |
| 28 | Most Monitor Anything sections are children of `data-collection` in `integrations/categories.yaml`. Network Flows is different: |
| 29 | |
| 30 | - `integrations/categories.yaml` defines top-level `flows` with children `flows.sources` and `flows.enrichment-methods`. |
| 31 | - `src/crates/netflow-plugin/metadata.yaml` uses those categories for NetFlow / IPFIX / sFlow and flow enrichment entries. |
| 32 | - `integrations/gen_doc_collector_page.py` therefore must treat top-level `flows` as a section, otherwise those entries are not grouped as `Network Flows` on Monitor Anything. |
| 33 | |
| 34 | ## Validation |
| 35 | |
| 36 | After changing flow metadata or category handling, run: |
| 37 | |
| 38 | ```bash |
| 39 | python3 integrations/gen_integrations.py |
| 40 | python3 integrations/gen_docs_integrations.py |
| 41 | python3 integrations/gen_doc_collector_page.py |
| 42 | rg -n '^### Network Flows|\\[NetFlow\\]|\\[Static Metadata\\]|\\[Decapsulation\\]' src/collectors/COLLECTORS.md |
| 43 | ``` |
| 44 | |
| 45 | Expected result: `src/collectors/COLLECTORS.md` contains a `### Network Flows` section listing NetFlow, IPFIX, sFlow, and the enrichment integrations. |
| 46 | |
| 47 | ## How I Figured This Out |
| 48 | |
| 49 | Read `integrations/categories.yaml`, `src/crates/netflow-plugin/metadata.yaml`, `integrations/gen_doc_collector_page.py`, `src/collectors/COLLECTORS.md`, `.github/workflows/check-markdown.yml`, and `.github/workflows/generate-integrations.yml`; regenerated `COLLECTORS.md` and checked for the `Network Flows` section. |