netdata · github-actions · Jul 17, 2026
diff --git a/docs/Exporting Metrics/Exporting reference.mdx b/docs/Exporting Metrics/Exporting reference.mdx
@@ -63,6 +63,60 @@ Netdata provides three data export modes:
 | [Prometheus Remote Write](/docs/exporting-metrics/connectors/prometheus-remote-write) | Snappy-compressed protobuf | Binary over HTTP                   |
 | [TimescaleDB](https://github.com/netdata/netdata/blob/master/src/exporting/TIMESCALE.md)                                  | JSON streams               | Time-series tables                 |
 
+## How Metric Names Are Constructed
+
+OpenTSDB and Graphite export dotted metric names. Prometheus scrape and remote write export context-based metric names with labels.
+
+### Flat-name connectors: OpenTSDB and Graphite
+
+These connectors join their name components with dots, so the chart and dimension are visible directly in the metric name:
+
+```text
+OpenTSDB: prefix.chart.dimension
+Graphite: prefix.hostname.chart.dimension
+```
+
+- **OpenTSDB** sends the host as a separate tag (`host=...`).
+- **Graphite** embeds the host in the dotted path: `prefix.hostname.chart.dimension`.
+
+Example (OpenTSDB): `netdata.system.cpu.user` with a `host=myhost` tag.
+
+OpenTSDB and Graphite preserve dots in chart and dimension names. They replace other non-alphanumeric characters with underscores.
+
+### Prometheus exports: scrape and remote write
+
+For homogeneous charts, both methods join the prefix and the chart **context** with underscores, and carry the chart, family, and dimension as labels:
+
+```text
+prefix_context{chart="...", family="...", dimension="..."}
+```
+
+- The chart **context** — the template shared by all charts of the same kind — is part of the metric name, not the individual chart ID or name.
+- `average` appends the chart units and `_average`. The scrape endpoint can omit the units with `hideunits=yes`.
+- `sum` appends `_sum` without the chart units.
+- In `as-collected` mode, incremental and percentage-over-difference counters append `_total`. For charts produced by the Prometheus collector, Netdata does not append `_total`.
+- For heterogeneous `as-collected` charts, the dimension moves into the metric name (`prefix_context_dimension`) and is omitted from the labels.
+- Netdata sanitizes the context, units, and any dimension embedded in a Prometheus metric name, so dots and other unsupported characters become underscores. Chart, family, and dimension labels retain their label values. The configured prefix is used as provided.
+
+Example (remote write): `netdata_system_cpu_percentage_average{chart="system.cpu", dimension="user", family="cpu", instance="myhost"}`.
+
+For the complete naming rules — contexts, units, suffixes, and how to preview the exact metric names via the `allmetrics` endpoint — see the [Prometheus reference](/docs/exporting-metrics/prometheus).
+
+### Quick comparison
+
+| Aspect             | OpenTSDB / Graphite                  | Prometheus scrape / remote write                                                   |
+|:-------------------|:-------------------------------------|:-----------------------------------------------------------------------------------|
+| OpenTSDB base      | `prefix.chart.dimension`             | `prefix_context`                                                                   |
+| Graphite base      | `prefix.hostname.chart.dimension`    | `prefix_context`                                                                   |
+| Dimension          | In the metric name                   | Label; in the metric name for heterogeneous `as-collected` charts                  |
+| Data-source suffix | None                                 | `_total`, `_average`, or `_sum` when applicable                                    |
+| Units in name      | No                                   | `average` only                                                                     |
+| Host               | Tag (OpenTSDB) or path (Graphite)    | `instance` label for remote write and all-host scrape; otherwise the scrape target |
+| Sanitization       | Chart/dimension preserve dots        | Context/units/embedded dimensions replace dots                                     |
+| Default prefix     | `netdata`                            | `netdata`                                                                          |
+
+Both approaches respect the `send names instead of ids` setting: when enabled, Netdata uses human-friendly chart and dimension names; when disabled, it uses the raw system IDs. See the [OpenTSDB connector options](/docs/exporting-metrics/connectors/opentsdb) for the prefix and name settings.
+
 ## Configuration Structure
 
 Your `exporting.conf` file contains these configuration blocks:
@@ -86,7 +140,7 @@ Your `exporting.conf` file contains these configuration blocks:
     enabled = yes
     destination = localhost:2003
     data source = average
-    prefix = Netdata
+    prefix = netdata
     hostname = my-name
     update every = 10
     buffer on failures = 10

diff --git a/docs/Exporting Metrics/Prometheus.mdx b/docs/Exporting Metrics/Prometheus.mdx
@@ -95,7 +95,7 @@ Netdata tracks each Prometheus server's last access time to calculate averages f
 
 Like `average` but sums values instead of averaging them.
 
-**Format:** `CONTEXT_UNITS_sum{chart="CHART",family="FAMILY",dimension="DIMENSION"}`
+**Format:** `CONTEXT_sum{chart="CHART",family="FAMILY",dimension="DIMENSION"}`
 
 To change the data source, add the `source` parameter to the URL:
 
@@ -265,11 +265,11 @@ Or append `&prefix=netdata` to the URL.
 
 ### Metric Units
 
-| Source              | Unit Behavior                             | Control                             |
-|:--------------------|:------------------------------------------|:------------------------------------|
-| `average` (default) | Adds units to names (e.g., `_KiB_persec`) | `&hideunits=yes` to hide            |
-| `as-collected`      | No units in names                         | N/A                                 |
-| All sources         | v1.12+ standardized units                 | `&oldunits=yes` for pre-v1.12 names |
+| Source              | Unit Behavior                             | Control                                                       |
+|:--------------------|:------------------------------------------|:--------------------------------------------------------------|
+| `average` (default) | Adds units to names (e.g., `_KiB_persec`) | `&hideunits=yes` to hide; `&oldunits=yes` for pre-v1.12 names |
+| `as-collected`      | No units in names                         | N/A                                                           |
+| `sum`               | No units in names                         | N/A                                                           |
 
 ### Accuracy of Average and Sum Data Sources
 

diff --git a/docs/Netdata Agent/Configuration/Organize systems metrics and alerts.mdx b/docs/Netdata Agent/Configuration/Organize systems metrics and alerts.mdx
@@ -120,6 +120,25 @@ Add your own labels to categorize systems by any criteria you need.
     sudo ./edit-config netdata.conf
     ```
 
+    :::note
+    On Windows, Netdata configuration lives at `C:\Program Files\Netdata\etc\netdata` (default install location) and there is no `sudo`. Open the bundled MSYS2 shell — for example `Win + R`, then `"C:\Program Files\Netdata\msys2.exe"` — and edit `netdata.conf`:
+
+    ```bash
+    cd /etc/netdata
+    ./edit-config netdata.conf
+    ```
+
+    `edit-config` opens the file in the `nano` editor. Add your `[host labels]` section and save it — the label naming rules, the `[host labels]` example, and the environment variable expansion in steps 2 and 3 work identically on Windows.
+
+    Reload labels without restarting the Agent, from an elevated PowerShell:
+
+    ```powershell
+    & "C:\Program Files\Netdata\usr\bin\netdatacli.exe" reload-labels
+    ```
+
+    Verify your labels at `http://HOST-IP:19999/api/v1/info`. See [editing configuration files on Windows](/docs/netdata-agent/installation/windows#editing-configuration-files) for the full MSYS2 environment workflow.
+    :::
+
 2. Add a `[host labels]` section:
 
     ```text

diff --git a/docs/Netdata Agent/Maintenance/Service Control.mdx b/docs/Netdata Agent/Maintenance/Service Control.mdx
@@ -160,5 +160,6 @@ The `netdatacli` tool is available on Windows at the Netdata installation path (
 | **Stop**          | `Stop-Service Netdata`    | Task Manager > Services > Netdata | —                           |
 | **Restart**       | `Restart-Service Netdata` | Task Manager > Services > Netdata | —                           |
 | **Reload Health** | —                         | —                                 | `netdatacli reload-health`  |
+| **Reload Labels** | —                         | —                                 | `netdatacli reload-labels`  |
 | **Shutdown**      | —                         | —                                 | `netdatacli shutdown-agent` |
 | **Ping**          | —                         | —                                 | `netdatacli ping`           |