@cryptotaxi247 / netdata-1 / commits / 305b14342

Add troubleshooting FAQ to query metrics skill (#21837)

Add troubleshooting FAQ to query metrics skill document Add 13 FAQ entries covering the most common issues users face when querying the Netdata Cloud API: empty responses on no match, metadata explosion without scope.contexts, time alignment, hostname vs UUID filtering, format limitations, context discovery, anomaly rate interpretation, tier requirements, point annotations, timeout tuning, max points clamping, and multi-context query caveats.

Costa Tsaousis committed Feb 27, 2026 at 02:21 UTC 305b143426d8d21df2e39ecc6add4a4f37c73166
1 file changed +43
docs/netdata-ai/skills/query-netdata-cloud-metrics.md
+43
@@ -877,6 +877,49 @@ Then inspect `summary.labels` in the response:
877
878 ---
879
880 +## Troubleshooting / FAQ
881 +
882 +**Q: My query returns empty data — no error, but no results either.**
883 +A: The API returns empty responses when nothing matches your filters. This is by design — it does not return an error. Check: (1) Is `scope.contexts` set to a valid context name? Typos like `cpu.system` instead of `system.cpu` silently return nothing. (2) Are your `scope.labels` or `scope.dimensions` correct? (3) If using `scope.nodes`, are the UUIDs valid? Use `/contexts` to verify context names and `/nodes` to verify UUIDs.
884 +
885 +**Q: The response is huge (megabytes) and slow.**
886 +A: You are missing `scope.contexts`. Without it, the scope defaults to the entire room — every context, instance, dimension, and label across all nodes. Always set `scope.contexts` to only the context(s) you need (e.g., `["system.cpu"]`).
887 +
888 +**Q: The time range in the response doesn't match what I requested.**
889 +A: Add `"unaligned"` to the `options` array. Without it, time intervals are aligned to wall-clock boundaries based on the query period. For example, a 1-hour query might snap to 14:00–15:00 instead of 14:07–15:07. The `unaligned` option gives you the exact time range you asked for.
890 +
891 +**Q: I'm using hostnames in `scope.nodes` and getting no data.**
892 +A: `scope.nodes` only accepts node UUIDs (the `nd` field from `/nodes`). Hostnames, patterns, and machine GUIDs do not work there. Use `selectors.nodes` instead — it accepts hostname patterns (e.g., `["web*", "prod-*"]`) and is the preferred way to filter by node.
893 +
894 +**Q: I requested CSV format but got an error or garbled output.**
895 +A: Only `json2` format works through the Cloud API. The Cloud proxy cannot aggregate CSV responses from multiple agents. Always use `"format": "json2"`.
896 +
897 +**Q: How do I find the context name for a metric I see on the dashboard?**
898 +A: The context name is shown next to the chart title on every Netdata chart (e.g., `system.cpu`, `disk.space`, `net.net`). Click it to copy it to the clipboard. You can also use the `/contexts` endpoint with a pattern like `["system.*"]` to browse available contexts.
899 +
900 +**Q: The anomaly rate (`arp`) is always 0 — is anomaly detection working?**
901 +A: An `arp` of 0 means either no anomalies were detected (normal for healthy systems) or ML-based anomaly detection is disabled on the agent. Anomaly detection runs on every metric at collection time using ML (k-means clustering). Non-zero values indicate the percentage of raw samples in the interval that were flagged as anomalous. If `arp` is 0 across all metrics and all time ranges, the agent may have ML disabled.
902 +
903 +**Q: `countif` or `percentile` time_group returns unexpected values.**
904 +A: These functions require raw per-second data. Add `"tier": 0` to the `window` object to force the use of the non-aggregated storage tier. Without it, the query may use a pre-aggregated tier (per-minute or per-hour) where these functions cannot work correctly.
905 +
906 +**Q: I see non-zero `pa` values in the data — what do they mean?**
907 +A: `pa` is a point annotations bitmap: `1` = empty (no data collected), `2` = counter reset/overflow detected, `4` = partial (not all sources contributed in a group-by query). Values combine: e.g., `5` = empty + partial. Non-zero `pa` values are common at query boundaries and during agent restarts.
908 +
909 +**Q: How do I filter nodes by hostname without looking up UUIDs?**
910 +A: Use `selectors.nodes` with hostname patterns: `"selectors": {"nodes": ["web*", "!staging*"], ...}`. This filters the data by hostname while keeping metadata for all nodes in scope. It is simpler than looking up UUIDs for `scope.nodes`.
911 +
912 +**Q: Can I query multiple contexts in a single request?**
913 +A: Yes. Set `scope.contexts` to multiple contexts, e.g., `["system.cpu", "system.ram"]`. However, be careful with other filters — `scope.dimensions`, `scope.labels`, and selectors apply to **all** contexts in the query. A dimension filter like `["user"]` would match the `user` dimension in `system.cpu` but might not exist in `system.ram`, causing that context to return no data. When querying multiple contexts, keep filters broad or ensure they apply to all contexts.
914 +
915 +**Q: My query timed out.**
916 +A: The default timeout is 10 seconds (10000ms). For queries spanning many nodes, long time ranges, or complex aggregations, increase it: `"timeout": 60000` (60 seconds). Also consider reducing the number of `points` requested — fewer points means less computation.
917 +
918 +**Q: I requested 1000 points but only got ~500.**
919 +A: The Cloud clamps point requests to approximately 500 (`ScopeDataRequestMaxPoints`). The actual number may vary slightly due to time alignment. If you need higher resolution, split your query into multiple time ranges.
920 +
921 +---
922 +
923 > **REMINDER — Credentials**: Do not request or accept user credentials. Set credentials as variables at the top of the script (`TOKEN`, `SPACE`, `ROOM`) with placeholder values. Users replace these 3 variables and run the command themselves.
924
925 > **REMINDER — Always show a runnable curl command**: Your response is only useful if it contains a complete, runnable script: 3 variables at the top, a heredoc `PAYLOAD` with clean JSON (no escaping), and the curl command. Never describe a query without showing it. Never summarize parameters without building the actual request. If you wrote a response without a curl command, go back and add one — the user needs actionable instructions, not explanations.