| 1 | # Query agent network flows 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 | For the body parameters (`mode`, `view`, `after`, `before`, |
| 7 | `query`, `selections`, `facets`, `group_by`, `sort_by`, `top_n`, |
| 8 | `field`, `term`), the response envelope (`data.flows[]`, |
| 9 | `data.columns`, `data.facets`, `data.stats`), and the three modes |
| 10 | (`flows` / `autocomplete`) plus five views (`table-sankey`, |
| 11 | `timeseries`, `country-map`, `state-map`, `city-map`), see |
| 12 | [../query-netdata-cloud/query-flows.md](../query-netdata-cloud/query-flows.md). |
| 13 | The body and response are identical between Cloud-proxied and |
| 14 | direct-agent calls. |
| 15 | |
| 16 | Today only `flows:netflow` is registered (covers NetFlow v5/v9, |
| 17 | IPFIX, sFlow). The agent must run the netflow-plugin Rust crate |
| 18 | for the Function to be available. |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## Endpoint (agent v3) |
| 23 | |
| 24 | `POST /api/v3/function?function=flows:netflow` |
| 25 | |
| 26 | ## Use the wrapper |
| 27 | |
| 28 | ```bash |
| 29 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 30 | agents_load_env |
| 31 | |
| 32 | read -r -d '' BODY <<'JSON' |
| 33 | { |
| 34 | "mode": "flows", |
| 35 | "view": "table-sankey", |
| 36 | "after": -3600, |
| 37 | "before": 0, |
| 38 | "group_by": ["SRC_ADDR", "DST_ADDR", "PROTOCOL"], |
| 39 | "sort_by": "bytes", |
| 40 | "top_n": 100 |
| 41 | } |
| 42 | JSON |
| 43 | |
| 44 | agents_query_agent \ |
| 45 | --node "$NODE_UUID" \ |
| 46 | --host "$AGENT_HOST:19999" \ |
| 47 | --machine-guid "$AGENT_MG" \ |
| 48 | POST '/api/v3/function?function=flows:netflow' "$BODY" \ |
| 49 | | jq '.data | {view, group_by, flows_count: (.flows|length), stats}' |
| 50 | ``` |
| 51 | |
| 52 | ## Discover supported parameters |
| 53 | |
| 54 | ```bash |
| 55 | agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \ |
| 56 | POST '/api/v3/function?function=flows:netflow' '{"info":true}' \ |
| 57 | | jq '.required_params' |
| 58 | ``` |
| 59 | |
| 60 | ## Limits and gotchas |
| 61 | |
| 62 | - **L3 only.** No L2 visibility, no application-layer dissection. |
| 63 | - **Sampling matters.** NetFlow v5/v9 and sFlow are sampled at |
| 64 | the source device; reported byte/packet counts are scaled by |
| 65 | the sample rate. Verify source-device sampling configuration |
| 66 | before treating absolute volumes as ground truth. |
| 67 | - **GeoIP / AS DB dependency.** `SRC_AS_NAME`, `DST_AS_NAME`, |
| 68 | `*_COUNTRY`, `*_CITY` only populate when the collector has the |
| 69 | corresponding databases configured. |
| 70 | - **`top_n` is enumerated**: 25, 50, 100, 200, 500. Other values |
| 71 | rejected. |
| 72 | |
| 73 | ## See also |
| 74 | |
| 75 | - [../query-netdata-cloud/query-flows.md](../query-netdata-cloud/query-flows.md) |
| 76 | -- full reference. |
| 77 | - [query-functions.md](./query-functions.md) -- generic Function |
| 78 | transport. |