| 1 | # Query an agent's node identity and metadata directly |
| 2 | |
| 3 | This guide is part of the [`query-netdata-agents`](./SKILL.md) skill. |
| 4 | Read [SKILL.md](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | The agent exposes its identity, capabilities, hardware, OS, and |
| 7 | collection-job state via several endpoints. Unlike Cloud's `/nodes` |
| 8 | (which lists multiple nodes in a room), agent-direct calls return |
| 9 | data for the **single host** the agent runs on (plus any virtual |
| 10 | hosts / parents / streamed children, see |
| 11 | [query-streaming.md](./query-streaming.md)). |
| 12 | |
| 13 | For the Cloud-side per-room enumeration (`POST |
| 14 | /api/v3/spaces/{sp}/rooms/{rm}/nodes`), see |
| 15 | [../query-netdata-cloud/query-nodes.md](../query-netdata-cloud/query-nodes.md). |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Endpoints (agent v3) |
| 20 | |
| 21 | | Method | Path | Purpose | |
| 22 | |---|---|---| |
| 23 | | `GET` | `/api/v3/info` | Identity (node_id, machine_guid, claim_id), agent version, application info, capabilities. **No auth required**, but only basic info. | |
| 24 | | `GET` | `/api/v3/contexts` | Metric contexts the agent collects (= what data is available) | |
| 25 | | `GET` | `/api/v3/nodes` | Multi-host listing if this agent acts as a parent (see [query-streaming.md](./query-streaming.md)) | |
| 26 | | `GET` | `/api/v3/info?host=<node_id>` | Detail for a specific host (when multi-host) | |
| 27 | |
| 28 | ## Use the wrappers |
| 29 | |
| 30 | ```bash |
| 31 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 32 | agents_load_env |
| 33 | |
| 34 | # /info is unauthenticated -- you can call it without the bearer. |
| 35 | # But going through agents_query_agent uses the bearer flow, which |
| 36 | # is fine and consistent. |
| 37 | agents_query_agent \ |
| 38 | --node "$NODE_UUID" \ |
| 39 | --host "$AGENT_HOST:19999" \ |
| 40 | --machine-guid "$AGENT_MG" \ |
| 41 | GET /api/v3/info \ |
| 42 | | jq '.agents[0] | {nm, nd, mg, cloud, application: .application.package.version}' |
| 43 | |
| 44 | # Hardware and OS labels (typically exposed under .labels in /info or |
| 45 | # in the chart-labels namespace; see the response shape). |
| 46 | agents_query_agent \ |
| 47 | --node "$NODE_UUID" \ |
| 48 | --host "$AGENT_HOST:19999" \ |
| 49 | --machine-guid "$AGENT_MG" \ |
| 50 | GET /api/v3/info \ |
| 51 | | jq '.agents[0].application, .agents[0].cloud' |
| 52 | |
| 53 | # Claim_id specifically (used by the bearer-mint flow). |
| 54 | agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \ |
| 55 | GET /api/v3/info | jq -r '.agents[0].cloud.claim_id' |
| 56 | ``` |
| 57 | |
| 58 | ## Top-level response shape (`/api/v3/info`) |
| 59 | |
| 60 | ```text |
| 61 | { |
| 62 | "api": 2, |
| 63 | "agents": [ |
| 64 | { |
| 65 | "mg": "<machine_guid UUID>", |
| 66 | "nd": "<node UUID>", |
| 67 | "nm": "<hostname>", |
| 68 | "now": <unix-seconds>, |
| 69 | "ai": <agent index>, |
| 70 | "application": { |
| 71 | "package": { "version": "vX.Y.Z-...", "type": "binpkg-deb|...", "arch": "x86_64|...", ... }, |
| 72 | "configure": "cmake -...", |
| 73 | ... |
| 74 | }, |
| 75 | "cloud": { |
| 76 | "claim_id": "<UUID>", |
| 77 | "aclk": "available|online|...", |
| 78 | ... |
| 79 | }, |
| 80 | "labels": { ... }, |
| 81 | ... |
| 82 | } |
| 83 | ], |
| 84 | ... |
| 85 | } |
| 86 | ``` |
| 87 | |
| 88 | For the full per-agent label set, the `chart-labels` are usually |
| 89 | exposed via the metrics path's `summary.nodes[].labels` (see |
| 90 | [query-metrics.md](./query-metrics.md)). |
| 91 | |
| 92 | ## Hardware / OS query patterns |
| 93 | |
| 94 | Hardware and OS facts live primarily in the agent's host-labels. |
| 95 | On a fully-running agent the labels are present in `/api/v3/info` |
| 96 | and copied verbatim into the Cloud `/nodes` `.labels` field (the |
| 97 | fast path for cross-fleet queries). |
| 98 | |
| 99 | | Field | Where it lives | |
| 100 | |---|---| |
| 101 | | Architecture, kernel, OS name/version | `agents[0].application` (build-time) AND `summary.nodes[].labels._architecture`, `_kernel_version`, `_os_name`, `_os_version` | |
| 102 | | CPU count, RAM, disk space | `summary.nodes[].labels._system_cores`, `_system_ram_total`, `_system_disk_space` (chart-labels) | |
| 103 | | Cloud provider / region / instance type | `summary.nodes[].labels._cloud_provider_type`, `_cloud_instance_region`, `_cloud_instance_type` | |
| 104 | | Container/virtualization | `summary.nodes[].labels._container`, `_container_detection`, `_is_k8s_node`, `_is_parent`, `_is_ephemeral` | |
| 105 | |
| 106 | To fetch chart-labels as a structured object, run a metrics query |
| 107 | and read `summary.nodes[].labels`: |
| 108 | |
| 109 | ```bash |
| 110 | read -r -d '' BODY <<'JSON' |
| 111 | { |
| 112 | "scope": {"contexts": ["system.cpu"]}, |
| 113 | "selectors": {"nodes": ["*"]}, |
| 114 | "window": {"after": -60, "before": 0, "points": 1}, |
| 115 | "aggregations": {"metrics": [{"group_by": ["selected"]}], "time": {"time_group": "average"}}, |
| 116 | "format": "json2", |
| 117 | "options": ["jsonwrap", "minify", "unaligned"] |
| 118 | } |
| 119 | JSON |
| 120 | agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \ |
| 121 | POST /api/v3/data "$BODY" \ |
| 122 | | jq '.summary.nodes[0].labels' |
| 123 | ``` |
| 124 | |
| 125 | ## Collection-job state (failed / disabled jobs) |
| 126 | |
| 127 | The agent's DynCfg surface lists every collection job and its |
| 128 | status. See [query-dyncfg.md](./query-dyncfg.md): |
| 129 | |
| 130 | ```bash |
| 131 | # List every go.d.plugin job and its current state. |
| 132 | agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \ |
| 133 | GET '/api/v3/config?action=tree&path=/collectors/go.d/Jobs' \ |
| 134 | | jq '.tree["/collectors/go.d/Jobs"]' |
| 135 | ``` |
| 136 | |
| 137 | DynCfg job statuses include `running` (200), `accepted` (202), |
| 138 | `accepted-disabled` (298), `accepted-restart-required` (299), |
| 139 | plus error states (4xx/5xx). A failed-collection job appears with |
| 140 | a 4xx/5xx status and an error message. |
| 141 | |
| 142 | ## Vnodes |
| 143 | |
| 144 | Virtual nodes (configured via `/etc/netdata/vnodes/`) are listed |
| 145 | under `/collectors/go.d/Vnodes` and `/collectors/ibm.d/Vnodes` in |
| 146 | the DynCfg tree. Use the same DynCfg path: |
| 147 | |
| 148 | ```bash |
| 149 | agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \ |
| 150 | GET '/api/v3/config?action=tree&path=/collectors/go.d/Vnodes' |
| 151 | ``` |
| 152 | |
| 153 | ## Limits and gotchas |
| 154 | |
| 155 | - **`/api/v3/info` is unauthenticated**, but most other paths |
| 156 | require the bearer. The wrapper always uses the bearer; that's |
| 157 | fine for `/info` too. |
| 158 | - **`labels` location varies by version.** On older agents some |
| 159 | labels appear only in `summary.nodes[].labels` of metrics |
| 160 | responses; on newer agents they're also under |
| 161 | `agents[0].labels`. Check both. |
| 162 | - **Streaming roles** (parent / child) are at |
| 163 | `summary.nodes[].labels._is_parent` (true/false), and the |
| 164 | full streaming surface lives in |
| 165 | [query-streaming.md](./query-streaming.md). |
| 166 | |
| 167 | ## See also |
| 168 | |
| 169 | - [../query-netdata-cloud/query-nodes.md](../query-netdata-cloud/query-nodes.md) |
| 170 | -- per-room / per-space node enumeration via Cloud. |
| 171 | - [query-dyncfg.md](./query-dyncfg.md) -- DynCfg surface (jobs, |
| 172 | vnodes, config). |
| 173 | - [query-streaming.md](./query-streaming.md) -- parent/child |
| 174 | streaming relationships and replication state. |
| 175 | - [query-metrics.md](./query-metrics.md) -- chart-labels via |
| 176 | `summary.nodes[].labels` of metric queries. |