@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 73 lines 2.09 KB
Rendered Raw
1 # Query agent topology 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 topology body and response payload are the same as the Cloud-proxied
7 transport. For the production topology schema, response fields, compact table
8 format, and interpretation rules, see
9 [../query-netdata-cloud/query-topology.md](../query-netdata-cloud/query-topology.md).
10
11 ## Endpoint
12
13 `POST /api/v3/function?function=topology:<source>`
14
15 Example:
16
17 ```bash
18 source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh"
19 agents_load_env
20 AGENT_URL="${AGENT_URL:-http://${AGENT_HOST:-127.0.0.1}:${AGENT_PORT:-19999}}"
21 AGENT_TARGET="${AGENT_URL#http://}"
22 AGENT_TARGET="${AGENT_TARGET#https://}"
23 AGENT_TARGET="${AGENT_TARGET%%/*}"
24
25 read -r -d '' BODY <<'JSON'
26 {
27 "selections": {
28 "mode": ["aggregated"]
29 },
30 "timeout": 60000
31 }
32 JSON
33
34 agents_query_agent \
35 --node "$NODE_UUID" \
36 --host "$AGENT_TARGET" \
37 --machine-guid "$AGENT_MG" \
38 POST '/api/v3/function?function=topology:network-connections' "$BODY" \
39 | jq '.data | {
40 schema: .schema_version,
41 actors: .actors.rows,
42 links: .links.rows,
43 evidence_rows: ([.evidence[]?.table.rows] | add // 0)
44 }'
45 ```
46
47 ## Discover supported parameters
48
49 ```bash
50 agents_query_agent \
51 --node "$NODE_UUID" \
52 --host "$AGENT_TARGET" \
53 --machine-guid "$AGENT_MG" \
54 POST '/api/v3/function?function=topology:network-connections' \
55 '{"info":true,"timeout":30000}' \
56 | jq '.required_params'
57 ```
58
59 ## Notes
60
61 - The graph is the perspective of the queried Agent or producer instance.
62 - Fleet-wide views require Cloud aggregation over multiple topology payloads.
63 - High-cardinality relationship facts live in evidence sections, not graph
64 links.
65 - Topology Functions should fail explicitly on size limits; they must not
66 silently truncate evidence.
67
68 ## See also
69
70 - [../query-netdata-cloud/query-topology.md](../query-netdata-cloud/query-topology.md)
71 -- full response reference.
72 - [query-functions.md](./query-functions.md) -- generic direct-agent Function
73 transport.