docs: Add comprehensive Badges documentation#21711
Open
kanelatechnical wants to merge 28 commits intonetdata:masterfrom
Open
docs: Add comprehensive Badges documentation#21711kanelatechnical wants to merge 28 commits intonetdata:masterfrom
kanelatechnical wants to merge 28 commits intonetdata:masterfrom
Conversation
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="docs/.map/map.csv">
<violation number="1" location="docs/.map/map.csv:227">
P2: The new map.csv row contains unquoted commas in the keywords and description fields, which splits the row into extra columns and breaks ingestion. Quote the keywords and description fields so the row stays at 6 columns.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
59fff2f to
ff98e1a
Compare
Contributor
There was a problem hiding this comment.
2 issues found across 1 file (changes from recent commits).
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="docs/dashboards-and-charts/badges.md">
<violation number="1" location="docs/dashboards-and-charts/badges.md:50">
P3: The optional parameters table header has an extra column separator, which will break Markdown table rendering and misalign the rows.</violation>
<violation number="2" location="docs/dashboards-and-charts/badges.md:58">
P3: The `options` example includes an unescaped pipe, which splits the table row into extra columns and breaks rendering.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="docs/dashboards-and-charts/badges.md">
<violation number="1" location="docs/dashboards-and-charts/badges.md:125">
P2: The color badge examples use incomplete link syntax (`[]`) without a link target, which renders as invalid Markdown. Use plain image syntax (``) or provide a link target.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
3d4428d to
5d8cfcf
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the Badges API feature (/api/v1/badge.svg), which was previously undocumented despite being available in the source code. The documentation provides users with complete guidance on generating dynamic SVG badges to display Netdata metrics and alert statuses in external platforms like GitHub READMEs, dashboards, and documentation.
Changes:
- Added
docs/dashboards-and-charts/badges.mdwith complete API specification, usage examples, troubleshooting guide, and advanced configuration options - Registered the new documentation page in
docs/.map/map.csvfor proper rendering on learn.netdata.cloud - Documented all query parameters, color options, grouping methods, alert states, URL escaping requirements, and performance characteristics
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/dashboards-and-charts/badges.md | Comprehensive Badges API documentation covering endpoint specification, parameters, examples, color options, security, troubleshooting, and advanced usage patterns |
| docs/.map/map.csv | Registration entry for the badges documentation page with appropriate metadata and keywords |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ilyam8
reviewed
Feb 6, 2026
ilyam8
reviewed
Feb 6, 2026
ilyam8
reviewed
Feb 6, 2026
ilyam8
reviewed
Feb 6, 2026
ilyam8
reviewed
Feb 6, 2026
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.
- 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
be47c13 to
1b5d107
Compare
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.
ebafc1c to
75670fa
Compare
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
reviewed
Feb 6, 2026
docs/dashboards-and-charts/badges.md
Outdated
|
|
||
| 1. Edit `netdata.conf`: | ||
|
|
||
| ```ini |
Member
There was a problem hiding this comment.
@kanelatechnical netdata.conf is not ini, don't use ini for it.
ilyam8
reviewed
Feb 6, 2026
| Example: | ||
|
|
||
| ```markdown | ||
|  |
Member
There was a problem hiding this comment.
system.cpu_usage
Pame pali: this alert doesn't exist. Please do manual verification too.
ilyam8
reviewed
Feb 6, 2026
|
|
||
| ### Alert Status Badge | ||
|
|
||
| The badge displays the alert status text (like "OK", "WARNING", "CRITICAL") with the configured color. The alarm name must match your Netdata health configuration. |
Member
There was a problem hiding this comment.
The badge displays the alert status text
How to do that? Doesn't work for me. Does it work for you? Can you share a screenshot?
ilyam8
reviewed
Feb 6, 2026
docs/dashboards-and-charts/badges.md
Outdated
|  | ||
| ``` | ||
|
|
||
| **Note:** The `mem.available` chart shows total available memory when no dimension is specified. To display specific memory components, check if your Netdata configuration provides dimensions like `free` or `used`: |
Member
There was a problem hiding this comment.
This is just wrong.mem.available doesn't have free and used dimensions.
ilyam8
requested changes
Feb 6, 2026
- 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)
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds comprehensive documentation for the Badges feature that was previously undocumented but available in the source code.
Summary
The Badges feature allows users to generate dynamic SVG badges displaying real-time metrics and alert status from any Netdata agent. This feature was mentioned in user queries on asknetdata but had no documentation, leading to unresponded queries.
Changes
docs/dashboards-and-charts/badges.md- Complete documentation including:/api/v1/badge.svg)Technical Details
src/web/api/v1/api_v1_badge/web_buffer_svg.cweb_allow_badges_fromin netdata.confTesting
Fixes: Addresses unresponded queries about badges functionality on asknetdata
Summary by cubic
Add comprehensive documentation for Netdata Badges (/api/v1/badge.svg), covering usage, parameters, examples, color options, access control, troubleshooting, performance, auto-refresh (embed/iframe), GitHub caching limits, and a character-escaping table. Aligns the docs with source code (correct operators/defaults, text color defaults, special units, expanded grouping methods and query options, alert states including UNINITIALIZED and REMOVED) and registers the page in map.csv.
Written for commit 43672ef. Summary will update on new commits.