# query-netdata-cloud -- How-tos index

This directory holds **operational how-tos**: short, focused
recipes that combine the per-domain guides into answers for
specific questions. Each how-to documents the question, the steps
taken, the wrappers used, and the expected output shape.

## The "if you analyze, you author a how-to" rule

The how-tos catalog is meant to be **live**. Every time an AI
assistant (or human) is asked a question that:

1. The user expects a concrete answer to, AND
2. Is not already documented in this index, AND
3. Forces analysis (multiple wrapper calls, jq pipelines, or
   cross-referencing more than one per-domain guide)

the assistant MUST author a new how-to in this directory and add
it to the index BELOW before completing the task.

This is mandatory. Skipping it means the next assistant repeats
the same analysis from scratch.

## How-to authoring template

Filename: `<slug>.md` (e.g. `find-node-id-by-hostname.md`).

Sections:

1. **Question** -- the user-visible question, verbatim or
   paraphrased.
2. **Inputs** -- what the user must supply (space, hostname,
   time range, etc.).
3. **Steps** -- numbered, each calling exactly one wrapper from
   `query-netdata-agents/scripts/_lib.sh`.
4. **Output** -- what the assistant returns to the user.
5. **Notes / gotchas** -- edge cases, follow-ups, related
   how-tos.
6. **Source guides** -- cross-links to the per-domain guides
   used.

Every code example must use the token-safe wrappers
(`agents_query_cloud`, `agents_query_agent`,
`agents_call_function`). No raw curl with `-H "Authorization:
Bearer $TOKEN"` -- that defeats the no-token-leak guarantee.

## Index

(Populate as how-tos are authored. Stubs below mirror the canonical
skill-verification harness questions for `verify/questions.md`; replace each
`(stub -- not yet authored)` with a real link as soon as a how-to is written.)

### Identity / hardware / OS

- `find-node-id-by-hostname.md` (stub -- not yet authored)
- `find-node-hardware-specs.md` (stub -- not yet authored)
- `find-node-os.md` (stub -- not yet authored)

### Metrics / fleet SLOs

- [`compare-explicit-and-room-wide-node-scope.md`](./compare-explicit-and-room-wide-node-scope.md) -- compare a fixed UUID scope with the current room-wide node scope; explains why all-room queries omit `scope.nodes` and use `selectors.nodes: ["*"]`, why a large UUID selector is redundant and expensive, and how to pass large payloads through the token-safe wrapper with `@file`.
- [`fleet-connectivity-slo-queries.md`](./fleet-connectivity-slo-queries.md) -- single-dimension fleet percentages (percent of devices connected/streaming, percent of devices with a boolean dimension at 1 or 0) and ranking devices by percent of time a boolean dimension was 0; includes the average-of-boolean trick and the countif-through-Cloud caveat.

### Streaming / parents / vnodes

- `is-node-a-parent-and-children.md` (stub -- not yet authored)
- `is-node-a-child-and-parent-target.md` (stub -- not yet authored)
- `list-vnodes-on-node.md` (stub -- not yet authored)
- [`diagnose-no-data-on-zoom-parent-retention-gaps.md`](./diagnose-no-data-on-zoom-parent-retention-gaps.md) -- why a node shows "No data" when zooming in while wider zoom renders fine: identify the serving agent from jsonwrap `.agents`, compare forced-tier queries (tier 0 vs 1 vs 2), reduce all-null rows to gap runs, run the decisive control test (does the PARENT's own local data have the same tier0 hole?), read the parent's daemon log via the `windows-events`/`systemd-journal` Function for `DBENGINE` write errors, and quantify child streaming flapping via `netdata.streaming_outbound` `replicating` buckets.

### Collectors / jobs

- `find-failed-collection-jobs.md` (stub -- not yet authored)
- `is-collector-monitoring-X-and-frequency.md` (stub -- not yet authored)

### Top processes

- `pid-with-biggest-memory-and-app-group.md` (stub -- not yet authored)

### Alerts

- `currently-firing-alerts-in-room.md` (stub -- not yet authored)
- `alert-config-by-cfg-hash.md` (stub -- not yet authored)
- `silenced-alerts.md` (stub -- not yet authored)

### Logs / status file

- `last-netdata-status-file-log.md` (stub -- not yet authored)
- `recent-error-logs-in-namespace.md` (stub -- not yet authored)

### Topology / flows

- `local-l2-topology-summary.md` (stub -- not yet authored)
- [`group-network-topology-by-kubernetes-pod.md`](./group-network-topology-by-kubernetes-pod.md) -- summarize `topology:network-connections` process actors by Kubernetes pod and namespace through Cloud.
- [`find-containers-for-topology-port.md`](./find-containers-for-topology-port.md) -- find containers or pods exposing a specific TCP port from the Cloud topology Function payload.
- [`validate-local-netflow-function.md`](./validate-local-netflow-function.md)
- `top-flow-talkers-last-hour.md` (stub -- not yet authored)

### Members / rooms / feed

- `members-by-role-in-space.md` (stub -- not yet authored)
- `rooms-with-most-nodes.md` (stub -- not yet authored)
- `node-state-changes-last-hour.md` (stub -- not yet authored)

## Cross-skill how-tos

When the answer needs both Cloud-side and direct-agent-side calls
(e.g. "find the parent of a stale node, then read its
streaming-state directly"), author the how-to under the skill
that owns the FIRST wrapper call and cross-link to the other.
