@cryptotaxi247 / netdata / commits / 51c39e382

docs: update docs/add-advanced-api-query-example-force (#22450)

* docs: Fixed remove-node.md Method 2 to specify the command must run on the Parent node (not 'any node'), and added a Docusaurus :::note about HA setups requiring execution on each Parent Agent. Both edits are grounded in src/cli/README.md footnote [^3] and docs/observability-centralization-points/metrics-centralization-points/faq.md line 125. * docs: Restructured remove-node.md into two clearly separated sections (Section A: Standalone Nodes, Section B: Child Nodes), fixed 3 factual inaccuracies (Parent Agent requirement, removed false Stale→Offline claim, individual identifiers not labeled as bulk), updated Quick Decision Guide to ask about node topology first * docs: Replaced 'Section A' and 'Section B' headings with plain descriptive headings 'Singular or Standalone Nodes' and 'Child Nodes' * docs: Applied feedback edits to remove-node.md: fixed Stale definition to match node-states-and-transitions.md exactly, replaced remaining 'Section A/B' references with descriptive headings in Quick Decision Guide and Troubleshooting section. --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com>

nedi-app[bot] committed May 11, 2026 at 14:14 UTC 51c39e382c00ed0b13e8cf1e604f21680299dfa9
1 file changed +59 -28
docs/learn/remove-node.md
+59 -28
@@ -7,7 +7,7 @@ You can remove a node from your Space in Netdata Cloud, but the process depends
7 Before attempting to remove a node, it's important to understand what each status means:
8
9 * **Online** (Live): Node is actively connected and streaming data
10 -* **Stale**: Node is a child that stopped streaming to its parent, but the parent still has its historical data
10 +* **Stale**: Node disconnected, but a Parent connected to Netdata Cloud has its historical data
11 * **Offline** (Unreachable): Node is disconnected and no longer has data available for querying
12
13 For a complete explanation of node states, state transitions, and when nodes move between states, see [Node States and Transitions](/docs/netdata-cloud/node-states-and-transitions.md).
@@ -25,12 +25,18 @@ This is why stale nodes show "Delete is disabled" - the system prevents deletion
25
26 ## Quick Decision Guide
27
28 -**What's your node status?**
28 +**What type of node is it?**
29
30 ```
31 -🔴 Node shows "Offline" → Use Method 1 (UI Method)
32 -🟡 Node shows "Stale" → Use Method 2 (CLI Method) ← MOST COMMON ISSUE
33 -📦 Multiple nodes to remove → Use Method 3 (Bulk Operations)
31 +🔴 Standalone node (connects directly to Cloud) → Removing Standalone Nodes
32 +🟡 Child node (streams through a Parent Agent) → Removing Child Nodes
33 +```
34 +
35 +**Then, what's the node status?**
36 +
37 +```
38 +📴 Node shows "Offline" → Use the UI removal method
39 +🟡 Node shows "Stale" → Use the CLI method
40 ```
41
42 :::note
@@ -39,12 +45,20 @@ You need **Admin** role in your Space to remove nodes. The CLI method requires a
45
46 :::
47
42 -## Removal Methods
48 +## Singular or Standalone Nodes
49 +
50 +These are nodes that connect directly to Netdata Cloud without streaming through a Parent Agent.
51
52 <details>
45 -<summary><strong>Method 1: Removing Offline Nodes (UI Method)</strong></summary><br/>
53 +<summary><strong>Removing Offline Standalone Nodes (UI Method)</strong></summary><br/>
54 +
55 +**When to use**: Your standalone node shows as **Offline** status in Netdata Cloud.
56 +
57 +:::note
58 +
59 +Stale status does not apply to standalone nodes — stale specifically means a child node stopped streaming to its parent.
60
47 -**When to use**: Your node shows as **Offline** status in Netdata Cloud.
61 +:::
62
63 **Steps**:
64 1. Stop the Netdata Agent on the node you want to remove
@@ -60,48 +74,65 @@ The **Remove** option is only available in the **Space Settings** view. It will
74
75 </details>
76
77 +## Child Nodes
78 +
79 +These are nodes that stream metrics through a Parent Agent. When a child node stops streaming to its parent, it becomes **Stale**.
80 +
81 <details>
64 -<summary><strong>Method 2: Removing Stale Nodes (CLI Method)</strong></summary><br/>
82 +<summary><strong>Removing Stale Child Nodes (CLI Method)</strong></summary><br/>
83
66 -**When to use**: Your node shows as **Stale** status and UI shows "Delete is disabled".
84 +**When to use**: Your child node shows as **Stale** status and UI shows "Delete is disabled".
85
68 -**Step 1: Get the Node UUID**
86 +**Step 1: Get the Node Identifier**
87 1. In Netdata Cloud, navigate to the stale node
88 2. Click the **node information (i)** button
89 3. Click **"View node info in JSON"**
72 -4. Copy the UUID from the JSON data (it will be copied to your clipboard)
90 +4. Copy the identifier from the JSON data (node_id, machine_guid, or hostname)
91
92 **Step 2: Remove the Stale Node**
75 -Run this command on any node with Netdata Agent installed:
93 +Run this command on the **Parent Agent** that holds the stale child's data:
94
95 ```bash
78 -netdatacli remove-stale-node <UUID>
96 +netdatacli remove-stale-node <identifier>
97 ```
98
81 -Replace `<UUID>` with the node's actual identifier from Step 1.
99 +Replace `<identifier>` with one of:
100 +- `node_id` - The node's unique identifier
101 +- `machine_guid` - The machine GUID from the node info
102 +- `hostname` - The node's hostname
103
83 -**What happens next**: The command unregisters and removes the node from the cloud. The node status should change from **Stale → Offline** in Netdata Cloud, then you can remove it via the UI method if needed.
104 +:::important
105
85 -</details>
106 +This command must be run on the **Parent Agent** that holds the node's metrics data, not on any arbitrary machine with Netdata Agent installed.
107
87 -<details>
88 -<summary><strong>Method 3: Bulk Operations</strong></summary><br/>
108 +:::
109
90 -**When to use**: You need to remove multiple nodes at once.
110 +:::note
111
92 -You can use the remove-stale-node command with different identifiers:
112 +If a node is represented by multiple Parent Agents in an HA setup, this command must be executed on **each** Parent Agent.
113
94 -```bash
95 -# Using machine GUID
96 -netdatacli remove-stale-node <machine_guid>
114 +:::
115 +
116 +**What happens next**: The command marks the node as ephemeral and removes it so it is no longer available for queries, from both the Netdata Agent dashboard and Netdata Cloud. The node is fully removed — it does not transition to Offline status.
117 +
118 +</details>
119
98 -# Using hostname
99 -netdatacli remove-stale-node <hostname>
120 +<details>
121 +<summary><strong>Removing All Child Nodes from a Parent</strong></summary><br/>
122 +
123 +**When to use**: You need to remove all stale child nodes from a Parent Agent at once.
124
101 -# Remove ALL stale nodes (use with extreme caution)
125 +```bash
126 +# Remove ALL stale child nodes from this Parent (use with extreme caution)
127 netdatacli remove-stale-node ALL_NODES
128 ```
129
130 +:::caution
131 +
132 +This command affects all disconnected child nodes on the Parent Agent where it is run. Use with caution in production environments.
133 +
134 +:::
135 +
136 </details>
137
138 ## Prevention and Best Practices
@@ -128,7 +159,7 @@ To prevent removed nodes from reappearing:
159
160 ## Troubleshooting
161
131 -**"Delete is disabled"**: The node is Stale, not Offline. Use Method 2 (CLI approach).
162 +**"Delete is disabled"**: The node is Stale, not Offline. Use the CLI approach for child nodes.
163
164 **"Command not found"**: Ensure you're running `netdatacli` on a system with Netdata Agent installed.
165