docs: Add comprehensive Badges documentation by kanelatechnical · Pull Request #21711 · netdata/netdata

cubic-dev-ai[bot]

cubic-dev-ai[bot]

cubic-dev-ai[bot]

ilyam8

ilyam8

ilyam8

ilyam8

ilyam8

Add documentation for the Badges feature (/api/v1/badge.svg) that allows
generating SVG badges displaying real-time metrics and alert status.

This addresses unresponded user queries about badges functionality.

Source code verified at src/web/api/v1/api_v1_badge/web_buffer_svg.c
Add badges.md to Dashboards and Charts section for proper learn.netdata.cloud
rendering. Placement rationale: Badges are a visualization/output feature for
embedding SVG images in dashboards and external sites, not a developer API.
Corrected discrepancies discovered during source code review:

1. Fixed conditional color operators:  is equality (not inequality),
    is the inequality operator
2. Corrected default  value:  (chart-dependent)
   instead of
3. Added missing parameters:  and
4. Corrected  default from 'Auto' to '-1 (auto)'
5. Updated examples to use correct conditional color syntax

Source: src/web/api/v1/api_v1_badge/web_buffer_svg.c
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Cross-verified against src/web/api/v1/api_v1_badge/web_buffer_svg.c and
src/web/api/queries/query.h:

1. Expanded grouping methods table to include: trimmed-mean, percentile,
   ses, des, cv, countif, extremes (source has ~50 methods)
2. Added UNINITIALIZED alert status (handled at line 1084-1085)
3. Fixed troubleshooting typo: color>threshold → color<threshold

All claims now align with source of truth.
Cross-verified against:
- src/web/api/v1/api_v1_badge/web_buffer_svg.c (main implementation)
- src/web/api/queries/query.h (grouping methods)
- src/daemon/config/netdata-conf-web.c (access control)

Corrections made:

1. Text color defaults: Changed from 'white' to 'grey' (fallback) - source
   uses 'fff' (white) only when explicitly passed, defaults to '555' (grey)

2. Empty value troubleshooting: Clarified that '-' appears when data is
   too old (staleness check) rather than just "no data"

3. Added Special Units Formats section documenting: seconds/minutes/hours
   (with _ago variants), on/off, up/down, ok/error, ok/failed, percentage,
   empty/null - all from badge_units_formatters array

4. Confirmed access control: 'allow badges from' in [web] section with
   default '*' (verified in netdata-conf-web.c:86-87)

All claims now align with source of truth.
Visual color indicators (spheres) added next to each predefined color
for easier identification when choosing badge colors.
Replaced non-rendering HTML spans with Unicode emoji circles that
render reliably in markdown tables.
Added asterisk marker to green sample and clarified in legend that
brightgreen is richer while green is lighter/yellowish.
Replaced emoji samples with actual colored boxes showing each hex code,
providing true visual representation of each badge color.

@kanelatechnical

- Fix WARNING alert color from yellow to orange (matches source code)
- Add REMOVED alert status (grey, occurs during shutdown/disconnect)
- Fix broken documentation links to correct paths
- Add URL escaping table
- Add performance section (2000 badges/sec, ~0.5ms per badge)
- Add JavaScript auto-refresh methods
- Add GitHub limitations section
- Add query options details (display_absolute, min2max, unaligned)
- Add note about escaping slashes in units
Convert troubleshooting section to use <details>/<summary> accordion format for better UX
- Remove extra column separator from table header
- Escape pipe character in options example
Text color defaults are 'fff' (white), not 'grey'
Replace static color table with inline badge images showing actual colors for better visual reference
Remove square brackets from image links to fix invalid markdown syntax. Use plain image syntax ![]() for standalone images
URL-encode the label parameter: Net%20In instead of Net+In (plus sign breaks URLs)
- Change chart=system.ram to mem.available for universal availability
- Clarify that allow badges from parameter goes under [web] section in netdata.conf
- Clarify "current CPU usage" as real-time from user dimension
- Remove divide parameter from Memory example (use precision instead)
- Change system.load to system.cpu for Status badge example
- Fix Network label (NetTraffic instead of Net In)
- Update CPU Alert example to use plausible alarm name (system.cpu_usage)
- Add note about alarm names being configuration-dependent

Reported issues and fixes:
1. Current vs dimension clarification
2. Memory divide parameter removed
3. system.load replaced with system.cpu
4. Network label fixed
5. Alert name updated to realistic example
Changes:
- Clarify Basic Metric Badge to explain single vs aggregated dimensions
- Clarify Memory badge behavior (total without dimensions)
- Explain system.load multi-dimension behavior
- Improve Alert Status Badge section with better description
- Add comprehensive "Notes on Chart and Alert Behavior" section
- Fix all issues raised by ilyam about chart/dimension/alarm behavior
- Fix divide parameter example (1024 for MiB→MB, not bytes→GiB)
- Fix options parameter example to use %7C URL encoding
- Add <> as inequality operator alongside !
- Document system.ram chart for memory dimensions
- Document missing chart parameter behavior (HTTP 400)
- Document invalid chart behavior (placeholder badge)
- Expand troubleshooting section with resolution steps

@kanelatechnical

Fixes ilyam8 review comment - system.load has 3 dimensions (load1, load5, load15)
and showing all 3 summed doesn't make sense. Changed to dimension=load1 for 1-min load.
Clarifies that alarm badges show BOTH status AND value, not 'instead of'.
Updates Alert Badges section to reflect this behavior.
Fixes lint warnings - all system.load examples now specify dimension=load1

ilyam8

ilyam8

ilyam8

ilyam8

ilyam8

- Add character escaping table
- Add embed/iframe refresh example
- Add refresh parameter usage example
- Fix CLEAR alert color: brightgreen instead of green
- Remove misleading mem.available dimension example (doesn't have dimensions)
- Use placeholder alarm name instead of potentially non-existent example
- Remove ini code fence (netdata.conf is not INI format)