| 1 | # query-netdata-agents -- verification questions (seed list) |
| 2 | |
| 3 | This file is the **seed input** consumed by the verification |
| 4 | harness introduced by PR #22423 for direct-agent queries. The harness spawns |
| 5 | a Sonnet-class assistant with `../SKILL.md` + `../how-tos/INDEX.md` |
| 6 | + the canonical reference docs as context, asks each question |
| 7 | below, captures the transcript, and grades it against the |
| 8 | verification harness rubric. |
| 9 | |
| 10 | When the assistant cannot answer or has to perform analysis not |
| 11 | already documented under `../how-tos/`, the assistant must author |
| 12 | a new how-to and add it to the index before completing. |
| 13 | |
| 14 | ## Anchor: target nodes |
| 15 | |
| 16 | Two targets: |
| 17 | |
| 18 | - **Local desktop**: the agent reachable at `http://localhost:19999` |
| 19 | (typically the user's `costa-desktop`). |
| 20 | - **Remote agent-events node**: the agent reachable at |
| 21 | `http://${AGENT_EVENTS_HOSTNAME}:19999` with node UUID |
| 22 | `${AGENT_EVENTS_NODE_ID}` and machine_guid |
| 23 | `${AGENT_EVENTS_MACHINE_GUID}`. |
| 24 | |
| 25 | Both use the bearer-mint flow. The harness verifies the wrapper |
| 26 | mints / caches / refreshes correctly for both. |
| 27 | |
| 28 | ## Identity (direct) |
| 29 | |
| 30 | - **Q01** -- Read the agent's `/api/v3/info` directly. What is the |
| 31 | node UUID, machine_guid, claim_id, agent version, and |
| 32 | hostname? |
| 33 | - **Q02** -- What is the install prefix detected by |
| 34 | `agents_netdata_prefix` on the local desktop? |
| 35 | |
| 36 | ## Streaming (agent-only -- Cloud has no equivalent) |
| 37 | |
| 38 | - **Q03** -- Run the `netdata-streaming` Function on the agent. |
| 39 | Is it acting as a parent (any incoming-direction rows)? If so, |
| 40 | how many children, and what's the replication progress per |
| 41 | child? |
| 42 | - **Q04** -- Is the agent acting as a child (any outgoing- |
| 43 | direction row)? If so, what is the upstream parent host / |
| 44 | endpoint? |
| 45 | |
| 46 | ## DynCfg (direct) |
| 47 | |
| 48 | - **Q05** -- Use `GET /api/v3/config?action=tree&path=/` to list |
| 49 | every configuration object on the agent. Group them by the |
| 50 | top-level path (e.g. `/collectors/go.d/Jobs`, |
| 51 | `/health/alerts/prototypes`, etc.) and show the count per |
| 52 | group. |
| 53 | - **Q06** -- For one collector job (your choice), get its JSON |
| 54 | Schema via `action=schema` and its current value via |
| 55 | `action=get`. |
| 56 | - **Q07** -- Are there any vnodes? Use |
| 57 | `path=/collectors/go.d/Vnodes` (and `ibm.d/Vnodes`). |
| 58 | |
| 59 | ## Functions (direct) |
| 60 | |
| 61 | - **Q08** -- Discover every Function registered on the agent |
| 62 | (use the listing endpoint or info-walk pattern). Group by |
| 63 | family (table snapshot vs log explorer vs topology vs flows |
| 64 | vs other). |
| 65 | - **Q09** -- For each of `processes`, `network-connections`, |
| 66 | `mount-points`, call with `{"info":true}` and report the |
| 67 | parameter set. |
| 68 | |
| 69 | ## Logs (direct) |
| 70 | |
| 71 | - **Q10** -- Tail the last 10 entries of the system journal on |
| 72 | the local desktop. |
| 73 | - **Q11** -- Find the last error-priority entry written to the |
| 74 | systemd journal in the last hour. |
| 75 | |
| 76 | ## Alerts (direct) |
| 77 | |
| 78 | - **Q12** -- Use `POST /api/v3/alerts` with |
| 79 | `{"options":["instances"]}` to list currently-firing alerts |
| 80 | on the agent. Pick one with status CRITICAL or WARNING and |
| 81 | fetch its full config via `GET /api/v3/alert_config?config=...`. |
| 82 | - **Q13** -- Use `POST /api/v3/alert_transitions` to find every |
| 83 | CLEAR -> CRITICAL transition in the last hour. |
| 84 | |
| 85 | ## Metrics (direct) |
| 86 | |
| 87 | - **Q14** -- Use `POST /api/v3/data` to find the maximum |
| 88 | `system.cpu` user dimension over the last hour, points=60. |
| 89 | - **Q15** -- Use `GET /api/v3/contexts` to list every metric |
| 90 | context the agent currently collects, sorted alphabetically. |
| 91 | |
| 92 | ## Topology (direct) |
| 93 | |
| 94 | - **Q16** -- Run `topology:snmp` against the local desktop with |
| 95 | `{"info":true}` and report `accepted_params`. (If `topology: |
| 96 | snmp` is not registered on the local desktop because no SNMP |
| 97 | collector is configured, say so explicitly.) |
| 98 | |
| 99 | ## Flows (direct) |
| 100 | |
| 101 | - **Q17** -- Run `flows:netflow` against the local desktop with |
| 102 | `{"info":true}` and report `accepted_params`. (If |
| 103 | `flows:netflow` is not registered, say so explicitly.) |
| 104 | |
| 105 | ## Token-safety self-test |
| 106 | |
| 107 | - **Q18** -- Run `agents_selftest_no_token_leak`. It must print |
| 108 | `[PASS]` to stderr. The captured stdout of every wrapper |
| 109 | invocation in this session must not contain |
| 110 | `NETDATA_CLOUD_TOKEN` bytes, `X-Netdata-Auth: Bearer |
| 111 | <real-uuid>`, or any cached-bearer UUID from |
| 112 | `<repo>/.local/audits/query-netdata-agents/bearers/`. |
| 113 | |
| 114 | ## Cross-skill (depends on the cloud skill) |
| 115 | |
| 116 | - **Q19** -- Pick a node UUID from the Cloud `/nodes` listing |
| 117 | (uses the cloud skill's `query-nodes.md`), then call |
| 118 | `agents_query_agent` directly against it (this skill). |
| 119 | Confirm both transports return the same `host[0].nm`. |