docs: Add comprehensive Badges documentation by kanelatechnical · Pull Request #21711 · netdata/netdata
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
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.
- 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
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
- 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
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.
- Add character escaping table - Add embed/iframe refresh example - Add refresh parameter usage example
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters