| 1 | # Query agent streaming (parent / child / replication) |
| 2 | |
| 3 | This guide is part of the [`query-netdata-agents`](./SKILL.md) skill. |
| 4 | Read [SKILL.md](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | Netdata agents form a streaming graph: a **child** sends its |
| 7 | metrics to a **parent**, which can in turn forward to another |
| 8 | parent. The same agent can be both a parent (receiving from |
| 9 | children) and a child (sending upstream). This guide covers how to |
| 10 | query that graph from a specific agent's perspective. |
| 11 | |
| 12 | There is **no Cloud-side equivalent** for the agent-internal |
| 13 | streaming/replication state -- this surface is agent-only. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Function name |
| 18 | |
| 19 | The agent registers a Function called `netdata-streaming` (verified |
| 20 | live; see |
| 21 | [../query-netdata-cloud/query-functions.md#frequently-registered-functions](../query-netdata-cloud/query-functions.md#frequently-registered-functions)). |
| 22 | It returns: |
| 23 | |
| 24 | - Per-streaming-peer connection state (replication progress, |
| 25 | bytes-in / bytes-out, last-error). |
| 26 | - Whether this agent is acting as a parent, a child, or both. |
| 27 | - The list of children currently streaming to this agent. |
| 28 | - The parent endpoints this agent is streaming to. |
| 29 | - ML status of the streaming pipeline (if ML is enabled). |
| 30 | |
| 31 | ## Use the wrapper |
| 32 | |
| 33 | ```bash |
| 34 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 35 | agents_load_env |
| 36 | |
| 37 | # Discover the parameters first. |
| 38 | agents_query_agent \ |
| 39 | --node "$NODE_UUID" \ |
| 40 | --host "$AGENT_HOST:19999" \ |
| 41 | --machine-guid "$AGENT_MG" \ |
| 42 | POST '/api/v3/function?function=netdata-streaming' '{"info":true}' \ |
| 43 | | jq '{accepted_params, required_params}' |
| 44 | |
| 45 | # Real query: top-level streaming state. |
| 46 | agents_query_agent \ |
| 47 | --node "$NODE_UUID" \ |
| 48 | --host "$AGENT_HOST:19999" \ |
| 49 | --machine-guid "$AGENT_MG" \ |
| 50 | POST '/api/v3/function?function=netdata-streaming' '{"timeout":30000}' |
| 51 | ``` |
| 52 | |
| 53 | The response uses the standard Function envelope; `data` holds |
| 54 | the per-peer rows. See |
| 55 | [../query-netdata-cloud/query-functions.md](../query-netdata-cloud/query-functions.md) |
| 56 | for the envelope definition and the canonical |
| 57 | `<repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md`. |
| 58 | |
| 59 | ## Question-to-query cheatsheet |
| 60 | |
| 61 | | Question | Approach | |
| 62 | |---|---| |
| 63 | | "Is this node a parent?" | Check `summary.nodes[0].labels._is_parent` from a metrics query (cheapest), OR look at the `netdata-streaming` Function's per-peer rows -- if any `direction:incoming` rows exist, this node is a parent. | |
| 64 | | "Of how many and which nodes?" | Filter the Function's rows where `direction:incoming` -- one per child. Each row carries the child's hostname and node id. | |
| 65 | | "Is this node a child? Where does it stream?" | Check `summary.nodes[0].labels._is_parent == false` AND look for `direction:outgoing` rows in the Function -- the destination is the upstream parent. | |
| 66 | | "What is the replication progress?" | Each row has replication-related fields (`replication_progress`, `replication_lag`, `replication_eta`). | |
| 67 | | "Are there any disconnected peers?" | Filter rows where `state` != `connected` / `streaming`. | |
| 68 | |
| 69 | ## Ancillary surfaces |
| 70 | |
| 71 | - **Per-stream metrics** (bandwidth, packets, dropped points) are |
| 72 | exposed as Netdata charts under the `netdata.streaming.*` |
| 73 | context family. Use [query-metrics.md](./query-metrics.md) to |
| 74 | query them as time series. |
| 75 | - **Streaming configuration** (which parents this agent connects |
| 76 | to, retention settings) lives in |
| 77 | `/etc/netdata/stream.conf`. The DynCfg path is |
| 78 | `/streaming` if your agent version exposes streaming config |
| 79 | through DynCfg; check via |
| 80 | `agents_query_agent ... GET '/api/v3/config?action=tree&path=/streaming'`. |
| 81 | - **`_is_parent` / `_is_ephemeral`** chart-labels surface the |
| 82 | parent / ephemeral state succinctly; see |
| 83 | [query-nodes.md](./query-nodes.md). |
| 84 | |
| 85 | ## Limits and gotchas |
| 86 | |
| 87 | - **Function name**: literal `netdata-streaming` (note the dash, |
| 88 | not a colon). The listing endpoint is the only authoritative |
| 89 | source -- if your agent is older, the Function name may differ. |
| 90 | - **Cloud aggregation does not exist** for streaming state. To |
| 91 | build a fleet-wide view, fan out per-agent calls and merge |
| 92 | client-side. |
| 93 | - **Per-peer rows can be tens of KB each** when there are many |
| 94 | children. Use `last` or pagination knobs in the Function body |
| 95 | if needed. |
| 96 | - **Agent must have streaming enabled.** A standalone (non- |
| 97 | streaming) agent has no rows; the Function still returns 200 |
| 98 | but with an empty `data` array. |
| 99 | |
| 100 | ## See also |
| 101 | |
| 102 | - [query-functions.md](./query-functions.md) -- generic Function |
| 103 | transport. |
| 104 | - [../query-netdata-cloud/query-functions.md](../query-netdata-cloud/query-functions.md) |
| 105 | -- canonical Function reference + envelope. |
| 106 | - [query-nodes.md](./query-nodes.md) -- node identity, parent / |
| 107 | child labels. |