[Docs] port the map from csv to yaml (#21692)
* port the map and update the readme file * remove map * schema validation and proper map * review fixes * review fixes * look for yaml map * Update docs/.map/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * review changes * lint * Update docs/.map/validate_map_schema.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * review changes * map edit * yaml map * yaml map * reshaped map, restore csv, schema and more * format * review * review fixes * comments on map --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Fotis Voutsas committed
Feb 5, 2026 at 14:12 UTC
7d64ba69d8fc6b369315407d9bdbcecac347d62e
6 files changed
+1473
-50
.github/workflows/trigger-learn-update.yml
+1
-1
@@ -6,7 +6,7 @@ on:
6
- master
7
paths:
8
- "**.mdx?"
9
- - "docs/.map/map.csv"
9
+ - "docs/.map/map.yaml"
10
- "packaging/installer/kickstart.sh"
11
concurrency:
12
group: learn-trigger-${{ github.ref }}
docs/.map/README.md
+56
-27
@@ -11,32 +11,59 @@ Publishing documentation to [Learn](https://github.com/netdata/learn) involves a
11
12
### Quick Checklist
13
14
-| Step | Action | Output |
15
-|-------|-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
16
-| **1** | Edit `map.csv` alongside your doc changes. Fill in all 4 columns (description can be left empty) correctly. | Docs mapped with proper sidebar labels, paths, and edit links. |
17
-| **2** | Test locally with the `ingest.py` script. Optionally run a full local Learn deployment. | Confirms no broken links or build errors. |
18
-| **3** | Merge the Docs PR (requires approval). | Docs + `map.csv` merged into the repo. |
19
-| **4** | Inspect the automatic Learn ingest PR. Check files + deploy preview. | Verified preview of Learn with changes. |
20
-| **5** | Merge the Learn ingest PR. | Docs officially live on Learn. |
21
-
22
-### 1. Edit `map.csv`
23
-
24
-All docs must be mapped in the [map.csv](https://github.com/netdata/netdata/blob/master/docs/.map/map.csv) file. Each row has five columns:
25
-
26
-| Column | Purpose | Notes |
27
-|-----------------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
28
-| **custom\_edit\_url** | Full GitHub **Edit** link for the file. Used for the "Edit this page" button. | Must use the full link (supports repos beyond `netdata/netdata`). |
29
-| **sidebar\_label** | The label shown in the sidebar. | To make a category: the **overview** page’s `sidebar_label` **must match** `learn_rel_path` (lowercase). <br>👉 Every folder must have an overview page. |
30
-| **learn\_status** | `Published` or `Unpublished`. | If `Unpublished`, see [Unpublishing Files](#unpublishing-files). |
31
-| **learn\_rel\_path** | The location path on Learn. | Use **uppercase letters** and **spaces**. Example: `Netdata Agent/Installation/Linux`. <br>👉 Every level requires an overview page. |
32
-| **keywords** | The keywords for the file. Double quoted, comma-separated like `"first keyword,second"` | Keywords are searchable by our search implementation. For a keyword `Super keyword`, `super` will bring it up, as well as `keyword`, due to the nature of our search. Also, for a `testing` keyword, a search for `test` will also bring it up. |
33
-| **description** | Legacy metadata description. | Rarely used today. |
34
-
35
-Example row in `map.csv`:
36
-
37
-```csv
38
-custom_edit_url,sidebar_label,learn_status,learn_rel_path,keywords,description
39
-https://github.com/netdata/netdata/edit/master/docs/installation/linux.md,Linux,Published,"Netdata Agent/Installation/Linux","install,linux","How to install Netdata Agent on Linux"
14
+| Step | Action | Output |
15
+|-------|-----------------------------------------------------------------------------------------|----------------------------------------------------------------|
16
+| **1** | Edit `map.yaml` alongside your doc changes. Update nodes and ordering as needed. | Docs mapped with proper sidebar labels, paths, and edit links. |
17
+| **2** | Test locally with the `ingest.py` script. Optionally run a full local Learn deployment. | Confirms no broken links or build errors. |
18
+| **3** | Merge the Docs PR (requires approval). | Docs + `map.yaml` merged into the repo. |
19
+| **4** | Inspect the automatic Learn ingest PR. Check files + deploy preview. | Verified preview of Learn with changes. |
20
+| **5** | Merge the Learn ingest PR. | Docs officially live on Learn. |
21
+
22
+### 1. Edit `map.yaml`
23
+
24
+All docs must be mapped in the [map.yaml](https://github.com/netdata/netdata/blob/master/docs/.map/map.yaml) file. The file is an ordered navigation tree under the top-level `sidebar:` key.
25
+
26
+Each node is either:
27
+
28
+- A **doc node** (with a `meta` object)
29
+- A **category node** (with `meta` + `items`)
30
+- An **integration placeholder** (`type: integration_placeholder`)
31
+
32
+#### `meta` fields
33
+
34
+| Field | Purpose | Notes |
35
+|-----------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
36
+| **label** | The label shown in the sidebar. | For category overview pages, this should match the sidebar position. Categories are defined by having `items`. |
37
+| **path** | Single path segment override (optional). | Used when the document's Learn path segment differs from the tree structure. Example: `OpenTelemetry` (not a full path). If omitted, the path is derived from the tree hierarchy. |
38
+| **edit_url** | Full GitHub **Edit** link for the file. Used for the "Edit this page" button. | Must use the full link (supports repos beyond `netdata/netdata`). Can be omitted only for nodes with `integration_placeholder` children (the integrations themselves will have edit URLs). |
39
+| **keywords** | List of keywords for search. | Example: `["install", "linux"]` |
40
+| **description** | Legacy metadata description. | Rarely used today. |
41
+
42
+#### Path Reconstruction
43
+
44
+The full Learn path for each document is automatically reconstructed by walking the tree hierarchy and concatenating parent labels. The `path` field in `meta` is only needed when a document's path segment differs from its tree position.
45
+
46
+For example, a document appearing under "Collecting Metrics" in the sidebar with `path: OpenTelemetry` will have Learn path `OpenTelemetry` instead of `Collecting Metrics/OpenTelemetry Metrics`.
47
+
48
+#### Integration placeholder node
49
+
50
+```yaml
51
+- type: integration_placeholder
52
+ integration_kind: collectors
53
+```
54
+
55
+Placeholders are positional: the ingest pipeline replaces them in-place with generated integration entries while preserving list order.
56
+
57
+#### Example node
58
+
59
+```yaml
60
+- meta:
61
+ label: "Linux"
62
+ edit_url: "https://github.com/netdata/netdata/edit/master/docs/installation/linux.md"
63
+ description: "How to install Netdata Agent on Linux"
64
+ keywords:
65
+ - "install"
66
+ - "linux"
67
```
68
69
### 2. Test the Changes
@@ -46,15 +73,17 @@ Before merging, **always test the map file**.
73
1. Clone [Learn](https://github.com/netdata/learn) locally.
74
2. Prepare environment and dependencies (see [ingest instructions](https://github.com/netdata/learn#ingest-and-process-documentation-files)).
75
3. Run the ingest command:
76
+
77
```bash
78
python3 ingest/ingest.py --repos OWNEROFREPO/netdata:YOURBRANCH
79
```
80
+
81
4. Inspect the ingested changes.
82
5. (Optional, advanced) [Deploy Learn](https://github.com/netdata/learn#local-deploy-of-learn) locally to confirm it builds correctly.
83
84
### 3. Merge the Docs PR
85
57
-- Submit your PR with the updated docs **and** `map.csv`.
86
+- Submit your PR with the updated docs **and** `map.yaml`.
87
- Get at least one approval.
88
- **Reviewers expect you to have tested already**. Don’t rely on them to test. Please also mention it if you have done testing, so it is clear.
89
docs/.map/map.csv
+2
-22
@@ -88,7 +88,6 @@ https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/README.md,Netd
88
https://github.com/netdata/netdata/edit/master/src/claim/README.md,Connect Agent,Published,Netdata Cloud,,
89
https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md,Spaces and Rooms,Published,Netdata Cloud/Spaces and Rooms,,
90
https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/node-rule-based-room-assignment.md,Node Rule-Based Room Assignment,Published,Netdata Cloud/Spaces and Rooms,,
91
-https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/versions.md,Versions,Unpublished,Netdata Cloud/Versions,,
91
https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/README.md,Authentication & Authorization,Published,Netdata Cloud/Authentication & Authorization,,
92
https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md,Enterprise SSO Authentication,Published,Netdata Cloud/Authentication & Authorization,,
93
authentication_integrations,,,,,
@@ -122,13 +121,9 @@ https://github.com/netdata/netdata/edit/master/src/crates/netdata-otel/otel-plug
121
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/README.md,Metrics Centralization Points,Published,Netdata Parents/Metrics Centralization Points,,
122
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/configuration.md,Configuring Metrics Centralization Points,Published,Netdata Parents/Metrics Centralization Points,,
123
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/sizing-netdata-parents.md,Sizing Netdata Parents,Published,Netdata Parents/Metrics Centralization Points,,
125
-,Optimizing Netdata Children,Unpublished,Netdata Parents/Metrics Centralization Points,,
124
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/clustering-and-high-availability-of-netdata-parents.md,Clustering and High Availability of Netdata Parents,Published,Netdata Parents/Metrics Centralization Points,,
125
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/replication-of-past-samples.md,Replication of Past Samples,Published,Netdata Parents/Metrics Centralization Points,,
126
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/faq.md,FAQ on Metrics Centralization Points,Published,Netdata Parents/Metrics Centralization Points,,
129
-https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/system-metrics.md,System metrics,Unpublished,Collecting Metrics,,"Netdata collects thousands of metrics from physical and virtual systems, IoT/edge devices, and containers with zero configuration."
130
-https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/application-metrics.md,Application metrics,Unpublished,Collecting Metrics,,"Monitor and troubleshoot every application on your infrastructure with per-second metrics, zero configuration, and meaningful charts."
131
-https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/container-metrics.md,Container metrics,Unpublished,Collecting Metrics,,Use Netdata to collect per-second utilization and application-level metrics from Linux/Docker containers and Kubernetes clusters.
127
https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/snmp/profile-format.md,SNMP Profile Format,Published,Collecting Metrics,,Learn how Netdata’s SNMP collector uses profiles.
128
collectors_integrations,,,,,
129
,,,,,
@@ -205,8 +200,6 @@ https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/g
200
https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/codex-cli.md,OpenAI Codex CLI,Published,Netdata AI/MCP/MCP Clients,,
201
https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/crush.md,Crush,Published,Netdata AI/MCP/MCP Clients,,
202
https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/opencode.md,OpenCode,Published,Netdata AI/MCP/MCP Clients,,
208
-https://github.com/netdata/netdata/edit/master/docs/netdata-assistant.md,AI powered troubleshooting assistant,Unpublished,AI and Machine Learning,,
209
-https://github.com/netdata/netdata/edit/master/src/ml/README.md,ML models and anomaly detection,Unpublished,AI and Machine Learning,,This is an in-depth look at how Netdata uses ML to detect anomalies.
203
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/README.md,Dashboards and Charts,Published,Dashboards and Charts,,
204
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/home-tab.md,Tabs,Published,Dashboards and Charts/Tabs,,"With Netdata Cloud's War Rooms, you can see real-time metrics, from any number of nodes in your infrastructure, in composite charts."
205
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/alerts-tab.md,Alerts,Published,Dashboards and Charts/Tabs,,
@@ -225,9 +218,6 @@ https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/expand
218
https://github.com/netdata/netdata/edit/master/docs/NIDL-Framework.md,NIDL Framework,Published,Dashboards and Charts,,
219
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/node-filter.md,Node Filter,Published,Dashboards and Charts,,
220
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/visualization-date-and-time-controls.md,Time Controls,Published,Dashboards and Charts,,
228
-https://github.com/netdata/netdata/edit/master/src/web/gui/confluence/README.md,Atlassian Confluence dashboards,Unpublished,Dashboards and Charts,,
229
-https://github.com/netdata/netdata/edit/master/src/web/gui/README.md,Legacy Agent Dashboard,Unpublished,Dashboards and Charts,,"The local Netdata Agent dashboard is the heart of health monitoring and performance troubleshooting, with hundreds of real-time charts."
230
-https://github.com/netdata/netdata/edit/master/docs/category-overview-pages/monitor-your-infrastructure.md,Monitor your Infrastructure,Unpublished,Dashboards and Charts,,
221
,,,,,
222
,,,,,
223
https://github.com/netdata/netdata/edit/master/docs/security-and-privacy-design/README.md,Security and Privacy Design,Published,Security and Privacy Design,,
@@ -243,7 +233,6 @@ https://github.com/netdata/netdata/edit/master/docs/security-and-privacy-design/
233
,,,,,
234
,,,,,
235
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/README.md,Developer and Contributor Corner,Published,Developer and Contributor Corner,,
246
-https://github.com/netdata/netdata/edit/master/docs/category-overview-pages/netdata-apis.md,REST API,Unpublished,Developer and Contributor Corner/REST API,,
236
https://github.com/netdata/netdata/edit/master/src/web/api/README.md,REST API,Published,Developer and Contributor Corner/REST API,,
237
https://github.com/netdata/netdata/edit/master/src/web/api/queries/README.md,Queries,Published,Developer and Contributor Corner/REST API/Queries,,
238
https://github.com/netdata/netdata/edit/master/src/web/api/queries/average/README.md,Average or Mean,Published,Developer and Contributor Corner/REST API/Queries,,
@@ -271,18 +260,16 @@ https://github.com/netdata/netdata/edit/master/src/database/engine/README.md,Dat
260
https://github.com/netdata/.github/edit/main/CONTRIBUTING.md,Contributing,Published,Developer and Contributor Corner,,
261
https://github.com/netdata/.github/edit/main/CODE_OF_CONDUCT.md,Community code of conduct,Published,Developer and Contributor Corner,,
262
https://github.com/netdata/.github/edit/main/SECURITY.md,Security Policy,Published,Developer and Contributor Corner,,The Netdata team maintains and adheres to a formal process any time a member of the community reports a security vulnerability.
274
-https://github.com/netdata/netdata/edit/master/src/plugins.d/README.md,External plugins,Published,Developer and Contributor Corner/External Plugins,,
263
+https://github.com/netdata/netdata/edit/master/src/plugins.d/README.md,External Plugins,Published,Developer and Contributor Corner/External Plugins,,
264
https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/README.md,go.d.plugin,Published,Developer and Contributor Corner/External Plugins/go.d.plugin,,"go.d.plugin is an external plugin for Netdata, responsible for running individual data collectors written in Go."
265
https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/docs/how-to-write-a-module.md,How to write a Netdata collector in Go,Published,Developer and Contributor Corner/External Plugins/go.d.plugin,,"This guide will walk you through the technical implementation of writing a new Netdata collector in Golang, with tips on interfaces, structure, configuration files, and more."
266
https://github.com/netdata/netdata/edit/master/src/collectors/python.d.plugin/README.md,python.d.plugin,Published,Developer and Contributor Corner/External Plugins/python.d.plugin,,
278
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/python-collector.md,Develop a custom data collector in Python,Unpublished,Developer and Contributor Corner/External Plugins/python.d.plugin,,"Learn how write a custom data collector in Python, which you'll use to collect metrics from and monitor any application that isn't supported out of the box."
267
https://github.com/netdata/netdata/edit/master/src/collectors/charts.d.plugin/README.md,charts.d.plugin,Published,Developer and Contributor Corner/External Plugins,,
268
https://github.com/netdata/netdata/edit/master/src/collectors/profile.plugin/README.md,profile.plugin,Published,Developer and Contributor Corner/External Plugins,,
269
https://github.com/netdata/netdata/edit/master/src/plugins.d/FUNCTION_UI_REFERENCE.md,Functions v3 Protocol reference,Published,Developer and Contributor Corner/External Plugins,,
270
https://github.com/netdata/netdata/edit/master/src/plugins.d/FUNCTION_UI_DEVELOPER_GUIDE.md,Functions developer guide,Published,Developer and Contributor Corner/External Plugins,,
271
https://github.com/netdata/netdata/edit/master/docs/guidelines.md,Contribute to the documentation,Published,Developer and Contributor Corner/Contribute to the documentation,,
272
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/style-guide.md,Netdata style guide,Published,Developer and Contributor Corner/Contribute to the documentation,,"The Netdata style guide establishes editorial guidelines for all of Netdata's writing, including documentation, blog posts, in-product UX copy, and more."
285
-https://github.com/netdata/netdata/edit/master/src/web/README.md,Web,Unpublished,Developer and Contributor Corner,,"Every Netdata Agent comes bundled with hundreds of interactive, customizable charts designed by monitoring and troubleshooting experts."
273
https://github.com/netdata/netdata/edit/master/docs/glossary.md,Glossary,Published,Developer and Contributor Corner,,
274
https://github.com/netdata/netdata/edit/master/src/libnetdata/README.md,libnetdata,Published,Developer and Contributor Corner/libnetdata,,
275
https://github.com/netdata/netdata/edit/master/src/libnetdata/adaptive_resortable_list/README.md,Adaptive re-sortable list (ARL),Published,Developer and Contributor Corner/libnetdata,,
@@ -315,21 +302,14 @@ https://github.com/netdata/netdata/edit/master/REDISTRIBUTED.md,Redistributed So
302
https://github.com/netdata/netdata/edit/master/tests/health_mgmtapi/README.md,Health command API tester,Published,Developer and Contributor Corner,,
303
https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/import-export-print-snapshot.md,"Import, export, and print a snapshot",Published,Developer and Contributor Corner,,"Snapshots can be incredibly useful for diagnosing anomalies after they've already happened, and are interoperable with any other node running Netdata."
304
https://github.com/netdata/netdata/edit/master/src/web/gui/custom/README.md,Build a custom Dashboard HTML page,Published,Developer and Contributor Corner,,Build custom dashboards with key metrics from one or more nodes running the Netdata Agent and host them anywhere.
318
-https://github.com/netdata/netdata/edit/master/docs/netdata-for-IoT.md,Netdata for IoT,Unpublished,Developer and Contributor Corner,,
305
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md,Monitor Nginx or Apache web server log files with Netdata,Published,Developer and Contributor Corner,,
306
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/collect-unbound-metrics.md,Monitor Unbound DNS servers with Netdata,Published,Developer and Contributor Corner,,
321
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/monitor-cockroachdb.md,Monitor CockroachDB metrics with Netdata,Unpublished,Developer and Contributor Corner,,
307
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md,Monitor a Hadoop cluster with Netdata,Published,Developer and Contributor Corner,,
323
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/kubernetes-k8s-netdata.md,Kubernetes monitoring with Netdata: Overview and visualizations,Unpublished,Developer and Contributor Corner,,Learn how to navigate Netdata's Kubernetes monitoring features for visualizing the health and performance of a Kubernetes cluster with per-second granularity.
324
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/lamp-stack.md,"LAMP stack monitoring (Linux, Apache, MySQL, PHP) with Netdata",Unpublished,Developer and Contributor Corner,,"Set up robust LAMP stack monitoring (Linux, Apache, MySQL, PHP) in just a few minutes using a free, open-source monitoring tool that collects metrics every second."
325
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/pi-hole-raspberry-pi.md,Monitor Pi-hole (and a Raspberry Pi) with Netdata,Unpublished,Developer and Contributor Corner,,"Monitor Pi-hole metrics, plus Raspberry Pi system metrics, in minutes and completely for free with Netdata's open-source monitoring agent."
326
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/raspberry-pi-anomaly-detection.md,Unsupervised anomaly detection for Raspberry Pi monitoring,Unpublished,Developer and Contributor Corner,,Use a low-overhead machine learning algorithm and an open-source monitoring tool to detect anomalous metrics on a Raspberry Pi.
308
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md,"Monitor, troubleshoot, and debug applications with eBPF metrics",Published,Developer and Contributor Corner,,"Use Netdata's built-in eBPF metrics collector to monitor, troubleshoot, and debug your custom application using low-level kernel feedback."
328
-https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/process.md,Monitor any process in real-time with Netdata,Unpublished,Developer and Contributor Corner,,"Tap into Netdata's powerful collectors, with per-second utilization metrics for every process, to troubleshoot faster and make data-informed decisions."
309
https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md,Build the Netdata Agent Yourself,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,
310
https://github.com/netdata/netdata/edit/master/packaging/maintainers/README.md,Package Maintainers,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,
311
https://github.com/netdata/netdata/edit/master/packaging/installer/methods/source.md,Compile from source code,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,Package maintainers and power users may be interested in manually building Netdata from source without using any of our installation scripts.
312
https://github.com/netdata/netdata/edit/master/build_external/README.md,External build-system,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,
313
https://github.com/netdata/netdata/edit/master/packaging/building-native-packages-locally.md,How to build native (DEB/RPM) packages locally for testing,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,Instructions for developers who need to build native packages locally for testing.
314
https://github.com/netdata/netdata/edit/master/contrib/README.md,Netdata contrib,Published,Developer and Contributor Corner/Build the Netdata Agent Yourself,,
335
-https://github.com/netdata/netdata/edit/master/packaging/installer/methods/manual.md,Install the Netdata Agent from a Git checkout,Published,Developer and Contributor Corner,,"Use the Netdata Agent source code from GitHub, plus helper scripts to set up your system, to install Netdata without packages or binaries."
315
+https://github.com/netdata/netdata/edit/master/packaging/installer/methods/manual.md,Install the Netdata Agent from a Git checkout,Published,Developer and Contributor Corner,,"Use the Netdata Agent source code from GitHub, plus helper scripts to set up your system, to install Netdata without packages or binaries."
\ No newline at end of file
docs/.map/map.schema.json
new
+116
@@ -0,0 +1,116 @@
1
+{
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "https://netdata.cloud/schemas/map.schema.json",
4
+ "title": "Netdata Documentation Map",
5
+ "description": "Schema for validating Netdata documentation map.yaml structure",
6
+ "type": "object",
7
+ "required": [
8
+ "sidebar"
9
+ ],
10
+ "properties": {
11
+ "sidebar": {
12
+ "type": "array",
13
+ "description": "Top-level sidebar navigation structure",
14
+ "items": {
15
+ "$ref": "#/definitions/node"
16
+ }
17
+ }
18
+ },
19
+ "definitions": {
20
+ "node": {
21
+ "oneOf": [
22
+ {
23
+ "$ref": "#/definitions/sidebarNode"
24
+ },
25
+ {
26
+ "$ref": "#/definitions/integrationPlaceholder"
27
+ }
28
+ ]
29
+ },
30
+ "sidebarNode": {
31
+ "type": "object",
32
+ "description": "A sidebar node representing a document or category",
33
+ "required": [
34
+ "meta"
35
+ ],
36
+ "additionalProperties": false,
37
+ "properties": {
38
+ "meta": {
39
+ "$ref": "#/definitions/nodeMeta"
40
+ },
41
+ "items": {
42
+ "type": "array",
43
+ "description": "Child nodes (documents, categories, or integration placeholders)",
44
+ "items": {
45
+ "$ref": "#/definitions/node"
46
+ }
47
+ }
48
+ }
49
+ },
50
+ "nodeMeta": {
51
+ "type": "object",
52
+ "description": "Metadata for a sidebar node",
53
+ "required": [
54
+ "label"
55
+ ],
56
+ "additionalProperties": false,
57
+ "properties": {
58
+ "label": {
59
+ "type": "string",
60
+ "minLength": 1,
61
+ "description": "Display label for the sidebar item"
62
+ },
63
+ "path": {
64
+ "type": "string",
65
+ "minLength": 1,
66
+ "description": "Path segment for this node (only if the page should not be a category overview page in this section). Single segment like 'Installation', not full path."
67
+ },
68
+ "edit_url": {
69
+ "type": "string",
70
+ "pattern": "^https://github\\.com/[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+/edit/[a-zA-Z0-9_.-]+/.+\\.(md|mdx)$",
71
+ "description": "GitHub edit URL pointing to the source markdown file"
72
+ },
73
+ "description": {
74
+ "type": "string",
75
+ "description": "Optional description/summary of the document"
76
+ },
77
+ "keywords": {
78
+ "type": "array",
79
+ "description": "Optional SEO keywords",
80
+ "items": {
81
+ "type": "string"
82
+ }
83
+ }
84
+ }
85
+ },
86
+ "integrationPlaceholder": {
87
+ "type": "object",
88
+ "description": "Placeholder for dynamically generated integration pages",
89
+ "required": [
90
+ "type",
91
+ "integration_kind"
92
+ ],
93
+ "additionalProperties": false,
94
+ "properties": {
95
+ "type": {
96
+ "type": "string",
97
+ "const": "integration_placeholder",
98
+ "description": "Identifies this as an integration placeholder"
99
+ },
100
+ "integration_kind": {
101
+ "type": "string",
102
+ "enum": [
103
+ "collectors",
104
+ "exporters",
105
+ "notifications",
106
+ "authentication",
107
+ "logs",
108
+ "agent_notifications",
109
+ "cloud_notifications"
110
+ ],
111
+ "description": "Type of integrations to be inserted at this location"
112
+ }
113
+ }
114
+ }
115
+ }
116
+}
\ No newline at end of file
docs/.map/map.yaml
new
+1016
@@ -0,0 +1,1016 @@
1
+sidebar:
2
+ # Welcome to Netdata
3
+ - meta:
4
+ label: Welcome to Netdata
5
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/welcome-to-netdata.md
6
+ items:
7
+ - meta:
8
+ label: Enterprise Evaluation Guide
9
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-enterprise-evaluation-corrected.md
10
+ keywords:
11
+ - real-time observability
12
+ - infrastructure monitoring
13
+ - meta:
14
+ label: Real-time Monitoring
15
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/realtime-monitoring.md
16
+ - meta:
17
+ label: Scalability
18
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/scalability.md
19
+ - meta:
20
+ label: Monitor Anything
21
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/COLLECTORS.md
22
+ description: Netdata gathers real-time metrics from hundreds of data sources using collectors. Most require zero configuration and are pre-configured out of the box.
23
+ - meta:
24
+ label: Fleet Deployment and Configuration Management
25
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/fleet-configuration-management.md
26
+ - meta:
27
+ label: Reporting
28
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/reporting.md
29
+ description: Extract infrastructure insights for stakeholders and BI tools using AI Insights, AI assistants (MCP), Grafana, or data export to Power BI, Tableau, and other analytics platforms.
30
+ keywords:
31
+ - power bi
32
+ - tableau
33
+ - looker
34
+ - qlik
35
+ - reporting
36
+ - business intelligence
37
+ - bi
38
+ - grafana
39
+ - ai insights
40
+ - mcp
41
+ - executive reports
42
+ - board reporting
43
+ - data export
44
+ # Getting Started
45
+ - meta:
46
+ label: Getting Started
47
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/getting-started-netdata/guide.md
48
+ # Live Demo
49
+ - meta:
50
+ label: Live Demo
51
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/Demo-Sites.md
52
+ # Netdata Agent
53
+ - meta:
54
+ label: Netdata Agent
55
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/deployment-guides/standalone-deployment.md
56
+ items:
57
+ - meta:
58
+ label: Versions & Platforms
59
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/versions-and-platforms.md
60
+ description: Present all the supported platform in the Netdata solution
61
+ - meta:
62
+ label: Quickstart Deployment
63
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/deployment-guides/README.md
64
+ - meta:
65
+ label: Installation
66
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/README.md
67
+ items:
68
+ - meta:
69
+ label: Linux
70
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kickstart.md
71
+ description: The kickstart.sh script installs Netdata from source, including all dependencies required to connect to Netdata Cloud, with a single command.
72
+ items:
73
+ - meta:
74
+ label: Native Linux Distribution packages
75
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/packages.md
76
+ description: Instructions for how to install Netdata using native DEB or RPM packages.
77
+ - meta:
78
+ label: Static binary Linux Packages
79
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/makeself/README.md
80
+ description: Users can build the static 64-bit binary package that we ship with every release of the open-source Netdata Agent for debugging or specialize purposes.
81
+ - meta:
82
+ label: Switch Install Types and Release Channels
83
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/learn/switching-install-types.md
84
+ - meta:
85
+ label: Offline systems
86
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/offline.md
87
+ description: Install the Netdata Agent on offline/air gapped systems to benefit from real-time, per-second monitoring without connecting to the internet.
88
+ - meta:
89
+ label: Windows
90
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/windows/WINDOWS_INSTALLER.md
91
+ items:
92
+ - meta:
93
+ label: Switching Install Types and Release Channels
94
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/install/windows-release-channels.md
95
+ description: Guide to choosing and switching between different Netdata Windows installation methods and release channels
96
+ - meta:
97
+ label: Docker
98
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/docker/README.md
99
+ - meta:
100
+ label: Kubernetes
101
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kubernetes.md
102
+ description: Deploy Netdata to monitor a Kubernetes cluster to monitor the health, performance, resource utilization, and application metrics of a Kubernetes cluster in real time.
103
+ - meta:
104
+ label: Kubernetes Helm chart reference
105
+ edit_url: https://github.com/netdata/helmchart/edit/master/charts/netdata/README.md
106
+ - meta:
107
+ label: macOS
108
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/macos.md
109
+ - meta:
110
+ label: FreeBSD
111
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/freebsd.md
112
+ description: Install Netdata on FreeBSD to monitor the health and performance of bare metal or VMs with thousands of real-time, per-second metrics.
113
+ - meta:
114
+ label: pfSense
115
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/pfsense.md
116
+ description: Install Netdata on pfSense to monitor the health and performance of firewalls with thousands of real-time, per-second metrics.
117
+ - meta:
118
+ label: Synology
119
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/synology.md
120
+ description: The Netdata Agent can be installed on AMD64-compatible NAS systems using the 64-bit pre-compiled static binary.
121
+ - meta:
122
+ label: Ansible
123
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/ansible.md
124
+ description: Deploy an infrastructure monitoring solution in minutes with the Netdata Agent and Ansible. Use and customize a simple playbook for monitoring as code.
125
+ - meta:
126
+ label: AWS
127
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/aws.md
128
+ description: The Netdata Agent runs on all popular cloud providers, but often requires additional steps and configuration for full functionality.
129
+ - meta:
130
+ label: Azure
131
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/azure.md
132
+ description: The Netdata Agent runs on all popular cloud providers, but often requires additional steps and configuration for full functionality.
133
+ - meta:
134
+ label: GCP
135
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/gcp.md
136
+ description: The Netdata Agent runs on all popular cloud providers, but often requires additional steps and configuration for full functionality.
137
+ - meta:
138
+ label: Maintenance
139
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/category-overview-pages/maintenance-operations-on-netdata-agents.md
140
+ items:
141
+ - meta:
142
+ label: Service Control
143
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/start-stop-restart.md
144
+ description: Manage the Netdata Agent daemon, load configuration changes, and troubleshoot stuck processes on systemd and non-systemd nodes.
145
+ - meta:
146
+ label: Update
147
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md
148
+ description: If you opted out of automatic updates, you need to update your Netdata Agent to the latest nightly or stable version.
149
+ - meta:
150
+ label: Reinstall
151
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/REINSTALL.md
152
+ description: Troubleshooting installation issues or force an update of the Netdata Agent by reinstalling it using the same method you used during installation.
153
+ - meta:
154
+ label: Uninstall
155
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UNINSTALL.md
156
+ description: If you are no longer interested in using the Netdata Agent, use the self-contained uninstaller to remove all traces of binaries and configuration files.
157
+ - meta:
158
+ label: Backup and restore an Agent
159
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/backup-and-restore-an-agent.md
160
+ description: What actions you need to do to backup and Agent and restore it.
161
+ - meta:
162
+ label: Resource Utilization
163
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/sizing-netdata-agents/README.md
164
+ items:
165
+ - meta:
166
+ label: CPU
167
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/sizing-netdata-agents/cpu-requirements.md
168
+ - meta:
169
+ label: RAM
170
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/sizing-netdata-agents/ram-requirements.md
171
+ - meta:
172
+ label: Bandwidth
173
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/sizing-netdata-agents/bandwidth-requirements.md
174
+ - meta:
175
+ label: Disk & Retention
176
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/sizing-netdata-agents/disk-requirements-and-retention.md
177
+ - meta:
178
+ label: Configuration
179
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/README.md
180
+ description: Netdata is zero-configuration for most users, but complex infrastructures may require you to tweak some of the Agent's granular settings.
181
+ items:
182
+ - meta:
183
+ label: Dynamic Configuration Manager
184
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/dynamic-configuration.md
185
+ - meta:
186
+ label: Daemon
187
+ edit_url: https://github.com/netdata/netdata/edit/master/src/daemon/config/README.md
188
+ description: The Netdata Agent's daemon is installed preconfigured to collect thousands of metrics every second, but is highly configurable for real-world workloads.
189
+ - meta:
190
+ label: Database
191
+ edit_url: https://github.com/netdata/netdata/edit/master/src/database/CONFIGURATION.md
192
+ description: With a single configuration change, the Netdata Agent can store days, weeks, or months of metrics at its famous per-second granularity.
193
+ - meta:
194
+ label: Registry
195
+ edit_url: https://github.com/netdata/netdata/edit/master/src/registry/CONFIGURATION.md
196
+ description: Netdata utilizes a central registry of machines/person GUIDs, URLs, and opt-in account information to provide unified cross-server dashboards.
197
+ - meta:
198
+ label: Securing Agents
199
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/securing-netdata-agents.md
200
+ description: Your data and systems are safe with Netdata, but we recommend a few easy ways to improve the security of your infrastructure.
201
+ items:
202
+ - meta:
203
+ label: Web Server Reference
204
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/server/README.md
205
+ description: The Netdata Agent's local static-threaded web server serves dashboards and real-time visualizations with security and DDoS protection.
206
+ - meta:
207
+ label: Running the Agent behind a reverse proxy
208
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md
209
+ items:
210
+ - meta:
211
+ label: Nginx
212
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md
213
+ - meta:
214
+ label: HAProxy
215
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md
216
+ - meta:
217
+ label: Apache
218
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md
219
+ - meta:
220
+ label: Lighttpd v1.4.x
221
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md
222
+ - meta:
223
+ label: Caddy
224
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md
225
+ - meta:
226
+ label: H2O
227
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md
228
+ - meta:
229
+ label: Performance Optimization
230
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/optimize-the-netdata-agents-performance.md
231
+ description: While the Netdata Agent is designed to monitor a system with only 1% CPU, you can optimize its performance for low-resource systems.
232
+ - meta:
233
+ label: Organize systems, metrics, and alerts
234
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts.md
235
+ - meta:
236
+ label: Using custom CA certificates with Netdata
237
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/using-custom-ca-certificates-with-netdata.md
238
+ - meta:
239
+ label: Daemon
240
+ edit_url: https://github.com/netdata/netdata/edit/master/src/daemon/README.md
241
+ - meta:
242
+ label: Database
243
+ edit_url: https://github.com/netdata/netdata/edit/master/src/database/README.md
244
+ - meta:
245
+ label: Logging
246
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/log/README.md
247
+ - meta:
248
+ label: Registry
249
+ edit_url: https://github.com/netdata/netdata/edit/master/src/registry/README.md
250
+ description: Netdata utilizes a central registry of machines/person GUIDs, URLs, and opt-in account information to provide unified cross-server dashboards.
251
+ - meta:
252
+ label: Agent CLI
253
+ edit_url: https://github.com/netdata/netdata/edit/master/src/cli/README.md
254
+ description: The Netdata Agent includes a command-line experience for reloading health configuration, reopening log files, halting the daemon, and more.
255
+ - meta:
256
+ label: Node Identities
257
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/learn/node-identities.md
258
+ description: Understanding how Netdata identifies nodes across Agents Parents and Cloud
259
+ keywords:
260
+ - guid
261
+ - machine guid
262
+ - node id
263
+ - claimed id
264
+ - identity
265
+ - meta:
266
+ label: VM Templates
267
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/learn/vm-templates.md
268
+ description: Prepare VM templates so each clone gets a unique Netdata identity
269
+ keywords:
270
+ - vm
271
+ - template
272
+ - clone
273
+ - kvm
274
+ - proxmox
275
+ - vagrant
276
+ - terraform
277
+ - meta:
278
+ label: Anonymous telemetry events
279
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-agent/configuration/anonymous-telemetry-events.md
280
+ # Netdata Parents
281
+ - meta:
282
+ label: Netdata Parents
283
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/deployment-guides/deployment-with-centralization-points.md
284
+ items:
285
+ - meta:
286
+ label: Parent Configuration Best Practices
287
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/best-practices.md
288
+ - meta:
289
+ label: Parent-Child Configuration Reference
290
+ edit_url: https://github.com/netdata/netdata/edit/master/src/streaming/README.md
291
+ - meta:
292
+ label: Configuration Examples
293
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/deployment-guides/deployment-strategies.md
294
+ - meta:
295
+ label: Streaming Routing Reference
296
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/streaming-routing.md
297
+ - meta:
298
+ label: Node Types and Lifecycle Reference
299
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/nodes-ephemerality.md
300
+ - meta:
301
+ label: Metrics Centralization Points
302
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/README.md
303
+ items:
304
+ - meta:
305
+ label: Configuring Metrics Centralization Points
306
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/configuration.md
307
+ - meta:
308
+ label: Sizing Netdata Parents
309
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/sizing-netdata-parents.md
310
+ - meta:
311
+ label: Clustering and High Availability of Netdata Parents
312
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/clustering-and-high-availability-of-netdata-parents.md
313
+ - meta:
314
+ label: Replication of Past Samples
315
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/replication-of-past-samples.md
316
+ - meta:
317
+ label: FAQ on Metrics Centralization Points
318
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/faq.md
319
+ # Netdata Cloud
320
+ - meta:
321
+ label: Netdata Cloud
322
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/README.md
323
+ items:
324
+ - meta:
325
+ label: Connect Agent
326
+ edit_url: https://github.com/netdata/netdata/edit/master/src/claim/README.md
327
+ - meta:
328
+ label: Spaces and Rooms
329
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md
330
+ items:
331
+ - meta:
332
+ label: Node Rule-Based Room Assignment
333
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/node-rule-based-room-assignment.md
334
+ - meta:
335
+ label: Authentication & Authorization
336
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/README.md
337
+ items:
338
+ - meta:
339
+ label: Enterprise SSO Authentication
340
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/enterprise-sso-authentication.md
341
+ - meta:
342
+ label: Role-based access model
343
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/role-based-access-model.md
344
+ description: Explanation of Netdata roles and permissions linked to them
345
+ - meta:
346
+ label: API Tokens
347
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/authentication-and-authorization/api-tokens.md
348
+ - type: integration_placeholder
349
+ integration_kind: authentication
350
+ - meta:
351
+ label: Netdata Plans & Billing
352
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/view-plan-and-billing.md
353
+ - meta:
354
+ label: Agent-Cloud Link (ACLK)
355
+ edit_url: https://github.com/netdata/netdata/edit/master/src/aclk/README.md
356
+ description: The Agent-Cloud link (ACLK) is the mechanism responsible for connecting a Netdata agent to Netdata Cloud.
357
+ - meta:
358
+ label: Remove Agent
359
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/learn/remove-node.md
360
+ - meta:
361
+ label: Node States and Transitions
362
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-cloud/node-states-and-transitions.md
363
+ description: Understanding node connection states and state transitions in Netdata Cloud
364
+ keywords:
365
+ - node states
366
+ - live
367
+ - stale
368
+ - offline
369
+ - unseen
370
+ - transitions
371
+ - meta:
372
+ label: Unclaim and Reclaim a Node
373
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/learn/unclaim-reclaim-node.md
374
+ - meta:
375
+ label: Account Deletion
376
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/delete/netdata/account.md
377
+ # Netdata Cloud On-Prem
378
+ - meta:
379
+ label: Netdata Cloud On-Prem
380
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/README.md
381
+ items:
382
+ - meta:
383
+ label: Installation
384
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/installation.md
385
+ - meta:
386
+ label: Software Bill of Materials
387
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/sbom.md
388
+ - meta:
389
+ label: Container Image Signature Verification
390
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/image-signature-verification.md
391
+ - meta:
392
+ label: Security Hardening Guide
393
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/hardening-guide.md
394
+ - meta:
395
+ label: Kubernetes Network Policy Configuration
396
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/netpol.md
397
+ - meta:
398
+ label: PoC without K8s
399
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/poc-without-k8s.md
400
+ - meta:
401
+ label: Mirroring image registry
402
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/ecr-mirror.md
403
+ - meta:
404
+ label: Troubleshooting
405
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/docs/learn.netdata.cloud/troubleshooting.md
406
+ - meta:
407
+ label: Release Notes
408
+ edit_url: https://github.com/netdata/netdata-cloud-onprem/edit/master/netdata-cloud-onprem/RELEASE-NOTES.md
409
+ # Collecting Metrics
410
+ - meta:
411
+ label: Collecting Metrics
412
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/README.md
413
+ items:
414
+ - meta:
415
+ label: Collectors configuration
416
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/REFERENCE.md
417
+ - meta:
418
+ label: Service discovery
419
+ edit_url: https://github.com/netdata/agent-service-discovery/edit/master/README.md
420
+ - meta:
421
+ label: StatsD
422
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/statsd.plugin/README.md
423
+ - meta:
424
+ label: OpenTelemetry Metrics
425
+ edit_url: https://github.com/netdata/netdata/edit/master/src/crates/netdata-otel/otel-plugin/README.md
426
+ description: Ingesting storing and visualizing OpenTelemetry metrics
427
+ path: OpenTelemetry
428
+ - meta:
429
+ label: SNMP Profile Format
430
+ edit_url: https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/snmp/profile-format.md
431
+ description: Learn how Netdata’s SNMP collector uses profiles.
432
+ - type: integration_placeholder
433
+ integration_kind: collectors
434
+ # Exporting Metrics
435
+ - meta:
436
+ label: Exporting Metrics
437
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/exporting-metrics/README.md
438
+ description: Use the exporting engine to send Netdata metrics to popular external time series databases for long-term storage or further analysis.
439
+ items:
440
+ - meta:
441
+ label: Exporting reference
442
+ edit_url: https://github.com/netdata/netdata/edit/master/src/exporting/README.md
443
+ description: With the exporting engine, you can archive your Netdata metrics to multiple external databases for long-term storage or further analysis.
444
+ - meta:
445
+ label: Enable an exporting connector
446
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/exporting-metrics/enable-an-exporting-connector.md
447
+ description: Learn how to enable and configure any connector using examples to start exporting metrics to external time-series databases in minutes.
448
+ - meta:
449
+ label: Prometheus
450
+ edit_url: https://github.com/netdata/netdata/edit/master/src/exporting/prometheus/README.md
451
+ description: Export Netdata metrics to Prometheus for archiving and further analysis.
452
+ - meta:
453
+ label: Shell Scripts
454
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/exporters/shell/README.md
455
+ - type: integration_placeholder
456
+ integration_kind: exporters
457
+ # Logs
458
+ - meta:
459
+ label: Logs
460
+ items:
461
+ - meta:
462
+ label: Journal Viewer Plugin
463
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/logs/README.md
464
+ description: View and analyze logs available in systemd journal
465
+ path: Systemd Journal Logs
466
+ items:
467
+ - meta:
468
+ label: Forward Secure Sealing (FSS) in Systemd-Journal
469
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/logs/forward_secure_sealing.md
470
+ - meta:
471
+ label: Windows Events Plugin Reference
472
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/windows-events.plugin/README.md
473
+ path: Windows Event Logs
474
+ - meta:
475
+ label: log2journal
476
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/log2journal/README.md
477
+ path: log2journal
478
+ - meta:
479
+ label: systemd-cat-native
480
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/log/systemd-cat-native.md
481
+ - meta:
482
+ label: Logs Centralization Points with systemd-journald
483
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/logs-centralization-points-with-systemd-journald/README.md
484
+ items:
485
+ - meta:
486
+ label: Passive journal centralization with encryption using self-signed certificates
487
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/logs-centralization-points-with-systemd-journald/passive-journal-centralization-with-encryption-using-self-signed-certificates.md
488
+ - meta:
489
+ label: Passive journal centralization without encryption
490
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/logs-centralization-points-with-systemd-journald/passive-journal-centralization-without-encryption.md
491
+ - meta:
492
+ label: Active journal source without encryption
493
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/logs/active_journal_centralization_guide_no_encryption.md
494
+ - type: integration_placeholder
495
+ integration_kind: logs
496
+ # Top Consumers
497
+ - meta:
498
+ label: Top Consumers
499
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/top-monitoring-netdata-functions.md
500
+ description: Present the Netdata Functions what these are and why they should be used.
501
+ items:
502
+ - meta:
503
+ label: Processes
504
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/functions/processes.md
505
+ - meta:
506
+ label: Database Queries
507
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/functions/databases.md
508
+ description: Top and running database queries with deadlock and error attribution for 13 databases.
509
+ # Alerts & Notifications
510
+ - meta:
511
+ label: Alerts & Notifications
512
+ edit_url: https://github.com/netdata/netdata/edit/master/src/health/README.md
513
+ items:
514
+ - meta:
515
+ label: Creating Alerts with the Alerts Configuration Manager
516
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/alerts-and-notifications/creating-alerts-with-netdata-alerts-configuration-manager.md
517
+ - meta:
518
+ label: Notifications
519
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/alerts-and-notifications/notifications/README.md
520
+ description: Send Netdata alerts from a centralized place with Netdata Cloud, or configure nodes individually, to enable incident response and faster resolution.
521
+ items:
522
+ - meta:
523
+ label: Agent Notifications Reference
524
+ edit_url: https://github.com/netdata/netdata/edit/master/src/health/notifications/README.md
525
+ path: Agent Dispatched Notifications
526
+ items:
527
+ - type: integration_placeholder
528
+ integration_kind: agent_notifications
529
+ - meta:
530
+ label: Centralized Cloud Notifications Reference
531
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/centralized-cloud-notifications-reference.md
532
+ description: Configure Netdata Cloud to send notifications to your team whenever any node on your infrastructure triggers an alert threshold.
533
+ path: Centralized Cloud Notifications
534
+ items:
535
+ - meta:
536
+ label: Manage notification methods
537
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/manage-notification-methods.md
538
+ description: Instructions on how to manage notification methods
539
+ - meta:
540
+ label: Manage alert notification silencing rules
541
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/alerts-and-notifications/notifications/centralized-cloud-notifications/manage-alert-notification-silencing-rules.md
542
+ description: Master Netdata alert management via notification silencing rules for efficient and focused monitoring.
543
+ - type: integration_placeholder
544
+ integration_kind: cloud_notifications
545
+ - meta:
546
+ label: Alert Configuration Reference
547
+ edit_url: https://github.com/netdata/netdata/edit/master/src/health/REFERENCE.md
548
+ - meta:
549
+ label: Alert Configuration Ordering
550
+ edit_url: https://github.com/netdata/netdata/edit/master/src/health/alert-configuration-ordering.md
551
+ keywords:
552
+ - alerts
553
+ - health
554
+ - ordering
555
+ - precedence
556
+ - templates
557
+ - alarms
558
+ - meta:
559
+ label: Overriding Stock Alerts
560
+ edit_url: https://github.com/netdata/netdata/edit/master/src/health/overriding-stock-alerts.md
561
+ keywords:
562
+ - alerts
563
+ - health
564
+ - override
565
+ - stock
566
+ - templates
567
+ - alarms
568
+ - meta:
569
+ label: Health API Calls
570
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/health/README.md
571
+ # Netdata AI
572
+ - meta:
573
+ label: Netdata AI
574
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/category-overview-pages/machine-learning-and-assisted-troubleshooting.md
575
+ items:
576
+ - meta:
577
+ label: Conversations
578
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/conversations.md
579
+ keywords:
580
+ - conversations
581
+ - chat
582
+ - real-time
583
+ - live exhibits
584
+ - meta:
585
+ label: Insights
586
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-insights.md
587
+ items:
588
+ - meta:
589
+ label: Infrastructure Summary
590
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/infrastructure-summary.md
591
+ - meta:
592
+ label: Performance Optimization
593
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/performance-optimization.md
594
+ - meta:
595
+ label: Capacity Planning
596
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/capacity-planning.md
597
+ - meta:
598
+ label: Anomaly Analysis
599
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/anomaly-analysis.md
600
+ - meta:
601
+ label: Scheduled Reports
602
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/scheduled-reports.md
603
+ - meta:
604
+ label: Investigations
605
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/investigations/index.md
606
+ items:
607
+ - meta:
608
+ label: Custom Investigations
609
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/investigations/custom-investigations.md
610
+ - meta:
611
+ label: Scheduled Investigations
612
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/investigations/scheduled-investigations.md
613
+ - meta:
614
+ label: Troubleshooting
615
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/troubleshooting/index.md
616
+ items:
617
+ - meta:
618
+ label: Alert Troubleshooting
619
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/troubleshooting/troubleshoot.md
620
+ - meta:
621
+ label: Anomaly Advisor
622
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/ml-ai/anomaly-advisor.md
623
+ - meta:
624
+ label: Metric Correlations
625
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/metric-correlations.md
626
+ description: Quickly find metrics and charts closely related to a particular timeframe of interest anywhere in your infrastructure to discover the root cause faster.
627
+ - meta:
628
+ label: Alerts Automation
629
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/alerts-automation/alerts-automation.md
630
+ description: AI-powered alert creation and suggestions
631
+ keywords:
632
+ - alerts
633
+ - automation
634
+ - ai alerts
635
+ - meta:
636
+ label: Anomaly Detection
637
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-anomaly-detection.md
638
+ items:
639
+ - meta:
640
+ label: ML Configuration
641
+ edit_url: https://github.com/netdata/netdata/edit/master/src/ml/ml-configuration.md
642
+ - meta:
643
+ label: ML Accuracy
644
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-accuracy.md
645
+ description: Analysis of Netdata's ML anomaly detection accuracy, false positive rates, and comparison with other approaches
646
+ - meta:
647
+ label: MCP
648
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/README.md
649
+ items:
650
+ - meta:
651
+ label: Chat with Netdata
652
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/ai-chat-netdata.md
653
+ - meta:
654
+ label: MCP Clients
655
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md
656
+ items:
657
+ - meta:
658
+ label: Claude Desktop
659
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/claude-desktop.md
660
+ - meta:
661
+ label: Cursor
662
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/cursor.md
663
+ - meta:
664
+ label: Visual Studio Code
665
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/vs-code.md
666
+ - meta:
667
+ label: JetBrains IDEs
668
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/jetbrains-ides.md
669
+ - meta:
670
+ label: Netdata Web Client
671
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/netdata-web-client.md
672
+ - meta:
673
+ label: Claude Code
674
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/claude-code.md
675
+ - meta:
676
+ label: Gemini CLI
677
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/gemini-cli.md
678
+ - meta:
679
+ label: OpenAI Codex CLI
680
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/codex-cli.md
681
+ - meta:
682
+ label: Crush
683
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/crush.md
684
+ - meta:
685
+ label: OpenCode
686
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/netdata-ai/mcp/mcp-clients/opencode.md
687
+ # Dashboards and Charts
688
+ - meta:
689
+ label: Dashboards and Charts
690
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/README.md
691
+ items:
692
+ - meta:
693
+ label: Tabs
694
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/home-tab.md
695
+ description: With Netdata Cloud's War Rooms, you can see real-time metrics, from any number of nodes in your infrastructure, in composite charts.
696
+ items:
697
+ - meta:
698
+ label: Alerts
699
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/alerts-tab.md
700
+ - meta:
701
+ label: Anomalies
702
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/anomaly-advisor-tab.md
703
+ description: Quickly find anomalous metrics anywhere in your infrastructure.
704
+ - meta:
705
+ label: Dashboards
706
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/dashboards-tab.md
707
+ description: Design new dashboards that target your infrastructure's unique needs and share them with your team fortargeted visual anomaly detection or incident response.
708
+ - meta:
709
+ label: Events
710
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/events-feed.md
711
+ description: Present the Netdata Events feed.
712
+ - meta:
713
+ label: Kubernetes
714
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/kubernetes-tab.md
715
+ description: Netdata Cloud features rich, zero-configuration Kubernetes monitoring for the resource utilization and application metrics of Kubernetes (k8s) clusters.
716
+ - meta:
717
+ label: Logs
718
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/logs-tab.md
719
+ - meta:
720
+ label: Metrics
721
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/metrics-tab-and-single-node-tabs.md
722
+ - meta:
723
+ label: Nodes
724
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/nodes-tab.md
725
+ description: See charts from all your nodes in one pane of glass, then dive in to embedded dashboards for granular troubleshooting of ongoing issues.
726
+ - meta:
727
+ label: Top
728
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/top-tab.md
729
+ description: Instructions on how to use Functions
730
+ - meta:
731
+ label: Theme
732
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/themes.md
733
+ - meta:
734
+ label: Grafana Plugin
735
+ edit_url: https://github.com/netdata/netdata-grafana-datasource-plugin/edit/master/README.md
736
+ - meta:
737
+ label: Charts
738
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/netdata-charts.md
739
+ - meta:
740
+ label: Expanded Chart Analysis
741
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/expanded-chart-analysis.md
742
+ - meta:
743
+ label: NIDL Framework
744
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/NIDL-Framework.md
745
+ - meta:
746
+ label: Node Filter
747
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/node-filter.md
748
+ - meta:
749
+ label: Time Controls
750
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/visualization-date-and-time-controls.md
751
+ # Security and Privacy Design
752
+ - meta:
753
+ label: Security and Privacy Design
754
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/security-and-privacy-design/README.md
755
+ items:
756
+ - meta:
757
+ label: Netdata Agent
758
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/security-and-privacy-design/netdata-agent-security.md
759
+ - meta:
760
+ label: Netdata Cloud
761
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/security-and-privacy-design/netdata-cloud-security.md
762
+ # Developer and Contributor Corner
763
+ - meta:
764
+ label: Developer and Contributor Corner
765
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/README.md
766
+ items:
767
+ - meta:
768
+ label: REST API
769
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/README.md
770
+ items:
771
+ - meta:
772
+ label: Queries
773
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/README.md
774
+ items:
775
+ - meta:
776
+ label: Average or Mean
777
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/average/README.md
778
+ - meta:
779
+ label: CountIf
780
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/countif/README.md
781
+ - meta:
782
+ label: Double exponential smoothing
783
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/des/README.md
784
+ - meta:
785
+ label: Incremental Sum (`incremental_sum`)
786
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/incremental_sum/README.md
787
+ - meta:
788
+ label: Max
789
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/max/README.md
790
+ - meta:
791
+ label: Median
792
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/median/README.md
793
+ description: Use median in API queries and health entities to find the 'middle' value from a sample, eliminating any unwanted spikes in the returned metrics.
794
+ - meta:
795
+ label: Min
796
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/min/README.md
797
+ - meta:
798
+ label: Percentile
799
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/percentile/README.md
800
+ description: Use percentile in API queries and health entities to find the 'percentile' value from a sample, eliminating any unwanted spikes in the returned metrics.
801
+ - meta:
802
+ label: Single (or Simple) Exponential Smoothing (`ses`)
803
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/ses/README.md
804
+ - meta:
805
+ label: Standard deviation (`stddev`)
806
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/stddev/README.md
807
+ - meta:
808
+ label: Sum
809
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/sum/README.md
810
+ - meta:
811
+ label: Trimmed Mean
812
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/queries/trimmed_mean/README.md
813
+ description: Use trimmed-mean in API queries and health entities to find the average value from a sample, eliminating any unwanted spikes in the returned metrics.
814
+ - meta:
815
+ label: Formatters
816
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/formatters/README.md
817
+ items:
818
+ - meta:
819
+ label: CSV formatter
820
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/formatters/csv/README.md
821
+ - meta:
822
+ label: JSON formatter
823
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/formatters/json/README.md
824
+ - meta:
825
+ label: SSV formatter
826
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/formatters/ssv/README.md
827
+ - meta:
828
+ label: Value formatter
829
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/formatters/value/README.md
830
+ - meta:
831
+ label: Netdata badges
832
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/api/badges/README.md
833
+ - meta:
834
+ label: Dynamic Configuration
835
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/dyncfg.md
836
+ - meta:
837
+ label: Database Engine
838
+ edit_url: https://github.com/netdata/netdata/edit/master/src/database/engine/README.md
839
+ - meta:
840
+ label: Contributing
841
+ edit_url: https://github.com/netdata/.github/edit/main/CONTRIBUTING.md
842
+ - meta:
843
+ label: Community code of conduct
844
+ edit_url: https://github.com/netdata/.github/edit/main/CODE_OF_CONDUCT.md
845
+ - meta:
846
+ label: Security Policy
847
+ edit_url: https://github.com/netdata/.github/edit/main/SECURITY.md
848
+ description: The Netdata team maintains and adheres to a formal process any time a member of the community reports a security vulnerability.
849
+ - meta:
850
+ label: External Plugins
851
+ edit_url: https://github.com/netdata/netdata/edit/master/src/plugins.d/README.md
852
+ items:
853
+ - meta:
854
+ label: go.d.plugin
855
+ edit_url: https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/README.md
856
+ description: go.d.plugin is an external plugin for Netdata, responsible for running individual data collectors written in Go.
857
+ items:
858
+ - meta:
859
+ label: How to write a Netdata collector in Go
860
+ edit_url: https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/docs/how-to-write-a-module.md
861
+ description: This guide will walk you through the technical implementation of writing a new Netdata collector in Golang, with tips on interfaces, structure, configuration files, and more.
862
+ - meta:
863
+ label: python.d.plugin
864
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/python.d.plugin/README.md
865
+ - meta:
866
+ label: charts.d.plugin
867
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/charts.d.plugin/README.md
868
+ - meta:
869
+ label: profile.plugin
870
+ edit_url: https://github.com/netdata/netdata/edit/master/src/collectors/profile.plugin/README.md
871
+ - meta:
872
+ label: Functions v3 Protocol reference
873
+ edit_url: https://github.com/netdata/netdata/edit/master/src/plugins.d/FUNCTION_UI_REFERENCE.md
874
+ - meta:
875
+ label: Functions developer guide
876
+ edit_url: https://github.com/netdata/netdata/edit/master/src/plugins.d/FUNCTION_UI_DEVELOPER_GUIDE.md
877
+ - meta:
878
+ label: Contribute to the documentation
879
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/guidelines.md
880
+ items:
881
+ - meta:
882
+ label: Netdata style guide
883
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/style-guide.md
884
+ description: The Netdata style guide establishes editorial guidelines for all of Netdata's writing, including documentation, blog posts, in-product UX copy, and more.
885
+ - meta:
886
+ label: Glossary
887
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/glossary.md
888
+ - meta:
889
+ label: libnetdata
890
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/README.md
891
+ items:
892
+ - meta:
893
+ label: Adaptive re-sortable list (ARL)
894
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/adaptive_resortable_list/README.md
895
+ - meta:
896
+ label: Array allocator
897
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/aral/README.md
898
+ - meta:
899
+ label: AVL
900
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/avl/README.md
901
+ - meta:
902
+ label: BUFFER library
903
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/buffer/README.md
904
+ - meta:
905
+ label: Circular Buffer
906
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/circular_buffer/README.md
907
+ - meta:
908
+ label: Clocks
909
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/clocks/README.md
910
+ - meta:
911
+ label: Netdata ini config files
912
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/config/README.md
913
+ - meta:
914
+ label: JSON
915
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/json/README.md
916
+ - meta:
917
+ label: Locks
918
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/locks/README.md
919
+ - meta:
920
+ label: One way allocator
921
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/onewayalloc/README.md
922
+ - meta:
923
+ label: popen
924
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/popen/README.md
925
+ - meta:
926
+ label: parser
927
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/parser/README.md
928
+ - meta:
929
+ label: procfile
930
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/procfile/README.md
931
+ - meta:
932
+ label: Simple patterns
933
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/simple_pattern/README.md
934
+ description: Netdata supports simple patterns, which are less cryptic versions of regular expressions. Use familiar notation for powerful results.
935
+ - meta:
936
+ label: Statistical functions
937
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/statistical/README.md
938
+ - meta:
939
+ label: Storage number
940
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/storage_number/README.md
941
+ - meta:
942
+ label: String
943
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/string/README.md
944
+ - meta:
945
+ label: Threads
946
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/threads/README.md
947
+ - meta:
948
+ label: URL
949
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/url/README.md
950
+ - meta:
951
+ label: Worker Utilization
952
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/worker_utilization/README.md
953
+ - meta:
954
+ label: Dictionaries
955
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/dictionary/README.md
956
+ - meta:
957
+ label: July interface
958
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/july/README.md
959
+ - meta:
960
+ label: Socket
961
+ edit_url: https://github.com/netdata/netdata/edit/master/src/libnetdata/socket/README.md
962
+ - meta:
963
+ label: Running a Local Dashboard through Cloudflare Tunnels
964
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/running-through-cf-tunnels.md
965
+ - meta:
966
+ label: Redistributed Software
967
+ edit_url: https://github.com/netdata/netdata/edit/master/REDISTRIBUTED.md
968
+ - meta:
969
+ label: Health command API tester
970
+ edit_url: https://github.com/netdata/netdata/edit/master/tests/health_mgmtapi/README.md
971
+ - meta:
972
+ label: Import, export, and print a snapshot
973
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/dashboards-and-charts/import-export-print-snapshot.md
974
+ description: Snapshots can be incredibly useful for diagnosing anomalies after they've already happened, and are interoperable with any other node running Netdata.
975
+ - meta:
976
+ label: Build a custom Dashboard HTML page
977
+ edit_url: https://github.com/netdata/netdata/edit/master/src/web/gui/custom/README.md
978
+ description: Build custom dashboards with key metrics from one or more nodes running the Netdata Agent and host them anywhere.
979
+ - meta:
980
+ label: Monitor Nginx or Apache web server log files with Netdata
981
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md
982
+ - meta:
983
+ label: Monitor Unbound DNS servers with Netdata
984
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/collect-unbound-metrics.md
985
+ - meta:
986
+ label: Monitor a Hadoop cluster with Netdata
987
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md
988
+ - meta:
989
+ label: Monitor, troubleshoot, and debug applications with eBPF metrics
990
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md
991
+ description: Use Netdata's built-in eBPF metrics collector to monitor, troubleshoot, and debug your custom application using low-level kernel feedback.
992
+ - meta:
993
+ label: Build the Netdata Agent Yourself
994
+ edit_url: https://github.com/netdata/netdata/edit/master/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md
995
+ items:
996
+ - meta:
997
+ label: Package Maintainers
998
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/maintainers/README.md
999
+ - meta:
1000
+ label: Compile from source code
1001
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/source.md
1002
+ description: Package maintainers and power users may be interested in manually building Netdata from source without using any of our installation scripts.
1003
+ - meta:
1004
+ label: External build-system
1005
+ edit_url: https://github.com/netdata/netdata/edit/master/build_external/README.md
1006
+ - meta:
1007
+ label: How to build native (DEB/RPM) packages locally for testing
1008
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/building-native-packages-locally.md
1009
+ description: Instructions for developers who need to build native packages locally for testing.
1010
+ - meta:
1011
+ label: Netdata contrib
1012
+ edit_url: https://github.com/netdata/netdata/edit/master/contrib/README.md
1013
+ - meta:
1014
+ label: Install the Netdata Agent from a Git checkout
1015
+ edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/methods/manual.md
1016
+ description: Use the Netdata Agent source code from GitHub, plus helper scripts to set up your system, to install Netdata without packages or binaries.
docs/.map/validate_map_schema.py
new
+282
@@ -0,0 +1,282 @@
1
+#!/usr/bin/env python3
2
+"""Validate map.yaml against JSON Schema with additional custom rules.
3
+
4
+This validator uses JSON Schema for structure validation and adds custom
5
+checks for rules that can't be expressed in JSON Schema, such as:
6
+- Nodes with integration_placeholder children can omit edit_url
7
+- No duplicate edit_urls
8
+
9
+Path reconstruction rule (for ingest):
10
+- Nodes WITH items array → label is the path segment (they define hierarchy)
11
+- Nodes WITHOUT items → leaves that belong to their parent's path
12
+
13
+Exit codes:
14
+ 0 - Validation passed
15
+ 1 - Validation failed
16
+"""
17
+
18
+import sys
19
+import json
20
+from pathlib import Path
21
+from typing import List, Dict, Any, Tuple
22
+
23
+try:
24
+ from ruamel.yaml import YAML
25
+except ImportError:
26
+ print("ERROR: ruamel.yaml is required. Install with: pip install ruamel.yaml")
27
+ sys.exit(1)
28
+
29
+try:
30
+ import jsonschema
31
+ from jsonschema import Draft7Validator
32
+except ImportError:
33
+ print("ERROR: jsonschema is required. Install with: pip install jsonschema")
34
+ sys.exit(1)
35
+
36
+
37
+class MapValidationError:
38
+ def __init__(self, path: str, message: str):
39
+ self.path = path
40
+ self.message = message
41
+
42
+ def __str__(self):
43
+ return f"[{self.path}] {self.message}"
44
+
45
+
46
+def load_schema(schema_path: str) -> dict:
47
+ """Load JSON Schema from file."""
48
+ with open(schema_path, "r", encoding="utf-8") as f:
49
+ return json.load(f)
50
+
51
+
52
+def load_yaml(yaml_path: str) -> dict:
53
+ """Load YAML file."""
54
+ yaml = YAML(typ="safe")
55
+ with open(yaml_path, "r", encoding="utf-8") as f:
56
+ return yaml.load(f)
57
+
58
+
59
+def format_schema_error(error: jsonschema.ValidationError) -> str:
60
+ """Format a JSON Schema validation error nicely."""
61
+ path = (
62
+ ".".join(str(p) for p in error.absolute_path) if error.absolute_path else "root"
63
+ )
64
+ # For oneOf/anyOf, jsonschema often reports a generic message like
65
+ # "is not valid under any of the given schemas" and puts the real
66
+ # problems into error.context. Surface the most relevant sub-error(s)
67
+ # so users see actionable messages without needing debug output.
68
+ validator = getattr(error, "validator", None)
69
+ if validator in ("oneOf", "anyOf") and getattr(error, "context", None):
70
+ suberrors = list(error.context)
71
+
72
+ def _path_depth(e: jsonschema.ValidationError) -> int:
73
+ try:
74
+ return len(list(e.absolute_path))
75
+ except Exception:
76
+ return 0
77
+
78
+ # Prefer the deepest (most specific) sub-error.
79
+ suberrors.sort(key=_path_depth, reverse=True)
80
+ primary = suberrors[0]
81
+ sub_path = (
82
+ ".".join(str(p) for p in primary.absolute_path)
83
+ if primary.absolute_path
84
+ else path
85
+ )
86
+ # Collect up to a couple of distinct messages for context.
87
+ messages = [primary.message]
88
+ for sub in suberrors[1:3]:
89
+ if sub.message not in messages:
90
+ messages.append(sub.message)
91
+ details = "; ".join(messages)
92
+ return f"[{sub_path}] {details} (while validating {validator} at {path})"
93
+ return f"[{path}] {error.message}"
94
+
95
+
96
+def check_has_integration_placeholder(items: List[Any]) -> bool:
97
+ """Check if a node's items contain an integration_placeholder."""
98
+ if not isinstance(items, list):
99
+ return False
100
+ return any(
101
+ isinstance(item, dict) and item.get("type") == "integration_placeholder"
102
+ for item in items
103
+ )
104
+
105
+
106
+def check_duplicate_edit_urls(
107
+ node: Any, path: str, edit_urls: Dict[str, str], errors: List[MapValidationError]
108
+) -> None:
109
+ """Recursively check for duplicate edit_urls."""
110
+ if not isinstance(node, dict):
111
+ return
112
+
113
+ # Skip integration placeholders
114
+ if node.get("type") == "integration_placeholder":
115
+ return
116
+
117
+ # Check meta
118
+ meta = node.get("meta", {})
119
+ if isinstance(meta, dict):
120
+ label = meta.get("label", "???")
121
+ node_path = f"{path}/{label}" if path else label
122
+ edit_url = meta.get("edit_url")
123
+
124
+ if edit_url and isinstance(edit_url, str):
125
+ if edit_url in edit_urls:
126
+ errors.append(
127
+ MapValidationError(
128
+ node_path,
129
+ f"Duplicate edit_url: '{edit_url}' (first seen at {edit_urls[edit_url]})",
130
+ )
131
+ )
132
+ else:
133
+ edit_urls[edit_url] = node_path
134
+
135
+ # Recurse into children
136
+ items = node.get("items", [])
137
+ if isinstance(items, list):
138
+ for item in items:
139
+ check_duplicate_edit_urls(item, node_path, edit_urls, errors)
140
+
141
+
142
+def check_integration_placeholder_rule(
143
+ node: Any, path: str, errors: List[MapValidationError]
144
+) -> None:
145
+ """
146
+ Check that nodes without edit_url have integration_placeholder children.
147
+
148
+ Custom rule: A node can only omit edit_url if it has at least one
149
+ integration_placeholder child.
150
+ """
151
+ if not isinstance(node, dict):
152
+ return
153
+
154
+ # Skip integration placeholders themselves
155
+ if node.get("type") == "integration_placeholder":
156
+ return
157
+
158
+ meta = node.get("meta", {})
159
+ if not isinstance(meta, dict):
160
+ return
161
+
162
+ label = meta.get("label", "???")
163
+ node_path = f"{path}/{label}" if path else label
164
+ edit_url = meta.get("edit_url")
165
+ items = node.get("items", [])
166
+
167
+ # If edit_url is missing, check if there's an integration placeholder
168
+ if edit_url is None:
169
+ if not check_has_integration_placeholder(items):
170
+ errors.append(
171
+ MapValidationError(
172
+ node_path,
173
+ "Missing 'edit_url' field (only allowed for nodes with integration_placeholder children)",
174
+ )
175
+ )
176
+
177
+ # Recurse into children
178
+ if isinstance(items, list):
179
+ for item in items:
180
+ check_integration_placeholder_rule(item, node_path, errors)
181
+
182
+
183
+def validate_with_schema(data: dict, schema: dict) -> Tuple[bool, List[str]]:
184
+ """Validate data against JSON Schema."""
185
+ validator = Draft7Validator(schema)
186
+ errors = []
187
+
188
+ for error in validator.iter_errors(data):
189
+ errors.append(format_schema_error(error))
190
+
191
+ return len(errors) == 0, errors
192
+
193
+
194
+def validate_custom_rules(data: dict) -> Tuple[bool, List[MapValidationError]]:
195
+ """Apply custom validation rules not expressible in JSON Schema."""
196
+ errors: List[MapValidationError] = []
197
+ edit_urls: Dict[str, str] = {}
198
+
199
+ # Guard against non-dict YAML root
200
+ if not isinstance(data, dict):
201
+ return False, [
202
+ MapValidationError(
203
+ "root", f"YAML root must be a dictionary, got {type(data).__name__}"
204
+ )
205
+ ]
206
+
207
+ sidebar = data.get("sidebar", [])
208
+ if not isinstance(sidebar, list):
209
+ return False, [MapValidationError("root", "sidebar must be a list")]
210
+
211
+ # Check for duplicate edit_urls
212
+ for node in sidebar:
213
+ check_duplicate_edit_urls(node, "", edit_urls, errors)
214
+
215
+ # Check integration placeholder rule
216
+ for node in sidebar:
217
+ check_integration_placeholder_rule(node, "", errors)
218
+
219
+ return len(errors) == 0, errors
220
+
221
+
222
+def main():
223
+ """Main validation routine."""
224
+ script_dir = Path(__file__).parent
225
+ yaml_path = script_dir / "map.yaml"
226
+ schema_path = script_dir / "map.schema.json"
227
+
228
+ if not yaml_path.exists():
229
+ print(f"ERROR: {yaml_path} not found")
230
+ sys.exit(1)
231
+
232
+ if not schema_path.exists():
233
+ print(f"ERROR: {schema_path} not found")
234
+ sys.exit(1)
235
+
236
+ print("Validating map.yaml...")
237
+ print()
238
+
239
+ # Load files
240
+ try:
241
+ data = load_yaml(str(yaml_path))
242
+ schema = load_schema(str(schema_path))
243
+ except Exception as e:
244
+ print(f"ERROR loading files: {e}")
245
+ sys.exit(1)
246
+
247
+ # Guard against non-dict YAML root
248
+ if not isinstance(data, dict):
249
+ print(f"❌ Validation FAILED:\n")
250
+ print(f" • YAML root must be a dictionary, got {type(data).__name__}")
251
+ sys.exit(1)
252
+
253
+ all_errors = []
254
+
255
+ # Validate against JSON Schema
256
+ schema_valid, schema_errors = validate_with_schema(data, schema)
257
+ if not schema_valid:
258
+ all_errors.append("Schema validation errors:")
259
+ all_errors.extend(f" • {err}" for err in schema_errors)
260
+
261
+ # Apply custom rules
262
+ custom_valid, custom_errors = validate_custom_rules(data)
263
+ if not custom_valid:
264
+ if all_errors:
265
+ all_errors.append("")
266
+ all_errors.append("Custom rule violations:")
267
+ all_errors.extend(f" • {err}" for err in custom_errors)
268
+
269
+ # Report results
270
+ if all_errors:
271
+ print("❌ Validation FAILED:\n")
272
+ print("\n".join(all_errors))
273
+ sys.exit(1)
274
+ else:
275
+ print("✅ Validation PASSED")
276
+ print(f" - Validated against schema: {schema_path.name}")
277
+ print(f" - All custom rules satisfied")
278
+ sys.exit(0)
279
+
280
+
281
+if __name__ == "__main__":
282
+ main()