@cryptotaxi247 / netdata-1 / commits / 08055a8f8

chore(docs): remove todo docs (#21614)

Ilya Mashchenko committed Jan 22, 2026 at 18:41 UTC 08055a8f875a7c725fb4640f2b3f6410f448ec23

2 files changed -277

TODO-ALERT-OVERRIDE-DOCS-FIXES.md deleted

-54

@@ -1,54 +0,0 @@

1 -# TODO: Alert Override Docs Fixes

2 -

3 -## TL;DR

4 -- Fix remaining doc accuracy issues: disk space chart ID example, disable‑trick explanation, and `edit-config` usage wording.

5 -- Ensure new docs are tracked and mapped under Alerts & Notifications in Learn.

6 -

7 -## Analysis (facts from code/docs)

8 -- Stock health config path defaults to `/usr/lib/netdata/conf.d/health.d`. Evidence: `system/edit-config:69-92`, `src/health/README.md:81`, `src/health/health.c:135-145`.

9 -- File shadowing exists: user `health.d` file/subdir with same name prevents stock file/subdir from loading. Evidence: `src/libnetdata/paths/paths.c:219-312`.

10 -- Alert application order: alarms before templates; only one alert per (chart,name) is created because RRDCALC key is `{alert,chart}` and conflicts are rejected. Evidence: `src/health/health_prototypes.c:591-616`, `src/health/rrdcalc.c:177-183`, `src/health/rrdcalc.c:349-352`, `src/health/rrdcalc.c:409-426`.

11 -- Disk space chart IDs are `disk_space.<sanitized_mount>`; context is `disk.space`. Evidence: `src/collectors/diskspace.plugin/plugin_diskspace.c:224-235`, `src/collectors/proc.plugin/proc_self_mountinfo.c:293-295`, `src/database/rrdset-index-id.c:444-445`.

12 -- The `!*` disable shortcut is handled by the health config parser (sets `ap->match.enabled = false`). Evidence: `src/health/health_config.c:506-516`.

13 -- Style guide discourages hardcoding `/etc/netdata/edit-config` in docs; recommends running `edit-config` from the config dir. Evidence: `docs/developer-and-contributor-corner/style-guide.md:303-305`.

14 -

15 -## Decisions (confirmed by Costa)

16 -1) **Paths must be stated by name and path**

17 - - Use the *config directory name* (e.g., “stock health config directory”) **and** the concrete path.

18 - - Also mention this can vary by package/prefix (e.g., `/opt/...`) and point to `edit-config` / `netdata.conf` for discovery.

19 -

20 -2) **Keep and document the `host labels: _hostname=!*` trick**

21 - - This pattern exists in stock configs today; document it clearly (with caution) rather than remove it.

22 -

23 -3) **Reload is reliable; do not imply otherwise**

24 - - Use `netdatacli reload-health` (and SIGUSR2 if needed) as the canonical method.

25 - - Avoid “restart required” language.

26 -

27 -4) **Docs are in repo; keep them and map them**

28 - - Add/track the new docs and keep the `REFERENCE.md` link.

29 - - Update `docs/.map/map.csv` so the new pages appear in Learn.

30 -

31 -5) **Learn path**

32 - - Place both new pages under `Alerts & Notifications` so they appear at `https://learn.netdata.cloud/docs/alerts-&-notifications/`.

33 - - Evidence: existing Alerts & Notifications entries are in `docs/.map/map.csv:159-169`.

34 -

35 -## Plan

36 -- Fix disk space chart ID example and update ID discovery snippet.

37 -- Clarify disable‑trick explanation (`!*` parser shortcut).

38 -- Align `edit-config` usage with style guide while keeping path names/paths.

39 -- Add new docs to git and keep map entries under Alerts & Notifications.

40 -- Re-run a focused doc scan to confirm no remaining contradictions.

41 -

42 -## Implied Decisions (if you approve recommendations)

43 -- Use flexible stock path wording with a default example.

44 -- Keep the disable trick and explain it as a parser shortcut.

45 -- Prefer reload-health; restart only as a last resort.

46 -- Add new docs to repo.

47 -

48 -## Testing Requirements

49 -- Not applicable (documentation-only).

50 -

51 -## Documentation Updates Required

52 -- `src/health/alert-configuration-ordering.md`

53 -- `src/health/overriding-stock-alerts.md`

54 -- `src/health/REFERENCE.md` (if link/path wording changes)

TODO-HEALTH-DOCS.md deleted

-223

@@ -1,223 +0,0 @@

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