Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion LegacyLearnCorrelateLinksWithGHURLs.json
Original file line number Diff line number Diff line change
Expand Up @@ -3531,5 +3531,6 @@
"https://learn.netdata.cloud/docs/netdata-ai/mcp/mcp-clients/crush": "https://github.com/netdata/netdata/blob/master/docs/netdata-ai/mcp/mcp-clients/crush.md",
"https://learn.netdata.cloud/docs/netdata-ai/mcp/mcp-clients/claude-desktop": "https://github.com/netdata/netdata/blob/master/docs/netdata-ai/mcp/mcp-clients/claude-desktop.md",
"https://learn.netdata.cloud/docs/netdata-ai/mcp/mcp-clients/claude-code": "https://github.com/netdata/netdata/blob/master/docs/netdata-ai/mcp/mcp-clients/claude-code.md",
"https://learn.netdata.cloud/docs/netdata-ai/mcp/mcp-clients": "https://github.com/netdata/netdata/blob/master/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md"
"https://learn.netdata.cloud/docs/netdata-ai/mcp/mcp-clients": "https://github.com/netdata/netdata/blob/master/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md",
"https://learn.netdata.cloud/docs/collecting-metrics/collectors/operating-systems/ebpf-cachestat": "https://github.com/netdata/netdata/blob/master/src/collectors/ebpf.plugin/integrations/ebpf_cachestat.md"
}
39 changes: 23 additions & 16 deletions docs/Collecting Metrics/Chart Template Format.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,9 @@ Each collector has a single `charts.yaml` file that describes all its charts.
When a collector runs, the chart engine:

1. Reads the collector's `charts.yaml` file.
2. Compiles it into an immutable program (validates, resolves defaults, infers algorithms).
3. On each collection cycle, matches incoming metrics against dimension selectors.
2. Compiles it into an immutable program (validates and resolves static defaults).
3. On each collection cycle, matches incoming metrics against dimension selectors and resolves omitted algorithms from
runtime metric kinds.
4. Creates chart instances dynamically based on instance identity labels.
5. Updates dimension values every cycle; removes stale instances based on lifecycle policy.

