@cryptotaxi247 / netdata-1 / commits / 282263938

docs: Add documentation review findings for quick-start-create-your-first-alert.md

Costa Tsaousis committed Jan 11, 2026 at 15:02 UTC 2822639383c47104d4bdfa801f618d7b200402bd
1 file changed +223
TODO-HEALTH-DOCS.md new
+223
@@ -0,0 +1,223 @@
1 +# Documentation Review: quick-start-create-your-first-alert.md
2 +
3 +**Review Date:** January 11, 2026
4 +**File Reviewed:** `docs/alerts/creating-alerts-pages/quick-start-create-your-first-alert.md`
5 +**Reviewer:** Code Review Specialist
6 +
7 +---
8 +
9 +## Executive Summary
10 +
11 +The documentation provides a reasonable quick-start guide for creating alerts, but contains **one critical inaccuracy** regarding the `netdatacli reload-health` command output.
12 +
13 +---
14 +
15 +## Verification Results
16 +
17 +### 1. Lookup Syntax: `lookup: average -1m percentage of avail`
18 +
19 +**Status:** ✅ CORRECT
20 +
21 +**Evidence:**
22 +- Source: `src/health/health_config.c` lines 158-350
23 +- Parser supports: `METHOD AFTER [at BEFORE] [every DURATION] [OPTIONS] [of DIMENSIONS]`
24 +- The syntax `average -1m percentage of avail` breaks down as:
25 + - `average` - valid grouping method (RRDR_GROUPING_AVERAGE)
26 + - `-1m` - valid duration (60 seconds)
27 + - `percentage` - valid option (sets RRDR_OPTION_PERCENTAGE)
28 + - `of avail` - dimension specification, `avail` is a valid dimension for disk.space
29 +
30 +**Verification:** The `avail` dimension exists in disk.space charts (see `src/collectors/diskspace.plugin/plugin_diskspace.c` line 247: `rrddim_add(m->st_space, "avail", ...)`)
31 +
32 +---
33 +
34 +### 2. netdatacli reload-health Output
35 +
36 +**Status:** ❌ INCORRECT
37 +
38 +**Evidence:**
39 +- Source: `src/daemon/commands.c` lines 137-148
40 +- The `cmd_reload_health_execute` function does NOT set any message:
41 + ```c
42 + static cmd_status_t cmd_reload_health_execute(char *args, char **message)
43 + {
44 + (void)args;
45 + (void)message; // <-- message is never set!
46 + nd_log_limits_unlimited();
47 + netdata_log_info("COMMAND: Reloading HEALTH configuration.");
48 + health_plugin_reload();
49 + nd_log_limits_reset();
50 + return CMD_STATUS_SUCCESS;
51 + }
52 + ```
53 +
54 +- Actual output format (from `send_command_reply` at line 566):
55 + - Only sends exit code `X0\0` (status 0 for success)
56 + - No message is sent since `*message` is NULL
57 +
58 +- **Documented (line 87):** `Health configuration reloaded`
59 +- **Actual output:** Exit code `0` with no message
60 +
61 +**Impact:** Users expecting to see "Health configuration reloaded" will see nothing, which may cause confusion.
62 +
63 +---
64 +
65 +### 3. API Endpoint `/api/v1/alarms?all`
66 +
67 +**Status:** ✅ CORRECT
68 +
69 +**Evidence:**
70 +- Source: `src/web/api/v1/api_v1_alarms.c` lines 5-26
71 +- Function `api_v1_alarms()` at line 18:
72 + ```c
73 + int api_v1_alarms(RRDHOST *host, struct web_client *w, char *url) {
74 + int all = web_client_api_request_v1_alarms_select(url);
75 + buffer_flush(w->response.data);
76 + w->response.data->content_type = CT_APPLICATION_JSON;
77 + health_alarms2json(host, w->response.data, all);
78 + buffer_no_cacheable(w->response.data);
79 + return HTTP_RESP_OK;
80 + }
81 + ```
82 +- Parameter parsing at line 11 correctly handles `all` and `all=true`
83 +
84 +---
85 +
86 +### 4. edit-config Path: `/etc/netdata/edit-config`
87 +
88 +**Status:** ✅ CORRECT
89 +
90 +**Evidence:**
91 +- Source: `system/edit-config` (the script itself)
92 +- Script at lines 318-327:
93 + ```c
94 + main() {
95 + parse_args("${@}")
96 + check_directories()
97 + check_editor()
98 + copy("${file}")
99 + edit("${absfile}")
100 + }
101 + ```
102 +- The script correctly resolves paths to `/etc/netdata/` as the user config directory
103 +
104 +---
105 +
106 +## Scoring
107 +
108 +| Dimension | Score | Justification |
109 +|-----------|-------|---------------|
110 +| **Technical Accuracy** | 7/10 | Lookup syntax, API endpoint, and edit-config path are correct. `netdatacli reload-health` output is documented incorrectly. |
111 +| **Completeness** | 8/10 | Covers both file-based and Cloud UI workflows. Missing: actual output of reload-health command, troubleshooting for silent failures. |
112 +| **Clarity** | 9/10 | Well-structured with clear steps, code blocks, and tips. Very easy to follow. |
113 +| **Practical Value** | 7/10 | Good step-by-step instructions. Practical value reduced by the incorrect command output expectation. |
114 +| **Maintainability** | 8/10 | References to other chapters for deeper topics. Could use more inline comments about command behavior. |
115 +
116 +**Overall Score: 39/50 (78%)**
117 +
118 +---
119 +
120 +## Issues Found
121 +
122 +### Critical Issue #1: Incorrect netdatacli reload-health Output
123 +
124 +**Location:** `docs/alerts/creating-alerts-pages/quick-start-create-your-first-alert.md:87`
125 +
126 +**Current Text:**
127 +```
128 +You should see:
129 +
130 +Health configuration reloaded
131 +```
132 +
133 +**Actual Behavior:**
134 +The command returns exit code `0` with no message output to stdout. The message "Health configuration reloaded" is NOT produced by the daemon.
135 +
136 +**Recommended Fix:**
137 +Change the documentation to indicate that:
138 +1. Successful execution returns exit code 0 with no output
139 +2. Users should verify by checking API endpoint or dashboard
140 +3. Log messages go to `var/log/netdata/error.log` on failure
141 +
142 +---
143 +
144 +### Minor Issue #2: Silent Failure Not Documented
145 +
146 +**Location:** Lines 90-96
147 +
148 +**Current Text:**
149 +Note about `netdatacli` not being available and suggesting `systemctl restart netdata`
150 +
151 +**Issue:** Doesn't explain what happens if reload-health fails silently (e.g., syntax error in config).
152 +
153 +**Recommended Fix:**
154 +Add troubleshooting note about checking logs:
155 +```markdown
156 +:::tip
157 +
158 +If no output appears, check for syntax errors:
159 +```bash
160 +sudo cat /var/log/netdata/error.log | grep -i health
161 +```
162 +
163 +:::
164 +```
165 +
166 +---
167 +
168 +## Affected Code Paths
169 +
170 +### Files Verified
171 +| File | Purpose | Status |
172 +|------|---------|--------|
173 +| `src/health/health_config.c` | Lookup parser | ✅ Verified |
174 +| `src/daemon/commands.c` | reload-health command | ❌ Issue found |
175 +| `src/web/api/v1/api_v1_alarms.c` | API endpoint | ✅ Verified |
176 +| `system/edit-config` | edit-config script | ✅ Verified |
177 +| `src/collectors/diskspace.plugin/plugin_diskspace.c` | disk.space metrics | ✅ Verified |
178 +
179 +### Not Affected
180 +- Health notification system
181 +- Alert expression syntax (calc, warn, crit)
182 +- Cloud UI workflow documentation
183 +- Parent node configuration
184 +- High availability setups
185 +
186 +---
187 +
188 +## Recommendations
189 +
190 +### Immediate (P0)
191 +1. Fix the `netdatacli reload-health` output documentation - this is factually incorrect
192 +
193 +### Short-term (P1)
194 +2. Add explicit instruction to verify alert loaded via API or dashboard
195 +3. Document how to check for configuration errors
196 +
197 +### Long-term (P2)
198 +4. Consider modifying `cmd_reload_health_execute` to return a message for user feedback
199 +5. Add integration tests that verify documentation examples work
200 +
201 +---
202 +
203 +## Verification Commands Used
204 +
205 +```bash
206 +# Verify lookup parser syntax
207 +grep -n "percentage" src/health/health_config.c | head -20
208 +
209 +# Verify disk.space has 'avail' dimension
210 +grep -n "avail" src/collectors/diskspace.plugin/plugin_diskspace.c
211 +
212 +# Verify API endpoint
213 +grep -n "api_v1_alarms" src/web/api/v1/api_v1_alarms.c
214 +
215 +# Verify reload-health command
216 +grep -n "cmd_reload_health_execute" src/daemon/commands.c
217 +```
218 +
219 +---
220 +
221 +## Conclusion
222 +
223 +The documentation is generally well-written and accurate with the exception of the `netdatacli reload-health` output claim. Once corrected, this will be a solid quick-start guide for new users.
\ No newline at end of file