@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 160 lines 4.48 KB
Rendered Raw
1 # Query topology Functions via Netdata Cloud
2
3 This guide is part of the [`query-netdata-cloud`](./SKILL.md) skill.
4 Read the [SKILL.md prerequisites](./SKILL.md#prerequisites) first.
5 For the generic Function transport, see [query-functions.md](./query-functions.md).
6
7 Topology Functions return compact graph payloads using the production topology
8 schema:
9
10 - [FUNCTION_TOPOLOGY_SCHEMA.json](../../../../src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json)
11
12 The response contains actors, graph links, relationship evidence, optional
13 actor detail tables, and optional telemetry overlay refs. Large sections use
14 compact columnar tables.
15
16 ## Function namespace
17
18 Topology Functions use the `topology:<source>` namespace.
19
20 Known producer families:
21
22 | Function | Source | Typical topology |
23 |---|---|---|
24 | `topology:network-connections` | Network Viewer plugin | process, endpoint, socket evidence |
25 | `topology:streaming` | Netdata streaming subsystem | parent/child streaming graph |
26 | `topology:snmp` | SNMP topology collector | L2 devices, interfaces, endpoints, adjacencies |
27 | `topology:vsphere` | vSphere collector (planned) | inventory and virtualization relationships |
28
29 Always start with an info request to discover the parameters supported by the
30 Agent version you are querying.
31
32 ## Endpoint
33
34 Use the standard Cloud Function endpoint:
35
36 `POST /api/v2/nodes/{nodeId}/function?function=topology:<source>`
37
38 Example info request:
39
40 ```bash
41 TOKEN="YOUR_API_TOKEN"
42 NODE="YOUR_NODE_UUID"
43
44 curl -sS -X POST \
45 -H 'Content-Type: application/json' \
46 -H "Authorization: Bearer $TOKEN" \
47 "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=topology:network-connections" \
48 -d '{"info":true,"timeout":30000}'
49 ```
50
51 Example data request:
52
53 ```bash
54 TOKEN="YOUR_API_TOKEN"
55 NODE="YOUR_NODE_UUID"
56
57 read -r -d '' PAYLOAD <<'EOF'
58 {
59 "selections": {
60 "mode": ["aggregated"]
61 },
62 "timeout": 60000
63 }
64 EOF
65
66 curl -sS -X POST \
67 -H 'Content-Type: application/json' \
68 -H "Authorization: Bearer $TOKEN" \
69 "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=topology:network-connections" \
70 -d "$PAYLOAD"
71 ```
72
73 ## Response shape
74
75 Top-level response:
76
77 ```json
78 {
79 "status": 200,
80 "type": "topology",
81 "has_history": false,
82 "data": {
83 "schema_version": "netdata.topology.v1",
84 "producer": {},
85 "collected_at": "2026-05-09T10:00:00Z",
86 "dictionaries": {},
87 "types": {},
88 "actors": {},
89 "links": {},
90 "evidence": {},
91 "tables": {},
92 "overlays": {},
93 "stats": {}
94 }
95 }
96 ```
97
98 The important fields:
99
100 | Field | Description |
101 |---|---|
102 | `data.schema_version` | Topology contract version, currently `netdata.topology.v1` |
103 | `data.producer` | Producer source, instance, node, plugin, and version metadata |
104 | `data.dictionaries` | Shared dictionaries, especially `strings` |
105 | `data.types.actor_types` | Actor identity and aggregation-scope metadata |
106 | `data.types.link_types` | Link direction and aggregation policy |
107 | `data.types.evidence_types` | Evidence role and exact match columns |
108 | `data.actors` | Compact table of graph actors |
109 | `data.links` | Compact table of renderable graph links |
110 | `data.evidence` | Compact relationship evidence sections |
111 | `data.tables` | Optional actor or relationship detail tables |
112 | `data.overlays` | Optional metric/function overlay refs |
113 | `data.stats` | Producer and payload counters |
114
115 ## Decode compact tables
116
117 Every table has:
118
119 - `rows`: number of rows;
120 - `columns`: column definitions;
121 - `values`: parallel array of column encodings.
122
123 Supported codecs:
124
125 | Codec | Meaning |
126 |---|---|
127 | `const` | one value repeated for all rows |
128 | `values` | one value per row |
129 | `dict` | per-column dictionary plus row indexes |
130
131 Minimal jq-friendly counts:
132
133 ```bash
134 jq '.data | {
135 schema: .schema_version,
136 actors: .actors.rows,
137 links: .links.rows,
138 evidence_rows: ([.evidence[]?.table.rows] | add // 0),
139 stats
140 }'
141 ```
142
143 ## Interpretation rules
144
145 - Actors are entities.
146 - Links are graph edges.
147 - Evidence rows are the exact facts behind links.
148 - Actor custom tables are separate from relationship evidence.
149 - Direction semantics come from `data.types.link_types`.
150 - Telemetry overlays come from `data.types.overlay_templates` plus
151 `data.overlays.refs`.
152
153 Do not assume every evidence row is rendered as a graph edge. A single graph
154 link may summarize many evidence rows.
155
156 ## See also
157
158 - [query-functions.md](./query-functions.md) -- generic Function transport.
159 - [../query-netdata-agents/query-topology.md](../query-netdata-agents/query-topology.md)
160 -- direct-agent transport for the same topology payload.