@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 100 lines 4.02 KB
Rendered Raw
1 # Query agent Functions directly
2
3 This guide is part of the [`query-netdata-agents`](./SKILL.md) skill.
4 Read [SKILL.md](./SKILL.md#prerequisites) first for the
5 prerequisites (cloud token, network reachability, bearer flow).
6
7 For the response envelope (`status`, `v`, `type`, `help`,
8 `accepted_params`, `required_params`, `has_history`,
9 `update_every`, `data`), the four Function families, the canonical
10 protocol reference at
11 `<repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md`, and per-Function
12 body shapes, see
13 [../query-netdata-cloud/query-functions.md](../query-netdata-cloud/query-functions.md).
14 The agent and the Cloud proxy expose the same Function payload
15 shape -- the only difference is the URL and the auth header.
16
17 ---
18
19 ## Endpoint (agent v3)
20
21 `POST /api/v3/function?function={functionName}` on the agent at
22 port 19999. Path on the agent's HTTP API:
23
24 ```
25 http://<agent>:19999/host/<node-uuid>/api/v3/function?function=<name>
26 ```
27
28 `/api/v2/function` is also accepted on older agents -- prefer v3.
29
30 ## Discover Functions on a single agent
31
32 Most agents expose a function-listing surface through the same
33 generic Function call with `function=info`-like discovery. To
34 enumerate by name, query each Function with `{"info":true}`. For
35 a top-level list, use the Cloud-side functions endpoint via
36 [../query-netdata-cloud/query-functions.md#list-available-functions](../query-netdata-cloud/query-functions.md#list-available-functions);
37 the Cloud listing is authoritative even when you ultimately call
38 the agent directly.
39
40 ## Invoke a Function via the wrapper
41
42 ```bash
43 source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh"
44 agents_load_env
45
46 # Discover the parameter set (info=true is the safe first call).
47 agents_query_agent \
48 --node "$AGENT_EVENTS_NODE_ID" \
49 --host "$AGENT_EVENTS_HOSTNAME:19999" \
50 --machine-guid "$AGENT_EVENTS_MACHINE_GUID" \
51 POST '/api/v3/function?function=processes' '{"info":true}'
52
53 # Real query (after `info` told you the parameters).
54 agents_query_agent \
55 --node "$AGENT_EVENTS_NODE_ID" \
56 --host "$AGENT_EVENTS_HOSTNAME:19999" \
57 --machine-guid "$AGENT_EVENTS_MACHINE_GUID" \
58 POST '/api/v3/function?function=processes' '{"last":50,"timeout":30000}'
59 ```
60
61 The wrapper writes the response JSON to stdout; stderr shows the
62 curl invocation with `<AGENT_BEARER>` masked (the bearer is
63 minted/cached/refreshed internally and never reaches stdout).
64
65 ## When to prefer agent-direct over Cloud-proxied
66
67 - **Lower latency.** Direct skips the Cloud round-trip entirely.
68 - **Cloud unavailable.** The agent answers as long as port 19999
69 is reachable from your workstation.
70 - **High-frequency batch fetches.** The Cloud may rate-limit
71 function calls; the agent does not.
72
73 When the user only has Cloud access (the typical team-member case
74 on a remote agent), use the Cloud-proxied path documented in
75 [../query-netdata-cloud/query-functions.md](../query-netdata-cloud/query-functions.md)
76 instead.
77
78 ## Limits and gotchas
79
80 - **Bearer protection**: a 412 response from the agent means the
81 agent is bearer-protected. The `agents_query_agent` wrapper
82 handles this transparently (mint via Cloud, cache, refresh).
83 Direct curl fails until you mint a bearer.
84 - **Function name is case-sensitive.** Wrong casing returns 400.
85 - **Response is not streamed.** Even on the agent, the Function
86 response is buffered into a single JSON document.
87 - **The `cfg` field of an alert instance**, `claim_id`, `node_id`,
88 and similar UUID values appear in responses. Treat as
89 semi-sensitive; never paste raw responses into committed files.
90
91 ## See also
92
93 - [../query-netdata-cloud/query-functions.md](../query-netdata-cloud/query-functions.md)
94 -- canonical Function reference, response envelope, the four
95 families, the `info` widget schema, developer references.
96 - [../query-netdata-cloud/query-logs.md](../query-netdata-cloud/query-logs.md),
97 [query-topology.md](../query-netdata-cloud/query-topology.md),
98 [query-flows.md](../query-netdata-cloud/query-flows.md) --
99 per-family deep dives (the body shapes apply to direct-agent
100 calls verbatim).