ContextQMD
Back to Netdata

Query agent network flows directly

docs/netdata-ai/skills/query-netdata-agents/query-flows.md

2.11.03.0 KB
Original Source

Query agent network flows directly

This guide is part of the query-netdata-agents skill. Read SKILL.md first.

For the body parameters (mode, view, after, before, query, selections, facets, group_by, sort_by, top_n, field, term), the response envelope (data.flows[], data.columns, data.facets, data.stats), and the three modes (flows / autocomplete) plus five views (table-sankey, timeseries, country-map, state-map, city-map), see ../query-netdata-cloud/query-flows.md. The body and response are identical between Cloud-proxied and direct-agent calls.

Today only flows:netflow is registered (covers NetFlow v5/v9, IPFIX, sFlow). The agent must run the netflow-plugin Rust crate for the Function to be available.

The direct endpoint has the same CIDR behavior as Cloud: the six IP address facets accept exact IPv4/IPv6 addresses or canonical CIDRs, and autocomplete terms containing / generate canonical CIDR candidates from loose input such as 10/8. Only candidates containing an address in that field's retention-wide vocabulary are returned. One trailing dot before / is tolerated after one through three IPv4 octets, so 10./ is equivalent to 10/. Suggestions are not recalculated for the current time window or other active filters.

Endpoint (agent v3)

POST /api/v3/function?function=flows:netflow

Use the wrapper

bash
source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh"
agents_load_env

read -r -d '' BODY <<'JSON'
{
  "mode":     "flows",
  "view":     "table-sankey",
  "after":    -3600,
  "before":   0,
  "group_by": ["SRC_ADDR", "DST_ADDR", "PROTOCOL"],
  "sort_by":  "bytes",
  "top_n":    100
}
JSON

agents_query_agent \
    --node    "$NODE_UUID" \
    --host    "$AGENT_HOST:19999" \
    --machine-guid "$AGENT_MG" \
    POST '/api/v3/function?function=flows:netflow' "$BODY" \
  | jq '.data | {view, group_by, flows_count: (.flows|length), stats}'

Discover supported parameters

bash
agents_query_agent --node "$NODE_UUID" --host "$AGENT_HOST:19999" --machine-guid "$AGENT_MG" \
    POST '/api/v3/function?function=flows:netflow' '{"info":true}' \
  | jq '.required_params'

Limits and gotchas

  • L3 only. No L2 visibility, no application-layer dissection.
  • Sampling matters. NetFlow v5/v9 and sFlow are sampled at the source device; reported byte/packet counts are scaled by the sample rate. Verify source-device sampling configuration before treating absolute volumes as ground truth.
  • GeoIP / AS DB dependency. SRC_AS_NAME, DST_AS_NAME, *_COUNTRY, *_CITY only populate when the collector has the corresponding databases configured.
  • top_n is enumerated: 25, 50, 100, 200, 500. Other values rejected.

See also