| 1 | # query-netdata-cloud -- How-tos index |
| 2 | |
| 3 | This directory holds **operational how-tos**: short, focused |
| 4 | recipes that combine the per-domain guides into answers for |
| 5 | specific questions. Each how-to documents the question, the steps |
| 6 | taken, the wrappers used, and the expected output shape. |
| 7 | |
| 8 | ## The "if you analyze, you author a how-to" rule |
| 9 | |
| 10 | The how-tos catalog is meant to be **live**. Every time an AI |
| 11 | assistant (or human) is asked a question that: |
| 12 | |
| 13 | 1. The user expects a concrete answer to, AND |
| 14 | 2. Is not already documented in this index, AND |
| 15 | 3. Forces analysis (multiple wrapper calls, jq pipelines, or |
| 16 | cross-referencing more than one per-domain guide) |
| 17 | |
| 18 | the assistant MUST author a new how-to in this directory and add |
| 19 | it to the index BELOW before completing the task. |
| 20 | |
| 21 | This is mandatory. Skipping it means the next assistant repeats |
| 22 | the same analysis from scratch. |
| 23 | |
| 24 | ## How-to authoring template |
| 25 | |
| 26 | Filename: `<slug>.md` (e.g. `find-node-id-by-hostname.md`). |
| 27 | |
| 28 | Sections: |
| 29 | |
| 30 | 1. **Question** -- the user-visible question, verbatim or |
| 31 | paraphrased. |
| 32 | 2. **Inputs** -- what the user must supply (space, hostname, |
| 33 | time range, etc.). |
| 34 | 3. **Steps** -- numbered, each calling exactly one wrapper from |
| 35 | `query-netdata-agents/scripts/_lib.sh`. |
| 36 | 4. **Output** -- what the assistant returns to the user. |
| 37 | 5. **Notes / gotchas** -- edge cases, follow-ups, related |
| 38 | how-tos. |
| 39 | 6. **Source guides** -- cross-links to the per-domain guides |
| 40 | used. |
| 41 | |
| 42 | Every code example must use the token-safe wrappers |
| 43 | (`agents_query_cloud`, `agents_query_agent`, |
| 44 | `agents_call_function`). No raw curl with `-H "Authorization: |
| 45 | Bearer $TOKEN"` -- that defeats the no-token-leak guarantee. |
| 46 | |
| 47 | ## Index |
| 48 | |
| 49 | (Populate as how-tos are authored. Stubs below mirror the canonical |
| 50 | skill-verification harness questions for `verify/questions.md`; replace each |
| 51 | `(stub -- not yet authored)` with a real link as soon as a how-to is written.) |
| 52 | |
| 53 | ### Identity / hardware / OS |
| 54 | |
| 55 | - `find-node-id-by-hostname.md` (stub -- not yet authored) |
| 56 | - `find-node-hardware-specs.md` (stub -- not yet authored) |
| 57 | - `find-node-os.md` (stub -- not yet authored) |
| 58 | |
| 59 | ### Streaming / parents / vnodes |
| 60 | |
| 61 | - `is-node-a-parent-and-children.md` (stub -- not yet authored) |
| 62 | - `is-node-a-child-and-parent-target.md` (stub -- not yet authored) |
| 63 | - `list-vnodes-on-node.md` (stub -- not yet authored) |
| 64 | |
| 65 | ### Collectors / jobs |
| 66 | |
| 67 | - `find-failed-collection-jobs.md` (stub -- not yet authored) |
| 68 | - `is-collector-monitoring-X-and-frequency.md` (stub -- not yet authored) |
| 69 | |
| 70 | ### Top processes |
| 71 | |
| 72 | - `pid-with-biggest-memory-and-app-group.md` (stub -- not yet authored) |
| 73 | |
| 74 | ### Alerts |
| 75 | |
| 76 | - `currently-firing-alerts-in-room.md` (stub -- not yet authored) |
| 77 | - `alert-config-by-cfg-hash.md` (stub -- not yet authored) |
| 78 | - `silenced-alerts.md` (stub -- not yet authored) |
| 79 | |
| 80 | ### Logs / status file |
| 81 | |
| 82 | - `last-netdata-status-file-log.md` (stub -- not yet authored) |
| 83 | - `recent-error-logs-in-namespace.md` (stub -- not yet authored) |
| 84 | |
| 85 | ### Topology / flows |
| 86 | |
| 87 | - `local-l2-topology-summary.md` (stub -- not yet authored) |
| 88 | - [`validate-local-netflow-function.md`](./validate-local-netflow-function.md) |
| 89 | - `top-flow-talkers-last-hour.md` (stub -- not yet authored) |
| 90 | |
| 91 | ### Members / rooms / feed |
| 92 | |
| 93 | - `members-by-role-in-space.md` (stub -- not yet authored) |
| 94 | - `rooms-with-most-nodes.md` (stub -- not yet authored) |
| 95 | - `node-state-changes-last-hour.md` (stub -- not yet authored) |
| 96 | |
| 97 | ## Cross-skill how-tos |
| 98 | |
| 99 | When the answer needs both Cloud-side and direct-agent-side calls |
| 100 | (e.g. "find the parent of a stale node, then read its |
| 101 | streaming-state directly"), author the how-to under the skill |
| 102 | that owns the FIRST wrapper call and cross-link to the other. |