@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 118 lines 3.52 KB
Rendered Raw
1 # Validate a local Cloud-connected flow Function
2
3 ## Question
4
5 How can an assistant validate `flows:netflow` on a local Netdata Agent
6 that is connected to Netdata Cloud, without exposing Cloud tokens,
7 agent bearers, node ids, or raw flow rows?
8
9 ## Inputs
10
11 - Local agent URL, usually `http://127.0.0.1:19999`.
12 - `NETDATA_CLOUD_TOKEN` and `NETDATA_CLOUD_HOSTNAME` in `<repo>/.env`.
13 - The agent must have `flows:netflow` registered.
14
15 ## Steps
16
17 1. Capture local agent identity in memory without printing identifiers:
18
19 ```bash
20 INFO_JSON="$(curl -sS --max-time 10 http://127.0.0.1:19999/api/v3/info)"
21
22 jq -r '.agents[0] | {
23 cloud_status: .cloud.status,
24 node_id_present: ((.nd // "") | length > 0),
25 machine_guid_present: ((.mg // "") | length > 0),
26 claim_id_present: ((.cloud.claim_id // "") | length > 0)
27 }' <<<"$INFO_JSON"
28 ```
29
30 2. Load the token-safe wrappers:
31
32 ```bash
33 source docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh
34 agents_load_env
35 ```
36
37 3. Verify the Function info envelope via Cloud:
38
39 ```bash
40 NODE_UUID="$(jq -r '.agents[0].nd' \
41 <<<"$INFO_JSON")"
42
43 mkdir -p .local/audits/query-netdata-agents
44
45 agents_call_function \
46 --via cloud \
47 --node "$NODE_UUID" \
48 --function flows:netflow \
49 --body '{"info":true}' \
50 > .local/audits/query-netdata-agents/flows-netflow-info-cloud.json
51
52 jq '{status, type, has_history,
53 accepted_params_count: (.accepted_params | length),
54 required_params_count: (.required_params | length)}' \
55 .local/audits/query-netdata-agents/flows-netflow-info-cloud.json
56 ```
57
58 4. Run a real flow query using the documented request shape:
59
60 ```bash
61 read -r -d '' BODY <<'JSON'
62 {
63 "mode": "flows",
64 "view": "table-sankey",
65 "after": -3600,
66 "before": 0,
67 "group_by": ["SRC_AS_NAME", "PROTOCOL", "DST_AS_NAME"],
68 "sort_by": "bytes",
69 "top_n": 100
70 }
71 JSON
72
73 agents_call_function \
74 --via cloud \
75 --node "$NODE_UUID" \
76 --function flows:netflow \
77 --body "$BODY" \
78 > .local/audits/query-netdata-agents/flows-netflow-last-hour-cloud.json
79
80 jq '{status, type, view: .data.view,
81 flows_count: (.data.flows | length),
82 group_by: .data.group_by,
83 stats: .data.stats}' \
84 .local/audits/query-netdata-agents/flows-netflow-last-hour-cloud.json
85 ```
86
87 ## Output
88
89 Return only a sanitized summary:
90
91 - Function info `status` and `type`.
92 - Flow query row count.
93 - Group-by fields.
94 - Selected aggregate counters from `.data.stats`, such as
95 `decoded_netflow_v5`, `decoded_netflow_v9`, `decoded_ipfix`,
96 `decoded_sflow`, `journal_entries_written`, and
97 `journal_write_errors`.
98
99 Do not paste node ids, machine GUIDs, claim ids, Cloud tokens, agent
100 bearers, raw IP addresses, or raw flow rows into durable artifacts.
101
102 ## Notes / gotchas
103
104 - Prefer the Cloud transport for validation. It needs only the Cloud
105 token and does not require a direct agent bearer.
106 - Direct-agent validation is also possible. Use the sibling
107 direct-agent how-to when the test must prove the bearer mint/cache
108 path and the `X-Netdata-Auth` call path.
109 - Negative `after` values are relative to `before`; `before: 0` means
110 now. `top_n` accepts the documented values `25`, `50`, `100`,
111 `200`, or `500`.
112
113 ## Source guides
114
115 - [Network-flow Functions](../query-flows.md)
116 - [Generic Function invocation](../query-functions.md)
117 - [Direct-agent sibling skill](../../query-netdata-agents/SKILL.md)
118 - [Direct local flow Function validation](../../query-netdata-agents/how-tos/validate-direct-local-flow-function.md)