Expand All @@ -54,13 +55,13 @@ When a collector runs, the chart engine:
└──────────┬──────────┘
v
┌─────────────────────┐
│ Compile (engine) │ selector parsing, algorithm inference,
│ Compile (engine) │ selector parsing, static defaults,
│ │ context/family/ID composition
└──────────┬──────────┘
v
┌─────────────────────┐
│ Runtime (per cycle)│ match series → create/update/remove
│ │ charts and dimensions
│ Runtime (per cycle)│ match series → resolve algorithms →
│ │ create/update/remove charts and dimensions
└─────────────────────┘
```

Expand Down Expand Up @@ -565,7 +566,7 @@ charts:
| `family` | string | no | | Optional chart-level family leaf, appended to the group family. |
| `context` | string | **yes** | | Chart context leaf. Combined with context namespaces. |
| `units` | string | **yes** | | Chart units (e.g., `queries/s`, `bytes`, `percentage`). |
| `algorithm` | string | no | inferred from metrics | `absolute` or `incremental`. If omitted, inferred from metric suffixes. |
| `algorithm` | string | no | runtime metric kind | `absolute` or `incremental`. If omitted, resolved per dimension from the matched series kind. |
| `aggregation` | string | no | `sum` | Reducer applied to every dimension in the chart. |
| `type` | string | no | `line` | `line`, `area`, `stacked`, or `heatmap`. Histogram bucket charts are forced to `heatmap`. |
| `priority` | int | no | `70000` | Chart ordering priority in the dashboard (`0` = use engine default `70000`). |
Expand All @@ -579,20 +580,25 @@ ID. Promoted labels are non-identity metadata. When their effective intersection
existing chart with a complete replacement label set; it does not recreate the chart or its dimensions.

> [!TIP]
> When `algorithm` is omitted, the engine infers it from metric name suffixes. You only need to set it explicitly when the suffix doesn't match the intended behavior (e.g., a gauge metric named `*_total`).

| Suffix | Inferred algorithm |
|-------------------------------------------|--------------------|
| `*_total`, `*_count`, `*_sum`, `*_bucket` | `incremental` |
| Everything else | `absolute` |
> Omit `algorithm` for the normal case. The engine uses `incremental` for a matched runtime counter and `absolute` for a
> gauge or any other kind, regardless of the metric name. Set it explicitly only when every dimension in the chart must
> intentionally override its runtime kind.

Histogram `_bucket` dimensions receive non-overlapping range bucket totals from
`metrix.ReadFlatten()`. The `le` label remains the bucket upper bound, but the
value is no longer cumulative with earlier buckets. Histogram bucket dimensions
are named by the bare `le` value and ordered numerically, with `+Inf` last.

> [!WARNING]
> If a chart's dimensions mix counter-like metrics (e.g., `requests_total`) with gauge-like metrics (e.g., `temperature`) and `algorithm` is omitted, the engine fails with a compile error: _"algorithm inference is ambiguous for mixed metric kinds; set algorithm explicitly"_. Set `algorithm` on the chart to resolve this.
> Different runtime kinds may share a chart when they render as distinct dimensions. If several series collapse into the
> same rendered dimension, omit `algorithm` only when those series have the same runtime kind. Otherwise set an explicit
> chart algorithm so the aggregated dimension has one intentional wire interpretation. Chartengine does not diagnose a
> violation at runtime; authoring validation and real-path tests must reject it rather than depend on first-observed
> metadata.

The runtime kind of a live metric identity must remain stable while its dimension is materialized. Changing the kind does
not redefine an existing Netdata dimension; its creation-time wire algorithm remains until the dimension expires and is
recreated.

**Example: MySQL queries — incremental counters displayed as rates**

Expand Down Expand Up @@ -1133,15 +1139,16 @@ All rules below produce semantic validation errors unless noted:
| Every autogen rule selector requires at least one non-empty valid `allow`/`deny` entry | semantic |
| Unknown YAML fields | decode error (strict unmarshal) |

## Compiler-Derived Behavior
## Engine-Derived Behavior

> [!NOTE]
> These behaviors are applied by `chartengine` during compilation, not by the template parser. You don't need to configure them — they happen automatically, but knowing about them helps you write simpler templates.
> These behaviors are applied by `chartengine` during compilation or runtime planning, not by the template parser. You
> don't need to configure them, but knowing about them helps you write simpler templates.

| Input | Derived behavior |
|-----------------------------------------|------------------------------------------------------------------------------------------|
| Missing `chart.id` | `id` derived from `context` (`.` replaced with `_`). |
| Missing `chart.algorithm` | Inferred from metric suffixes (`*_total`, `*_count`, `*_sum`, `*_bucket` = incremental). |
| Missing `chart.algorithm` | Resolved per rendered dimension from runtime series kind: counter = `incremental`; every other kind = `absolute`. |
| `chart.priority = 0` | Treated as `70000` (engine default). |
| Group family hierarchy + `chart.family` | Composed into `/`-separated chart family. |
| `options.multiplier = 0` | Treated as `1`. |
Expand Down
8 changes: 4 additions & 4 deletions docs/Collecting Metrics/Collectors/Collectors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -390,6 +390,10 @@ import { Grid, Box } from '@site/src/components/Grid_integrations';
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/operating-systems/ebpf-cachestat-ebpf-plugin" title="eBPF Cachestat">
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/operating-systems/ebpf-dcstat" title="eBPF DCstat">
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>
Expand Down Expand Up @@ -434,10 +438,6 @@ import { Grid, Box } from '@site/src/components/Grid_integrations';
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/networking/ebpf-socket" title="eBPF Socket">
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/operating-systems/ebpf-softirq" title="eBPF SoftIRQ">
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "150"
sidebar_position: "140"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/frrouting"
slug: "/collecting-metrics/collectors/networking/frrouting"
---
Expand Down
2 changes: 1 addition & 1 deletion docs/Collecting Metrics/Collectors/Networking/Fastd.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "130"
sidebar_position: "120"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/fastd"
slug: "/collecting-metrics/collectors/networking/fastd"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "140"
sidebar_position: "130"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/freifunk-network"
slug: "/collecting-metrics/collectors/networking/freifunk-network"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "170"
sidebar_position: "160"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/hitron-coda-cable-modem"
slug: "/collecting-metrics/collectors/networking/hitron-coda-cable-modem"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [ip virtual server]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "190"
sidebar_position: "180"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/ip-virtual-server"
slug: "/collecting-metrics/collectors/networking/ip-virtual-server"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [ipv6 sockets]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "210"
sidebar_position: "200"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/ipv6-socket-statistics"
slug: "/collecting-metrics/collectors/networking/ipv6-socket-statistics"
---
Expand Down
2 changes: 1 addition & 1 deletion docs/Collecting Metrics/Collectors/Networking/ISC DHCP.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [dhcpd, dhcp]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "220"
sidebar_position: "210"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/isc-dhcp"
slug: "/collecting-metrics/collectors/networking/isc-dhcp"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [infiniband, rdma]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "180"
sidebar_position: "170"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/infiniband"
slug: "/collecting-metrics/collectors/networking/infiniband"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "230"
sidebar_position: "220"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/keepalived"
slug: "/collecting-metrics/collectors/networking/keepalived"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [vpn, libreswan, network, ipsec]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "240"
sidebar_position: "230"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/libreswan"
slug: "/collecting-metrics/collectors/networking/libreswan"
---
Expand Down
2 changes: 1 addition & 1 deletion docs/Collecting Metrics/Collectors/Networking/NSD.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [nsd, dns]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "390"
sidebar_position: "380"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/nsd"
slug: "/collecting-metrics/collectors/networking/nsd"
---
Expand Down
2 changes: 1 addition & 1 deletion docs/Collecting Metrics/Collectors/Networking/NTPd.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [ntpd, ntp, time]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "400"
sidebar_position: "390"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/ntpd"
slug: "/collecting-metrics/collectors/networking/ntpd"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "330"
sidebar_position: "320"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/netfilter"
slug: "/collecting-metrics/collectors/networking/netfilter"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [network, connections, sockets, tcp, udp, ports, freebsd, macos]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "340"
sidebar_position: "330"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/network-connections"
slug: "/collecting-metrics/collectors/networking/network-connections"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [network, bandwidth, ip, udp, tcp, interface]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "370"
sidebar_position: "360"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/network-subsystem"
slug: "/collecting-metrics/collectors/networking/network-subsystem"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [network interfaces]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "350"
sidebar_position: "340"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/network-interfaces"
slug: "/collecting-metrics/collectors/networking/network-interfaces"
---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: [ip, udp, udplite, icmp, netstat, snmp]
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "360"
sidebar_position: "350"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/network-statistics"
slug: "/collecting-metrics/collectors/networking/network-statistics"
---
Expand Down
4 changes: 0 additions & 4 deletions docs/Collecting Metrics/Collectors/Networking/Networking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,6 @@ import { Grid, Box } from '@site/src/components/Grid_integrations';
<img custom-image src="https://netdata.cloud/img/dnsmasq.svg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="ok" data-logo-contrast-dark="ok" data-logo-contrast-confidence="medium"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/networking/ebpf-socket" title="eBPF Socket">
<img custom-image src="https://netdata.cloud/img/ebpf.jpg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="low" data-logo-contrast-dark="ok" data-logo-contrast-confidence="high"/>
</Box>

<Box banner="by Netdata" banner_color="#00ab44" to="/docs/collecting-metrics/collectors/networking/getifaddrs" title="getifaddrs">
<img custom-image src="https://netdata.cloud/img/network.svg" style={{width: '90%', maxHeight: '100%', verticalAlign: 'middle' }} data-integration-logo="true" data-logo-contrast-light="unknown" data-logo-contrast-dark="unknown" data-logo-contrast-confidence="low"/>
</Box>
Expand Down
2 changes: 1 addition & 1 deletion docs/Collecting Metrics/Collectors/Networking/NextDNS.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc_max_heading_level: "6"
toc_collapsible: "true"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
sidebar_position: "380"
sidebar_position: "370"
learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/networking/nextdns"
slug: "/collecting-metrics/collectors/networking/nextdns"
---
Expand Down
Loading