| 1 | # query-netdata-agents -- How-tos index |
| 2 | |
| 3 | This directory holds **operational how-tos** for direct-agent |
| 4 | calls: short, focused recipes that combine the per-domain guides |
| 5 | into answers for specific questions. Each how-to documents the |
| 6 | question, the steps taken, the wrappers used, and the expected |
| 7 | output shape. |
| 8 | |
| 9 | ## The "if you analyze, you author a how-to" rule |
| 10 | |
| 11 | The how-tos catalog is meant to be **live**. Every time an AI |
| 12 | assistant (or human) is asked a question that: |
| 13 | |
| 14 | 1. The user expects a concrete answer to, AND |
| 15 | 2. Is not already documented in this index, AND |
| 16 | 3. Forces analysis (multiple wrapper calls, jq pipelines, or |
| 17 | cross-referencing more than one per-domain guide) |
| 18 | |
| 19 | the assistant MUST author a new how-to in this directory and add |
| 20 | it to the index BELOW before completing the task. |
| 21 | |
| 22 | This is mandatory. Skipping it means the next assistant repeats |
| 23 | the same analysis from scratch. |
| 24 | |
| 25 | ## How-to authoring template |
| 26 | |
| 27 | Filename: `<slug>.md`. Sections: Question, Inputs, Steps (each |
| 28 | calling one wrapper), Output, Notes / gotchas, Source guides. |
| 29 | |
| 30 | Every code example must use the token-safe wrappers from |
| 31 | `scripts/_lib.sh` (`agents_query_cloud`, `agents_query_agent`, |
| 32 | `agents_call_function`). No raw curl with `Authorization: Bearer |
| 33 | $TOKEN` or `X-Netdata-Auth: Bearer <uuid>` literals -- that |
| 34 | defeats the no-token-leak guarantee. |
| 35 | |
| 36 | ## Index |
| 37 | |
| 38 | (Populate as how-tos are authored. Stubs below mirror the canonical |
| 39 | skill-verification harness questions for `verify/questions.md`; replace each |
| 40 | `(stub -- not yet authored)` with a real link as soon as a how-to is written.) |
| 41 | |
| 42 | ### Identity / hardware / OS |
| 43 | |
| 44 | - `agent-info-summary.md` (stub -- not yet authored) |
| 45 | - `read-claim-id-direct.md` (stub -- not yet authored) |
| 46 | - `chart-labels-via-metrics-summary.md` (stub -- not yet authored) |
| 47 | |
| 48 | ### Streaming |
| 49 | |
| 50 | - `incoming-children-list.md` (stub -- not yet authored) |
| 51 | - `outgoing-parent-target.md` (stub -- not yet authored) |
| 52 | - `replication-progress-per-peer.md` (stub -- not yet authored) |
| 53 | |
| 54 | ### Collectors / jobs / vnodes (DynCfg) |
| 55 | |
| 56 | - `list-go.d-jobs-and-status.md` (stub -- not yet authored) |
| 57 | - `list-vnodes.md` (stub -- not yet authored) |
| 58 | - `read-job-config.md` (stub -- not yet authored) |
| 59 | - `add-go.d-job.md` (stub -- not yet authored) |
| 60 | |
| 61 | ### Functions |
| 62 | |
| 63 | - `discover-registered-functions.md` (stub -- not yet authored) |
| 64 | - `call-function-info.md` (stub -- not yet authored) |
| 65 | |
| 66 | ### Logs |
| 67 | |
| 68 | - `tail-namespace-direct.md` (stub -- not yet authored) |
| 69 | - `last-status-file-log-direct.md` (stub -- not yet authored) |
| 70 | - `histogram-by-priority.md` (stub -- not yet authored) |
| 71 | |
| 72 | ### Alerts |
| 73 | |
| 74 | - `currently-firing-alerts-direct.md` (stub -- not yet authored) |
| 75 | - `alert-config-direct.md` (stub -- not yet authored) |
| 76 | - `transitions-last-hour-direct.md` (stub -- not yet authored) |
| 77 | |
| 78 | ### Topology / flows |
| 79 | |
| 80 | - `topology-summary-direct.md` (stub -- not yet authored) |
| 81 | - `flows-top-talkers-direct.md` (stub -- not yet authored) |
| 82 | - [validate-direct-local-flow-function.md](./validate-direct-local-flow-function.md) -- prove a local Cloud-connected `flows:netflow` Function works through a Cloud-minted direct-agent bearer. |
| 83 | |
| 84 | ### Metrics |
| 85 | |
| 86 | - `current-cpu-direct.md` (stub -- not yet authored) |
| 87 | - `peak-memory-last-hour-direct.md` (stub -- not yet authored) |
| 88 | |
| 89 | ## Cross-skill how-tos |
| 90 | |
| 91 | When the answer needs both direct-agent and Cloud-side calls |
| 92 | (e.g. "discover the bearer-protected agent's claim_id from Cloud |
| 93 | first, then call it directly"), author the how-to under the |
| 94 | skill that owns the FIRST wrapper call and cross-link to the |
| 95 | other. |