Update to Better Stack
Snapshot Nov 13, 2026 · 12:08 UTC · version 1.3.14
Collection source: downloaded plugin package.
Instructions updated for chart-generation
Skill instructions — Now says: | Example Output | | --------- | ------------------------------------------ | --------------------- | | `percent` | A 0-1 ratio,...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Skill instructions
Nov 11, 2026 · 06:08 UTC
| Example Output | | --------- | -------------------------- | -------------- | | `percent` | Percentage (0-1 to 0-100%) | 75% | | `auto` | Auto-detect | varies | | `none` | Raw number ...
Nov 13, 2026 · 12:08 UTC
| Example Output | | --------- | ------------------------------------------ | --------------------- | | `percent` | A 0-1 ratio, multiplied by 100 for display | `0.75` renders as 75% | | `auto` | Auto-detect ...
Supporting files
Nov 11, 2026 · 06:08 UTC
[]
Nov 13, 2026 · 12:08 UTC
[{"relative_path":"references/common-mistakes.md","size_in_bytes":8615}]
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -71,11 +71,30 @@ ### Other -| Unit | Description | Example Output | -| --------- | -------------------------- | -------------- | -| `percent` | Percentage (0-1 to 0-100%) | 75% | -| `auto` | Auto-detect | varies | -| `none` | Raw number | 1234.56 | +| Unit | Description | Example Output | +| --------- | ------------------------------------------ | --------------------- | +| `percent` | A 0-1 ratio, multiplied by 100 for display | `0.75` renders as 75% | +| `auto` | Auto-detect | varies | +| `none` | Raw number | 1234.56 | + +### Percent takes 0-1 ratios + +`unit: "percent"` multiplies the query's value by 100, so the query must return a 0-1 ratio. Never multiply by 100 in the query: `* 100` with `percent` renders 75% as 7500%. When a metric is already reported 0-100 (e.g. `cpu_percent`), divide it by 100. + +```sql +-- GOOD: system_cpu_utilization_ratio is 0-1, so 0.75 renders as 75% +avgMerge(value_avg) AS "CPU usage" + +-- BAD with unit: "percent": renders 75% as 7500% +avgMerge(value_avg) * 100 AS "CPU usage" + +-- GOOD: a metric that is already 0-100, divided back to 0-1 +avgMerge(value_avg) / 100 AS "CPU usage" +``` + +Every number you set on a `percent` chart is a 0-1 ratio too: `y_axis_max: 1`, gauge `max: 1`, `color_upper_threshold: 0.9`, and a chart alert's threshold `value: 0.9` for 90%. + +The exception is `stacking: "stack_to_100"` on a bar chart: it sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares). ## Column Mapping @@ -145,10 +164,10 @@ ### Y-Axis Bounds -| Setting | Purpose | Example | -| ------------ | ------------- | ----------------------------------------- | -| `y_axis_min` | Force minimum | `0` for percentages | -| `y_axis_max` | Force maximum | `1` for 0-1 ratios, `100` for percentages | +| Setting | Purpose | Example | +| ------------ | ------------- | ---------------------------------------------------------------------- | +| `y_axis_min` | Force minimum | `0` for percentages | +| `y_axis_max` | Force maximum | `1` with `unit: "percent"` (0-1 data), `100` for 0-100 data without it | **Important**: For percentage data calculated as ratio (0-1), set `y_axis_max: 1`, NOT `100`. @@ -169,11 +188,11 @@ ## Stacking (`stacking`) - Line/Bar Charts -| Value | Behavior | -| -------------- | ----------------------------------------------- | -| `dont_stack` | Overlapping series (line default) | -| `stack` | Stacked series (bar default) | -| `stack_to_100` | Percentage stacking (auto-sets unit to percent) | +| Value | Behavior | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `dont_stack` | Overlapping series (line default) | +| `stack` | Stacked series (bar default) | +| `stack_to_100` | Percentage stacking: sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares) | **Rule**: Stack only series that are **non-overlapping parts of a whole** (e.g. memory `Used + Cache + Free` — and exclude the `Total` series itself, it double-counts its parts). The full stack-vs-don't decision rules (including the default-to-stack style for line charts) live in the `dashboard-builder` skill's Stacking Rules — when both skills are loaded, follow those. @@ -284,15 +303,7 @@ ## Common Mistakes -| Mistake | Correct Approach | -| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `y_axis_max: 100` for 0-1 ratio | Use `y_axis_max: 1` | -| Forgetting `series_column` | Set when query has grouping column | -| Using `%` as unit | Use `percent` | -| Using `bytes` as unit | Use `B_si` or `B_iec` | -| Defining a custom unit when a built-in exists | Prefer built-in units (`B_si`, `B_iec`, `B_si/s`, `ms`, `s`, `percent`, `shortened`, `e/s`, `rps`, etc.). Built-ins auto-scale (`B_si/s` renders as `kB/s`, `MB/s`, `GB/s` as values grow); custom-string units stay fixed and read worse at scale. Only define a custom unit when nothing in the built-in list fits the metric. **If you ever find yourself typing a built-in name (`shortened`, `percent`, `ms`, etc.) as the custom-unit string, stop — you're meant to set the `unit` field to that built-in value, not the custom-string field.** Both fields exist; using the wrong one breaks auto-scaling. **For network throughput use `B_si/s`** — `B_iec/s` is accepted by the chart formatter but is NOT in the UI's unit dropdown and gets rendered as raw `B_iec/s` instead of `MB/s`. | -| Slashes in series names (`Read / Write`, `vm-1 / read`) | Use a space or dash instead (`Read Write`, `vm-1 read`). Slashes read as path separators and clutter the legend; the structure is conveyed by the series naming pattern, not the punctuation. | -| Legend would display only the literal word `"value"` (single un-aliased series) | Set `legend: "hidden"`. A legend that just says `value` adds no information and clutters the chart. Aliased series (`UNION ALL` with `'Read' AS series` / `'Write' AS series`) keep the legend on — the labels carry meaning. | +Read `references/common-mistakes.md` (in this skill's directory) before you create or edit a chart: it lists the settings and query mistakes that break charts (units, percent ratios, legends, series names, axis bounds) and the correct approach for each. ## Dashboard Layout
Full technical diff · 2 changed fields
changed /included_files
[]
[
{
"relative_path": "references/common-mistakes.md",
"size_in_bytes": 8615
}
]changed /skill_md_contents
"---\nname: chart-generation\ndescription: Complete reference for chart types, units, and settings on Better Stack dashboards. Load right before creating charts - after the queries are built with the query skills.\n---\n\n# Chart Generation Guide\n\nThis guide covers everything needed to create properly configured charts using the `add_chart_to_dashboard` and `edit_chart` tools. `chart_building_help` has the server's current reference.\n\nTo make a chart **filterable**, define a template variable with `set_dashboard_variable`, then reference it in the query as `{{var}}` (required) or `[[ ... {{var}} ... ]]` (optional). See the `dashboard-builder` skill's \"Dashboard template variables\" section.\n\n## Chart Types\n\n| Type | Use Case | Key Requirement |\n| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| `line_chart` | Time-series trends, metrics over time | Query must have `time` column |\n| `bar_chart` | Comparisons, distributions | Works with time or categories |\n| `number_chart` | Single KPI, current value | Shows latest/aggregated value |\n| `table_chart` | Detailed data, logs, breakdowns | Any columnar data |\n| `pie_chart` | Distribution, proportions | Needs series + value columns |\n| `heatmap_chart` | Correlation, density over time | Needs time, series, value |\n| `scatter_chart` | Correlation between variables | X/Y numeric columns |\n| `gauge_chart` | Percentage metrics (0-1 range) | Single value, use `unit: \"percent\"` |\n| `map_chart` | Geographic distribution (by IP, airport, city, or country) | Value column + a `location()` column, grouped by location. Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Fleet overview — one colored hexagon per entity (host map) | One row per entity: value column + label column. Load `map-hierarchy-charts` skill |\n| `static_text_chart` | Markdown text, notes, documentation | Pass Markdown in `query` param |\n\nSee `metrics-query` skill for query syntax.\n\nFunnels (`funnel_chart`, `funnel_trend_chart`) are not dashboard charts: they live in Explore, built from steps in the Better Stack UI.\n\n## Units Reference\n\n### Data Size\n\n| Unit | Description |\n| ---------------------------- | -------------------------- |\n| `B_si` | Bytes (SI: KB, MB, GB) |\n| `B_iec` | Bytes (IEC: KiB, MiB, GiB) |\n| `kB`, `MB`, `GB`, `TB`, `PB` | Fixed unit |\n\n### Data Transfer Rate\n\n| Unit | Description |\n| ---------------------------- | --------------------------------------------- |\n| `B_si/s` | Bytes per second (auto-scale) |\n| `kB/s`, `MB/s`, `GB/s` | Fixed rate unit |\n| `bit_si/s` | Bits per second (auto-scale: bps, kbps, Mbps) |\n| `kbit/s`, `Mbit/s`, `Gbit/s` | Fixed rate unit (renders as kbps, Mbps, Gbps) |\n\n### Duration\n\n| Unit | Description |\n| ---- | ------------ |\n| `ns` | Nanoseconds |\n| `μs` | Microseconds |\n| `ms` | Milliseconds |\n| `s` | Seconds |\n| `m` | Minutes |\n| `h` | Hours |\n| `d` | Days |\n\n### Rates & Counts\n\n| Unit | Description | Example Output |\n| ----------- | -------------------- | -------------- |\n| `shortened` | Auto-scale (K, M, B) | 1.5K, 2.3M |\n| `e/s` | Events per second | 150 e/s |\n| `rps` | Requests per second | 1.2K rps |\n| `rpm` | Requests per minute | 72K rpm |\n\n### Other\n\n| Unit | Description | Example Output |\n| --------- | -------------------------- | -------------- |\n| `percent` | Percentage (0-1 to 0-100%) | 75% |\n| `auto` | Auto-detect | varies |\n| `none` | Raw number | 1234.56 |\n\n## Column Mapping\n\n### Core Columns\n\n| Setting | Purpose | Default |\n| --------------- | ----------------------------------- | ----------- |\n| `time_column` | Column for X-axis time | `\"time\"` |\n| `series_column` | Column that groups data into series | `\"series\"` |\n| `value_columns` | Columns with numeric values to plot | `[\"value\"]` |\n\nThese settings are optional — inferred from query results when not provided.\n\n### `value_columns`\n\n`value_columns` MUST exactly match the SQL column alias. If the query says `AS \"Operations\"`, then `value_columns: [\"Operations\"]`. A mismatch makes the chart appear empty because it can't find the data column — this is the #1 cause of empty charts. Never leave `value_columns` as the default `[\"value\"]` when the SQL uses a descriptive alias.\n\nFor single-series charts, use a descriptive alias (not `AS value`):\n\n```sql\nSELECT {{time}} AS time, avgMerge(value_avg) AS \"Memory usage\" FROM ...\n-- value_columns: [\"Memory usage\"]\n```\n\n**`AS value` is FORBIDDEN as the metric alias for ANY chart that renders a legend.** The chart engine displays the column alias in the legend when there's no `series_column`, or as the y-axis label / hover tooltip alongside series names when there IS one. A legend or hover that reads \"value\" is a visible bug. Always alias as the chart title (or a tighter version of it):\n\n- Chart \"Request rate\" → `AS \"Request rate\"`, `value_columns: [\"Request rate\"]`\n- Chart \"Memory available\" → `AS \"Memory available\"`, `value_columns: [\"Memory available\"]`\n- Chart \"Response time by app\" → `AS \"Response time\"`, `value_columns: [\"Response time\"]`\n\nThis applies to single-series AND multi-series charts.\n\n### `series_column` — auto-inferred, set explicitly to control\n\nThe backend **auto-infers `series_column` from query result columns when you omit it.** Omitting it does NOT prevent it from being set — to disable it you must explicitly pass `series_column: \"\"`.\n\n- **Set to `\"series\"`** when the query has a `GROUP BY` on a label/tag aliased as `series` (e.g., `label('instance_name') AS series ... GROUP BY time, series`).\n- **Set to `\"\"` (empty string)** for charts that should have NO series grouping:\n - `number_chart` with a single aggregate value\n - single-aggregate error rate ratios (`errors / total`)\n - any query whose output has no column intended as a grouping label\n\nIf `series_column` is set incorrectly, the chart engine interprets data values as series names, producing broken visuals with garbage labels.\n\n## Axis Configuration\n\n### X-Axis Type (`x_axis_type`)\n\n| Value | Use Case |\n| ---------- | -------------------------- |\n| `time` | Time-series data (default) |\n| `category` | Discrete categories |\n| `value` | Continuous numeric axis |\n\nAllowed per chart type: `line_chart` time/value; `bar_chart` and `heatmap_chart` time/category; `scatter_chart` all three. **A line/bar chart with `x_axis_type` other than `time` can't have chart alerts.**\n\n### Y-Axis Type (`y_axis_type`) — scatter only\n\n`scatter_chart` also takes `y_axis_type`: `value` (numeric Y axis, default) or `category` (evenly spaced rows). Other chart types ignore it.\n\n### Y-Axis Scale (`y_axis_scale`)\n\n| Value | Use Case |\n| -------- | ------------------------------------------ |\n| `linear` | Most data (default) |\n| `log` | Data spanning multiple orders of magnitude |\n\n### Y-Axis Bounds\n\n| Setting | Purpose | Example |\n| ------------ | ------------- | ----------------------------------------- |\n| `y_axis_min` | Force minimum | `0` for percentages |\n| `y_axis_max` | Force maximum | `1` for 0-1 ratios, `100` for percentages |\n\n**Important**: For percentage data calculated as ratio (0-1), set `y_axis_max: 1`, NOT `100`.\n\n## Handling Missing Values (`treat_missing_values`)\n\n**Default: `connected` for non-stacked, `previous` for stacked.** Only deviate when the metric's semantics genuinely require it.\n\n| Value | When to use |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `connected` | **Default for non-stacked.** Bridges polling gaps — for rates, gauges, percentages, latencies. Missing poll ≠ zero. |\n| `previous` | **Default for stacked.** `connected` breaks stacking (sawtooth collapse). Step-shapes between samples. |\n| `zero` | Sparse-event charts where a missing bucket really means \"zero events\" (rare errors, throttle counts, deadlocks). Or `.fill(0)` source. |\n| `disconnected` | Detecting outages — when showing the gap itself is the signal. |\n\n**Critical for cloud-pulled metrics (Azure / GCP / AWS / CloudWatch / Prometheus-pull)**: missing data ≠ zero events. These APIs poll on a schedule and occasionally miss a bucket. Using `zero` creates spurious dips that look like outages. Default to `connected` and only switch to `zero` when the source truly fills zeros.\n\n**Stacking restriction**: when `stacking` is `\"stack\"` or `\"stack_to_100\"`, only `\"previous\"` and `\"zero\"` are available. `\"connected\"` and `\"disconnected\"` are not supported for stacked charts.\n\n## Stacking (`stacking`) - Line/Bar Charts\n\n| Value | Behavior |\n| -------------- | ----------------------------------------------- |\n| `dont_stack` | Overlapping series (line default) |\n| `stack` | Stacked series (bar default) |\n| `stack_to_100` | Percentage stacking (auto-sets unit to percent) |\n\n**Rule**: Stack only series that are **non-overlapping parts of a whole** (e.g. memory `Used + Cache + Free` — and exclude the `Total` series itself, it double-counts its parts). The full stack-vs-don't decision rules (including the default-to-stack style for line charts) live in the `dashboard-builder` skill's Stacking Rules — when both skills are loaded, follow those.\n\n## Legend Placement\n\nPrefer `\"shown_below\"` placement. Options: `hidden`, `shown_below`, `shown_below_with_statistics` (line/bar/scatter: renders min/mean/max next to each series name), `shown_right`.\n\n## Chart-Specific Settings\n\n| Chart Type | Key Settings |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `line_chart` | `stacking` per Stacking section (`dashboard-builder` defaults lines to `stack`); `treat_missing_values`: `\"connected\"` non-stacked / `\"previous\"` stacked; `show_previous_period` overlays the prior period for comparison |\n| `bar_chart` | `stacking: \"stack\"`, `orientation: \"vertical\"` or `\"horizontal\"` |\n| `number_chart` | Coloring via `color_mode` (load `chart-styling` skill). **Series labels are never displayed** — the chart title is the only visible label - make title descriptive. **Include `{{time}}`** — number charts render a line-chart in background. |\n| `table_chart` | See **Table Chart Settings** below |\n| `pie_chart` | Requires `series_column` and `value_columns` |\n| `gauge_chart` | `min` (default 0) and `max` (the goal value, default 1) — set both explicitly. For 0-1 percentage values use `unit: \"percent\"` with `max: 1` |\n| `heatmap_chart` | `time_column` (X) + `x_axis_type`, `series_column` (Y) + `series_unit` (Y-label unit), single `value_columns` entry (cell color), `heatmap_color_mode` (`chart-styling` skill) |\n| `scatter_chart` | `time_column` (X) + `x_axis_type`, `value_columns` (Y) + `y_axis_type`, `series_column` groups points, `point_size_column` sizes them (default `\"size\"`) |\n| `map_chart` | Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Load `map-hierarchy-charts` skill |\n\nAll charts support: `unit` (+ `custom_unit: true` for a literal suffix outside the supported list), `decimal_places: 2`, `legend`. Exception: `table_chart` ignores the chart-level `unit` — use `column_units`.\n\n## Styling & advanced settings\n\nSeries colors and order, number chart coloring thresholds, heatmap color categories (`heatmap_color_mode` + `value_categories`), gauge bounds, y-axis tuning (`y_axis_auto_range`, log scale), `show_previous_period`, and the full per-key settings reference with cross-setting gotchas: load the `chart-styling` skill.\n\n## Bar Chart Configuration\n\n**Two types of bar charts — configure each differently:**\n\n1. **Category bar charts** (toplists, rankings) — NO time dimension:\n - `x_axis_type: \"category\"` (NOT \"time\" — there is no time column)\n - `time_column: \"series\"` (point to the category/grouping column, NOT \"time\")\n - `orientation: \"horizontal\"` (category labels are usually names)\n - Query has NO `{{time}}`, groups by a tag only\n\n2. **Time-series bar charts** (values over time) — HAS time dimension:\n - `x_axis_type: \"time\"` (default)\n - `orientation: \"vertical\"`\n - Query has `{{time}} AS time` and `GROUP BY time, series`\n\n**Common mistakes:**\n\n- Using `x_axis_type: \"time\"` on a category bar chart — breaks rendering (no time column exists)\n- Using `time_column: \"time\"` on a category bar chart — must be `\"series\"` (the grouping column)\n- Always check: does the query have `{{time}}`? No -> `x_axis_type: \"category\"` + `time_column: \"series\"`\n\n## Table Chart Settings\n\nTable charts format **each column independently** — they ignore the chart-level `unit` setting. Configure per-column units and progress bar highlighting via the settings object.\n\n### `column_units`\n\nSet units for individual columns. Each key is the column alias from the query, value is an object with `unit` and `custom_unit`:\n\n```json\n{\n \"column_units\": {\n \"CPU usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Memory usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Uptime\": { \"unit\": \"s\", \"custom_unit\": false },\n \"Disk used\": { \"unit\": \"B_si\", \"custom_unit\": false }\n }\n}\n```\n\nColumn names must exactly match the SQL alias. The `unit` values are the same as chart-level units (see Units Reference above).\n\n### `percentage_highlight_columns`\n\nAdd colored progress bar backgrounds to percentage columns (0-1 range values). Pass an array of column names:\n\n```json\n{\n \"percentage_highlight_columns\": [\"CPU usage\", \"Memory usage\"]\n}\n```\n\nThis renders a colored horizontal bar behind each cell value, making it easy to spot high/low values at a glance. Only use for columns that contain 0-1 ratio values displayed as percentages.\n\n## Map & Hierarchy Charts\n\n`map_chart` and `hierarchy_chart` are not time-series and have their own query shapes and settings — load the `map-hierarchy-charts` skill before creating either.\n\n## Chart Title Rules\n\n- Always sentence case (\"CPU utilization by service\", not \"CPU Utilization By Service\"). Never units in titles — bare or parenthesised — the `unit` setting renders the suffix; titles say _what_, not _how much_ (\"CPU utilization\", not \"CPU utilization (%)\").\n- Never abbreviate words (\"Average query latency\", not \"Avg query latency\"). Universal acronyms (CPU, HTTP, DNS, ...) are fine; narrower ones (NIC, SDK, SLO, ADLS) are not — if you'd hesitate to use it in onboarding documentation, spell it out. Applies to titles AND tooltips.\n- The full naming rules (abbreviation list, domain acronyms, parentheses ban, \"X by Y\" phrasing, \"&\" vs \"and\") live in the `dashboard-builder` skill — follow them for every dashboard, section, and chart title.\n\n## Explanation (tooltip)\n\nShows as a tooltip next to the chart title. Use rarely — charts must be comprehensible without it. A tooltip earns its place only by teaching something the chart can't show on its own: a non-obvious threshold (\"DiskPressure flips at 85% used — once tripped, kubelet evicts pods until usage drops\"), an invariant (\"Capture backlog > 0 means the pipeline is falling behind\"), a debugging hint, or a one-clause definition of an unfamiliar term used in the title (PTU, DLQ, ...). If you can't meet that bar, **leave the field empty** — the chart is better without filler.\n\n**Forbidden content** (these belong on the chart visually, not in prose):\n\n- How the metric is computed — aggregations, ratios, per-tag fan-outs are chart properties, not tooltip topics\n- That the value reflects the selected time window (every chart does)\n- Paraphrases of the chart title (\"Availability — shows the availability of the resource\" adds zero; cut it)\n- Unit explanations or conversions (the `unit` setting handles that)\n- What the legend already shows\n- Unexplained abbreviations or internal-sounding jargon (\"tail latency events\", \"poison-message queue\", \"AppLevelReconnectStorm\") — write plain English a customer reading the dashboard for the first time understands\n- Anything pointing outside the dashboard — other tools, how the dashboard was sourced, build/review process, \"previously this was X\". The customer sees only the dashboard; it must be self-contained. This rule applies to titles, section titles, and descriptions too.\n\n**Punctuation:** single-sentence tooltip → no trailing full-stop; 2+ sentences → every sentence ends with one. No parentheses. No code-shaped symbols (`=`, `→`, `&`, ASCII art) — write words (\"caps at 100\", not \"caps = 100\"); real numbers (\"above 85%\") and conventional abbreviations (`vs.`, `e.g.`) are fine. `vs` always with a period — in tooltips and titles.\n\n## Common Mistakes\n\n| Mistake | Correct Approach |\n| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `y_axis_max: 100` for 0-1 ratio | Use `y_axis_max: 1` |\n| Forgetting `series_column` | Set when query has grouping column |\n| Using `%` as unit | Use `percent` |\n| Using `bytes` as unit | Use `B_si` or `B_iec` |\n| Defining a custom unit when a built-in exists | Prefer built-in units (`B_si`, `B_iec`, `B_si/s`, `ms`, `s`, `percent`, `shortened`, `e/s`, `rps`, etc.). Built-ins auto-scale (`B_si/s` renders as `kB/s`, `MB/s`, `GB/s` as values grow); custom-string units stay fixed and read worse at scale. Only define a custom unit when nothing in the built-in list fits the metric. **If you ever find yourself typing a built-in name (`shortened`, `percent`, `ms`, etc.) as the custom-unit string, stop — you're meant to set the `unit` field to that built-in value, not the custom-string field.** Both fields exist; using the wrong one breaks auto-scaling. **For network throughput use `B_si/s`** — `B_iec/s` is accepted by the chart formatter but is NOT in the UI's unit dropdown and gets rendered as raw `B_iec/s` instead of `MB/s`. |\n| Slashes in series names (`Read / Write`, `vm-1 / read`) | Use a space or dash instead (`Read Write`, `vm-1 read`). Slashes read as path separators and clutter the legend; the structure is conveyed by the series naming pattern, not the punctuation. |\n| Legend would display only the literal word `\"value\"` (single un-aliased series) | Set `legend: \"hidden\"`. A legend that just says `value` adds no information and clutters the chart. Aliased series (`UNION ALL` with `'Read' AS series` / `'Write' AS series`) keep the legend on — the labels carry meaning. |\n\n## Dashboard Layout\n\nSee `dashboard-layout` skill for layout rules, row templates, coordinate math, and the mandatory planning process.\n\n## Critical checklist\n\nBefore creating each chart:\n\n- [ ] Query executed and data verified that its not all null\n""---\nname: chart-generation\ndescription: Complete reference for chart types, units, and settings on Better Stack dashboards. Load right before creating charts - after the queries are built with the query skills.\n---\n\n# Chart Generation Guide\n\nThis guide covers everything needed to create properly configured charts using the `add_chart_to_dashboard` and `edit_chart` tools. `chart_building_help` has the server's current reference.\n\nTo make a chart **filterable**, define a template variable with `set_dashboard_variable`, then reference it in the query as `{{var}}` (required) or `[[ ... {{var}} ... ]]` (optional). See the `dashboard-builder` skill's \"Dashboard template variables\" section.\n\n## Chart Types\n\n| Type | Use Case | Key Requirement |\n| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| `line_chart` | Time-series trends, metrics over time | Query must have `time` column |\n| `bar_chart` | Comparisons, distributions | Works with time or categories |\n| `number_chart` | Single KPI, current value | Shows latest/aggregated value |\n| `table_chart` | Detailed data, logs, breakdowns | Any columnar data |\n| `pie_chart` | Distribution, proportions | Needs series + value columns |\n| `heatmap_chart` | Correlation, density over time | Needs time, series, value |\n| `scatter_chart` | Correlation between variables | X/Y numeric columns |\n| `gauge_chart` | Percentage metrics (0-1 range) | Single value, use `unit: \"percent\"` |\n| `map_chart` | Geographic distribution (by IP, airport, city, or country) | Value column + a `location()` column, grouped by location. Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Fleet overview — one colored hexagon per entity (host map) | One row per entity: value column + label column. Load `map-hierarchy-charts` skill |\n| `static_text_chart` | Markdown text, notes, documentation | Pass Markdown in `query` param |\n\nSee `metrics-query` skill for query syntax.\n\nFunnels (`funnel_chart`, `funnel_trend_chart`) are not dashboard charts: they live in Explore, built from steps in the Better Stack UI.\n\n## Units Reference\n\n### Data Size\n\n| Unit | Description |\n| ---------------------------- | -------------------------- |\n| `B_si` | Bytes (SI: KB, MB, GB) |\n| `B_iec` | Bytes (IEC: KiB, MiB, GiB) |\n| `kB`, `MB`, `GB`, `TB`, `PB` | Fixed unit |\n\n### Data Transfer Rate\n\n| Unit | Description |\n| ---------------------------- | --------------------------------------------- |\n| `B_si/s` | Bytes per second (auto-scale) |\n| `kB/s`, `MB/s`, `GB/s` | Fixed rate unit |\n| `bit_si/s` | Bits per second (auto-scale: bps, kbps, Mbps) |\n| `kbit/s`, `Mbit/s`, `Gbit/s` | Fixed rate unit (renders as kbps, Mbps, Gbps) |\n\n### Duration\n\n| Unit | Description |\n| ---- | ------------ |\n| `ns` | Nanoseconds |\n| `μs` | Microseconds |\n| `ms` | Milliseconds |\n| `s` | Seconds |\n| `m` | Minutes |\n| `h` | Hours |\n| `d` | Days |\n\n### Rates & Counts\n\n| Unit | Description | Example Output |\n| ----------- | -------------------- | -------------- |\n| `shortened` | Auto-scale (K, M, B) | 1.5K, 2.3M |\n| `e/s` | Events per second | 150 e/s |\n| `rps` | Requests per second | 1.2K rps |\n| `rpm` | Requests per minute | 72K rpm |\n\n### Other\n\n| Unit | Description | Example Output |\n| --------- | ------------------------------------------ | --------------------- |\n| `percent` | A 0-1 ratio, multiplied by 100 for display | `0.75` renders as 75% |\n| `auto` | Auto-detect | varies |\n| `none` | Raw number | 1234.56 |\n\n### Percent takes 0-1 ratios\n\n`unit: \"percent\"` multiplies the query's value by 100, so the query must return a 0-1 ratio. Never multiply by 100 in the query: `* 100` with `percent` renders 75% as 7500%. When a metric is already reported 0-100 (e.g. `cpu_percent`), divide it by 100.\n\n```sql\n-- GOOD: system_cpu_utilization_ratio is 0-1, so 0.75 renders as 75%\navgMerge(value_avg) AS \"CPU usage\"\n\n-- BAD with unit: \"percent\": renders 75% as 7500%\navgMerge(value_avg) * 100 AS \"CPU usage\"\n\n-- GOOD: a metric that is already 0-100, divided back to 0-1\navgMerge(value_avg) / 100 AS \"CPU usage\"\n```\n\nEvery number you set on a `percent` chart is a 0-1 ratio too: `y_axis_max: 1`, gauge `max: 1`, `color_upper_threshold: 0.9`, and a chart alert's threshold `value: 0.9` for 90%.\n\nThe exception is `stacking: \"stack_to_100\"` on a bar chart: it sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares).\n\n## Column Mapping\n\n### Core Columns\n\n| Setting | Purpose | Default |\n| --------------- | ----------------------------------- | ----------- |\n| `time_column` | Column for X-axis time | `\"time\"` |\n| `series_column` | Column that groups data into series | `\"series\"` |\n| `value_columns` | Columns with numeric values to plot | `[\"value\"]` |\n\nThese settings are optional — inferred from query results when not provided.\n\n### `value_columns`\n\n`value_columns` MUST exactly match the SQL column alias. If the query says `AS \"Operations\"`, then `value_columns: [\"Operations\"]`. A mismatch makes the chart appear empty because it can't find the data column — this is the #1 cause of empty charts. Never leave `value_columns` as the default `[\"value\"]` when the SQL uses a descriptive alias.\n\nFor single-series charts, use a descriptive alias (not `AS value`):\n\n```sql\nSELECT {{time}} AS time, avgMerge(value_avg) AS \"Memory usage\" FROM ...\n-- value_columns: [\"Memory usage\"]\n```\n\n**`AS value` is FORBIDDEN as the metric alias for ANY chart that renders a legend.** The chart engine displays the column alias in the legend when there's no `series_column`, or as the y-axis label / hover tooltip alongside series names when there IS one. A legend or hover that reads \"value\" is a visible bug. Always alias as the chart title (or a tighter version of it):\n\n- Chart \"Request rate\" → `AS \"Request rate\"`, `value_columns: [\"Request rate\"]`\n- Chart \"Memory available\" → `AS \"Memory available\"`, `value_columns: [\"Memory available\"]`\n- Chart \"Response time by app\" → `AS \"Response time\"`, `value_columns: [\"Response time\"]`\n\nThis applies to single-series AND multi-series charts.\n\n### `series_column` — auto-inferred, set explicitly to control\n\nThe backend **auto-infers `series_column` from query result columns when you omit it.** Omitting it does NOT prevent it from being set — to disable it you must explicitly pass `series_column: \"\"`.\n\n- **Set to `\"series\"`** when the query has a `GROUP BY` on a label/tag aliased as `series` (e.g., `label('instance_name') AS series ... GROUP BY time, series`).\n- **Set to `\"\"` (empty string)** for charts that should have NO series grouping:\n - `number_chart` with a single aggregate value\n - single-aggregate error rate ratios (`errors / total`)\n - any query whose output has no column intended as a grouping label\n\nIf `series_column` is set incorrectly, the chart engine interprets data values as series names, producing broken visuals with garbage labels.\n\n## Axis Configuration\n\n### X-Axis Type (`x_axis_type`)\n\n| Value | Use Case |\n| ---------- | -------------------------- |\n| `time` | Time-series data (default) |\n| `category` | Discrete categories |\n| `value` | Continuous numeric axis |\n\nAllowed per chart type: `line_chart` time/value; `bar_chart` and `heatmap_chart` time/category; `scatter_chart` all three. **A line/bar chart with `x_axis_type` other than `time` can't have chart alerts.**\n\n### Y-Axis Type (`y_axis_type`) — scatter only\n\n`scatter_chart` also takes `y_axis_type`: `value` (numeric Y axis, default) or `category` (evenly spaced rows). Other chart types ignore it.\n\n### Y-Axis Scale (`y_axis_scale`)\n\n| Value | Use Case |\n| -------- | ------------------------------------------ |\n| `linear` | Most data (default) |\n| `log` | Data spanning multiple orders of magnitude |\n\n### Y-Axis Bounds\n\n| Setting | Purpose | Example |\n| ------------ | ------------- | ---------------------------------------------------------------------- |\n| `y_axis_min` | Force minimum | `0` for percentages |\n| `y_axis_max` | Force maximum | `1` with `unit: \"percent\"` (0-1 data), `100` for 0-100 data without it |\n\n**Important**: For percentage data calculated as ratio (0-1), set `y_axis_max: 1`, NOT `100`.\n\n## Handling Missing Values (`treat_missing_values`)\n\n**Default: `connected` for non-stacked, `previous` for stacked.** Only deviate when the metric's semantics genuinely require it.\n\n| Value | When to use |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `connected` | **Default for non-stacked.** Bridges polling gaps — for rates, gauges, percentages, latencies. Missing poll ≠ zero. |\n| `previous` | **Default for stacked.** `connected` breaks stacking (sawtooth collapse). Step-shapes between samples. |\n| `zero` | Sparse-event charts where a missing bucket really means \"zero events\" (rare errors, throttle counts, deadlocks). Or `.fill(0)` source. |\n| `disconnected` | Detecting outages — when showing the gap itself is the signal. |\n\n**Critical for cloud-pulled metrics (Azure / GCP / AWS / CloudWatch / Prometheus-pull)**: missing data ≠ zero events. These APIs poll on a schedule and occasionally miss a bucket. Using `zero` creates spurious dips that look like outages. Default to `connected` and only switch to `zero` when the source truly fills zeros.\n\n**Stacking restriction**: when `stacking` is `\"stack\"` or `\"stack_to_100\"`, only `\"previous\"` and `\"zero\"` are available. `\"connected\"` and `\"disconnected\"` are not supported for stacked charts.\n\n## Stacking (`stacking`) - Line/Bar Charts\n\n| Value | Behavior |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `dont_stack` | Overlapping series (line default) |\n| `stack` | Stacked series (bar default) |\n| `stack_to_100` | Percentage stacking: sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares) |\n\n**Rule**: Stack only series that are **non-overlapping parts of a whole** (e.g. memory `Used + Cache + Free` — and exclude the `Total` series itself, it double-counts its parts). The full stack-vs-don't decision rules (including the default-to-stack style for line charts) live in the `dashboard-builder` skill's Stacking Rules — when both skills are loaded, follow those.\n\n## Legend Placement\n\nPrefer `\"shown_below\"` placement. Options: `hidden`, `shown_below`, `shown_below_with_statistics` (line/bar/scatter: renders min/mean/max next to each series name), `shown_right`.\n\n## Chart-Specific Settings\n\n| Chart Type | Key Settings |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `line_chart` | `stacking` per Stacking section (`dashboard-builder` defaults lines to `stack`); `treat_missing_values`: `\"connected\"` non-stacked / `\"previous\"` stacked; `show_previous_period` overlays the prior period for comparison |\n| `bar_chart` | `stacking: \"stack\"`, `orientation: \"vertical\"` or `\"horizontal\"` |\n| `number_chart` | Coloring via `color_mode` (load `chart-styling` skill). **Series labels are never displayed** — the chart title is the only visible label - make title descriptive. **Include `{{time}}`** — number charts render a line-chart in background. |\n| `table_chart` | See **Table Chart Settings** below |\n| `pie_chart` | Requires `series_column` and `value_columns` |\n| `gauge_chart` | `min` (default 0) and `max` (the goal value, default 1) — set both explicitly. For 0-1 percentage values use `unit: \"percent\"` with `max: 1` |\n| `heatmap_chart` | `time_column` (X) + `x_axis_type`, `series_column` (Y) + `series_unit` (Y-label unit), single `value_columns` entry (cell color), `heatmap_color_mode` (`chart-styling` skill) |\n| `scatter_chart` | `time_column` (X) + `x_axis_type`, `value_columns` (Y) + `y_axis_type`, `series_column` groups points, `point_size_column` sizes them (default `\"size\"`) |\n| `map_chart` | Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Load `map-hierarchy-charts` skill |\n\nAll charts support: `unit` (+ `custom_unit: true` for a literal suffix outside the supported list), `decimal_places: 2`, `legend`. Exception: `table_chart` ignores the chart-level `unit` — use `column_units`.\n\n## Styling & advanced settings\n\nSeries colors and order, number chart coloring thresholds, heatmap color categories (`heatmap_color_mode` + `value_categories`), gauge bounds, y-axis tuning (`y_axis_auto_range`, log scale), `show_previous_period`, and the full per-key settings reference with cross-setting gotchas: load the `chart-styling` skill.\n\n## Bar Chart Configuration\n\n**Two types of bar charts — configure each differently:**\n\n1. **Category bar charts** (toplists, rankings) — NO time dimension:\n - `x_axis_type: \"category\"` (NOT \"time\" — there is no time column)\n - `time_column: \"series\"` (point to the category/grouping column, NOT \"time\")\n - `orientation: \"horizontal\"` (category labels are usually names)\n - Query has NO `{{time}}`, groups by a tag only\n\n2. **Time-series bar charts** (values over time) — HAS time dimension:\n - `x_axis_type: \"time\"` (default)\n - `orientation: \"vertical\"`\n - Query has `{{time}} AS time` and `GROUP BY time, series`\n\n**Common mistakes:**\n\n- Using `x_axis_type: \"time\"` on a category bar chart — breaks rendering (no time column exists)\n- Using `time_column: \"time\"` on a category bar chart — must be `\"series\"` (the grouping column)\n- Always check: does the query have `{{time}}`? No -> `x_axis_type: \"category\"` + `time_column: \"series\"`\n\n## Table Chart Settings\n\nTable charts format **each column independently** — they ignore the chart-level `unit` setting. Configure per-column units and progress bar highlighting via the settings object.\n\n### `column_units`\n\nSet units for individual columns. Each key is the column alias from the query, value is an object with `unit` and `custom_unit`:\n\n```json\n{\n \"column_units\": {\n \"CPU usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Memory usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Uptime\": { \"unit\": \"s\", \"custom_unit\": false },\n \"Disk used\": { \"unit\": \"B_si\", \"custom_unit\": false }\n }\n}\n```\n\nColumn names must exactly match the SQL alias. The `unit` values are the same as chart-level units (see Units Reference above).\n\n### `percentage_highlight_columns`\n\nAdd colored progress bar backgrounds to percentage columns (0-1 range values). Pass an array of column names:\n\n```json\n{\n \"percentage_highlight_columns\": [\"CPU usage\", \"Memory usage\"]\n}\n```\n\nThis renders a colored horizontal bar behind each cell value, making it easy to spot high/low values at a glance. Only use for columns that contain 0-1 ratio values displayed as percentages.\n\n## Map & Hierarchy Charts\n\n`map_chart` and `hierarchy_chart` are not time-series and have their own query shapes and settings — load the `map-hierarchy-charts` skill before creating either.\n\n## Chart Title Rules\n\n- Always sentence case (\"CPU utilization by service\", not \"CPU Utilization By Service\"). Never units in titles — bare or parenthesised — the `unit` setting renders the suffix; titles say _what_, not _how much_ (\"CPU utilization\", not \"CPU utilization (%)\").\n- Never abbreviate words (\"Average query latency\", not \"Avg query latency\"). Universal acronyms (CPU, HTTP, DNS, ...) are fine; narrower ones (NIC, SDK, SLO, ADLS) are not — if you'd hesitate to use it in onboarding documentation, spell it out. Applies to titles AND tooltips.\n- The full naming rules (abbreviation list, domain acronyms, parentheses ban, \"X by Y\" phrasing, \"&\" vs \"and\") live in the `dashboard-builder` skill — follow them for every dashboard, section, and chart title.\n\n## Explanation (tooltip)\n\nShows as a tooltip next to the chart title. Use rarely — charts must be comprehensible without it. A tooltip earns its place only by teaching something the chart can't show on its own: a non-obvious threshold (\"DiskPressure flips at 85% used — once tripped, kubelet evicts pods until usage drops\"), an invariant (\"Capture backlog > 0 means the pipeline is falling behind\"), a debugging hint, or a one-clause definition of an unfamiliar term used in the title (PTU, DLQ, ...). If you can't meet that bar, **leave the field empty** — the chart is better without filler.\n\n**Forbidden content** (these belong on the chart visually, not in prose):\n\n- How the metric is computed — aggregations, ratios, per-tag fan-outs are chart properties, not tooltip topics\n- That the value reflects the selected time window (every chart does)\n- Paraphrases of the chart title (\"Availability — shows the availability of the resource\" adds zero; cut it)\n- Unit explanations or conversions (the `unit` setting handles that)\n- What the legend already shows\n- Unexplained abbreviations or internal-sounding jargon (\"tail latency events\", \"poison-message queue\", \"AppLevelReconnectStorm\") — write plain English a customer reading the dashboard for the first time understands\n- Anything pointing outside the dashboard — other tools, how the dashboard was sourced, build/review process, \"previously this was X\". The customer sees only the dashboard; it must be self-contained. This rule applies to titles, section titles, and descriptions too.\n\n**Punctuation:** single-sentence tooltip → no trailing full-stop; 2+ sentences → every sentence ends with one. No parentheses. No code-shaped symbols (`=`, `→`, `&`, ASCII art) — write words (\"caps at 100\", not \"caps = 100\"); real numbers (\"above 85%\") and conventional abbreviations (`vs.`, `e.g.`) are fine. `vs` always with a period — in tooltips and titles.\n\n## Common Mistakes\n\nRead `references/common-mistakes.md` (in this skill's directory) before you create or edit a chart: it lists the settings and query mistakes that break charts (units, percent ratios, legends, series names, axis bounds) and the correct approach for each.\n\n## Dashboard Layout\n\nSee `dashboard-layout` skill for layout rules, row templates, coordinate math, and the mandatory planning process.\n\n## Critical checklist\n\nBefore creating each chart:\n\n- [ ] Query executed and data verified that its not all null\n"Full snapshot data
{
"description": "Complete reference for chart types, units, and settings on Better Stack dashboards. Load right before creating charts - after the queries are built with the query skills.",
"included_files": [
{
"relative_path": "references/common-mistakes.md",
"size_in_bytes": 8615
}
],
"name": "chart-generation",
"skill_md_contents": "---\nname: chart-generation\ndescription: Complete reference for chart types, units, and settings on Better Stack dashboards. Load right before creating charts - after the queries are built with the query skills.\n---\n\n# Chart Generation Guide\n\nThis guide covers everything needed to create properly configured charts using the `add_chart_to_dashboard` and `edit_chart` tools. `chart_building_help` has the server's current reference.\n\nTo make a chart **filterable**, define a template variable with `set_dashboard_variable`, then reference it in the query as `{{var}}` (required) or `[[ ... {{var}} ... ]]` (optional). See the `dashboard-builder` skill's \"Dashboard template variables\" section.\n\n## Chart Types\n\n| Type | Use Case | Key Requirement |\n| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| `line_chart` | Time-series trends, metrics over time | Query must have `time` column |\n| `bar_chart` | Comparisons, distributions | Works with time or categories |\n| `number_chart` | Single KPI, current value | Shows latest/aggregated value |\n| `table_chart` | Detailed data, logs, breakdowns | Any columnar data |\n| `pie_chart` | Distribution, proportions | Needs series + value columns |\n| `heatmap_chart` | Correlation, density over time | Needs time, series, value |\n| `scatter_chart` | Correlation between variables | X/Y numeric columns |\n| `gauge_chart` | Percentage metrics (0-1 range) | Single value, use `unit: \"percent\"` |\n| `map_chart` | Geographic distribution (by IP, airport, city, or country) | Value column + a `location()` column, grouped by location. Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Fleet overview — one colored hexagon per entity (host map) | One row per entity: value column + label column. Load `map-hierarchy-charts` skill |\n| `static_text_chart` | Markdown text, notes, documentation | Pass Markdown in `query` param |\n\nSee `metrics-query` skill for query syntax.\n\nFunnels (`funnel_chart`, `funnel_trend_chart`) are not dashboard charts: they live in Explore, built from steps in the Better Stack UI.\n\n## Units Reference\n\n### Data Size\n\n| Unit | Description |\n| ---------------------------- | -------------------------- |\n| `B_si` | Bytes (SI: KB, MB, GB) |\n| `B_iec` | Bytes (IEC: KiB, MiB, GiB) |\n| `kB`, `MB`, `GB`, `TB`, `PB` | Fixed unit |\n\n### Data Transfer Rate\n\n| Unit | Description |\n| ---------------------------- | --------------------------------------------- |\n| `B_si/s` | Bytes per second (auto-scale) |\n| `kB/s`, `MB/s`, `GB/s` | Fixed rate unit |\n| `bit_si/s` | Bits per second (auto-scale: bps, kbps, Mbps) |\n| `kbit/s`, `Mbit/s`, `Gbit/s` | Fixed rate unit (renders as kbps, Mbps, Gbps) |\n\n### Duration\n\n| Unit | Description |\n| ---- | ------------ |\n| `ns` | Nanoseconds |\n| `μs` | Microseconds |\n| `ms` | Milliseconds |\n| `s` | Seconds |\n| `m` | Minutes |\n| `h` | Hours |\n| `d` | Days |\n\n### Rates & Counts\n\n| Unit | Description | Example Output |\n| ----------- | -------------------- | -------------- |\n| `shortened` | Auto-scale (K, M, B) | 1.5K, 2.3M |\n| `e/s` | Events per second | 150 e/s |\n| `rps` | Requests per second | 1.2K rps |\n| `rpm` | Requests per minute | 72K rpm |\n\n### Other\n\n| Unit | Description | Example Output |\n| --------- | ------------------------------------------ | --------------------- |\n| `percent` | A 0-1 ratio, multiplied by 100 for display | `0.75` renders as 75% |\n| `auto` | Auto-detect | varies |\n| `none` | Raw number | 1234.56 |\n\n### Percent takes 0-1 ratios\n\n`unit: \"percent\"` multiplies the query's value by 100, so the query must return a 0-1 ratio. Never multiply by 100 in the query: `* 100` with `percent` renders 75% as 7500%. When a metric is already reported 0-100 (e.g. `cpu_percent`), divide it by 100.\n\n```sql\n-- GOOD: system_cpu_utilization_ratio is 0-1, so 0.75 renders as 75%\navgMerge(value_avg) AS \"CPU usage\"\n\n-- BAD with unit: \"percent\": renders 75% as 7500%\navgMerge(value_avg) * 100 AS \"CPU usage\"\n\n-- GOOD: a metric that is already 0-100, divided back to 0-1\navgMerge(value_avg) / 100 AS \"CPU usage\"\n```\n\nEvery number you set on a `percent` chart is a 0-1 ratio too: `y_axis_max: 1`, gauge `max: 1`, `color_upper_threshold: 0.9`, and a chart alert's threshold `value: 0.9` for 90%.\n\nThe exception is `stacking: \"stack_to_100\"` on a bar chart: it sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares).\n\n## Column Mapping\n\n### Core Columns\n\n| Setting | Purpose | Default |\n| --------------- | ----------------------------------- | ----------- |\n| `time_column` | Column for X-axis time | `\"time\"` |\n| `series_column` | Column that groups data into series | `\"series\"` |\n| `value_columns` | Columns with numeric values to plot | `[\"value\"]` |\n\nThese settings are optional — inferred from query results when not provided.\n\n### `value_columns`\n\n`value_columns` MUST exactly match the SQL column alias. If the query says `AS \"Operations\"`, then `value_columns: [\"Operations\"]`. A mismatch makes the chart appear empty because it can't find the data column — this is the #1 cause of empty charts. Never leave `value_columns` as the default `[\"value\"]` when the SQL uses a descriptive alias.\n\nFor single-series charts, use a descriptive alias (not `AS value`):\n\n```sql\nSELECT {{time}} AS time, avgMerge(value_avg) AS \"Memory usage\" FROM ...\n-- value_columns: [\"Memory usage\"]\n```\n\n**`AS value` is FORBIDDEN as the metric alias for ANY chart that renders a legend.** The chart engine displays the column alias in the legend when there's no `series_column`, or as the y-axis label / hover tooltip alongside series names when there IS one. A legend or hover that reads \"value\" is a visible bug. Always alias as the chart title (or a tighter version of it):\n\n- Chart \"Request rate\" → `AS \"Request rate\"`, `value_columns: [\"Request rate\"]`\n- Chart \"Memory available\" → `AS \"Memory available\"`, `value_columns: [\"Memory available\"]`\n- Chart \"Response time by app\" → `AS \"Response time\"`, `value_columns: [\"Response time\"]`\n\nThis applies to single-series AND multi-series charts.\n\n### `series_column` — auto-inferred, set explicitly to control\n\nThe backend **auto-infers `series_column` from query result columns when you omit it.** Omitting it does NOT prevent it from being set — to disable it you must explicitly pass `series_column: \"\"`.\n\n- **Set to `\"series\"`** when the query has a `GROUP BY` on a label/tag aliased as `series` (e.g., `label('instance_name') AS series ... GROUP BY time, series`).\n- **Set to `\"\"` (empty string)** for charts that should have NO series grouping:\n - `number_chart` with a single aggregate value\n - single-aggregate error rate ratios (`errors / total`)\n - any query whose output has no column intended as a grouping label\n\nIf `series_column` is set incorrectly, the chart engine interprets data values as series names, producing broken visuals with garbage labels.\n\n## Axis Configuration\n\n### X-Axis Type (`x_axis_type`)\n\n| Value | Use Case |\n| ---------- | -------------------------- |\n| `time` | Time-series data (default) |\n| `category` | Discrete categories |\n| `value` | Continuous numeric axis |\n\nAllowed per chart type: `line_chart` time/value; `bar_chart` and `heatmap_chart` time/category; `scatter_chart` all three. **A line/bar chart with `x_axis_type` other than `time` can't have chart alerts.**\n\n### Y-Axis Type (`y_axis_type`) — scatter only\n\n`scatter_chart` also takes `y_axis_type`: `value` (numeric Y axis, default) or `category` (evenly spaced rows). Other chart types ignore it.\n\n### Y-Axis Scale (`y_axis_scale`)\n\n| Value | Use Case |\n| -------- | ------------------------------------------ |\n| `linear` | Most data (default) |\n| `log` | Data spanning multiple orders of magnitude |\n\n### Y-Axis Bounds\n\n| Setting | Purpose | Example |\n| ------------ | ------------- | ---------------------------------------------------------------------- |\n| `y_axis_min` | Force minimum | `0` for percentages |\n| `y_axis_max` | Force maximum | `1` with `unit: \"percent\"` (0-1 data), `100` for 0-100 data without it |\n\n**Important**: For percentage data calculated as ratio (0-1), set `y_axis_max: 1`, NOT `100`.\n\n## Handling Missing Values (`treat_missing_values`)\n\n**Default: `connected` for non-stacked, `previous` for stacked.** Only deviate when the metric's semantics genuinely require it.\n\n| Value | When to use |\n| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `connected` | **Default for non-stacked.** Bridges polling gaps — for rates, gauges, percentages, latencies. Missing poll ≠ zero. |\n| `previous` | **Default for stacked.** `connected` breaks stacking (sawtooth collapse). Step-shapes between samples. |\n| `zero` | Sparse-event charts where a missing bucket really means \"zero events\" (rare errors, throttle counts, deadlocks). Or `.fill(0)` source. |\n| `disconnected` | Detecting outages — when showing the gap itself is the signal. |\n\n**Critical for cloud-pulled metrics (Azure / GCP / AWS / CloudWatch / Prometheus-pull)**: missing data ≠ zero events. These APIs poll on a schedule and occasionally miss a bucket. Using `zero` creates spurious dips that look like outages. Default to `connected` and only switch to `zero` when the source truly fills zeros.\n\n**Stacking restriction**: when `stacking` is `\"stack\"` or `\"stack_to_100\"`, only `\"previous\"` and `\"zero\"` are available. `\"connected\"` and `\"disconnected\"` are not supported for stacked charts.\n\n## Stacking (`stacking`) - Line/Bar Charts\n\n| Value | Behavior |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `dont_stack` | Overlapping series (line default) |\n| `stack` | Stacked series (bar default) |\n| `stack_to_100` | Percentage stacking: sets `percent` itself and scales each bar to 100% when drawing, so its query returns raw values (counts, not shares) |\n\n**Rule**: Stack only series that are **non-overlapping parts of a whole** (e.g. memory `Used + Cache + Free` — and exclude the `Total` series itself, it double-counts its parts). The full stack-vs-don't decision rules (including the default-to-stack style for line charts) live in the `dashboard-builder` skill's Stacking Rules — when both skills are loaded, follow those.\n\n## Legend Placement\n\nPrefer `\"shown_below\"` placement. Options: `hidden`, `shown_below`, `shown_below_with_statistics` (line/bar/scatter: renders min/mean/max next to each series name), `shown_right`.\n\n## Chart-Specific Settings\n\n| Chart Type | Key Settings |\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `line_chart` | `stacking` per Stacking section (`dashboard-builder` defaults lines to `stack`); `treat_missing_values`: `\"connected\"` non-stacked / `\"previous\"` stacked; `show_previous_period` overlays the prior period for comparison |\n| `bar_chart` | `stacking: \"stack\"`, `orientation: \"vertical\"` or `\"horizontal\"` |\n| `number_chart` | Coloring via `color_mode` (load `chart-styling` skill). **Series labels are never displayed** — the chart title is the only visible label - make title descriptive. **Include `{{time}}`** — number charts render a line-chart in background. |\n| `table_chart` | See **Table Chart Settings** below |\n| `pie_chart` | Requires `series_column` and `value_columns` |\n| `gauge_chart` | `min` (default 0) and `max` (the goal value, default 1) — set both explicitly. For 0-1 percentage values use `unit: \"percent\"` with `max: 1` |\n| `heatmap_chart` | `time_column` (X) + `x_axis_type`, `series_column` (Y) + `series_unit` (Y-label unit), single `value_columns` entry (cell color), `heatmap_color_mode` (`chart-styling` skill) |\n| `scatter_chart` | `time_column` (X) + `x_axis_type`, `value_columns` (Y) + `y_axis_type`, `series_column` groups points, `point_size_column` sizes them (default `\"size\"`) |\n| `map_chart` | Load `map-hierarchy-charts` skill |\n| `hierarchy_chart` | Load `map-hierarchy-charts` skill |\n\nAll charts support: `unit` (+ `custom_unit: true` for a literal suffix outside the supported list), `decimal_places: 2`, `legend`. Exception: `table_chart` ignores the chart-level `unit` — use `column_units`.\n\n## Styling & advanced settings\n\nSeries colors and order, number chart coloring thresholds, heatmap color categories (`heatmap_color_mode` + `value_categories`), gauge bounds, y-axis tuning (`y_axis_auto_range`, log scale), `show_previous_period`, and the full per-key settings reference with cross-setting gotchas: load the `chart-styling` skill.\n\n## Bar Chart Configuration\n\n**Two types of bar charts — configure each differently:**\n\n1. **Category bar charts** (toplists, rankings) — NO time dimension:\n - `x_axis_type: \"category\"` (NOT \"time\" — there is no time column)\n - `time_column: \"series\"` (point to the category/grouping column, NOT \"time\")\n - `orientation: \"horizontal\"` (category labels are usually names)\n - Query has NO `{{time}}`, groups by a tag only\n\n2. **Time-series bar charts** (values over time) — HAS time dimension:\n - `x_axis_type: \"time\"` (default)\n - `orientation: \"vertical\"`\n - Query has `{{time}} AS time` and `GROUP BY time, series`\n\n**Common mistakes:**\n\n- Using `x_axis_type: \"time\"` on a category bar chart — breaks rendering (no time column exists)\n- Using `time_column: \"time\"` on a category bar chart — must be `\"series\"` (the grouping column)\n- Always check: does the query have `{{time}}`? No -> `x_axis_type: \"category\"` + `time_column: \"series\"`\n\n## Table Chart Settings\n\nTable charts format **each column independently** — they ignore the chart-level `unit` setting. Configure per-column units and progress bar highlighting via the settings object.\n\n### `column_units`\n\nSet units for individual columns. Each key is the column alias from the query, value is an object with `unit` and `custom_unit`:\n\n```json\n{\n \"column_units\": {\n \"CPU usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Memory usage\": { \"unit\": \"percent\", \"custom_unit\": false },\n \"Uptime\": { \"unit\": \"s\", \"custom_unit\": false },\n \"Disk used\": { \"unit\": \"B_si\", \"custom_unit\": false }\n }\n}\n```\n\nColumn names must exactly match the SQL alias. The `unit` values are the same as chart-level units (see Units Reference above).\n\n### `percentage_highlight_columns`\n\nAdd colored progress bar backgrounds to percentage columns (0-1 range values). Pass an array of column names:\n\n```json\n{\n \"percentage_highlight_columns\": [\"CPU usage\", \"Memory usage\"]\n}\n```\n\nThis renders a colored horizontal bar behind each cell value, making it easy to spot high/low values at a glance. Only use for columns that contain 0-1 ratio values displayed as percentages.\n\n## Map & Hierarchy Charts\n\n`map_chart` and `hierarchy_chart` are not time-series and have their own query shapes and settings — load the `map-hierarchy-charts` skill before creating either.\n\n## Chart Title Rules\n\n- Always sentence case (\"CPU utilization by service\", not \"CPU Utilization By Service\"). Never units in titles — bare or parenthesised — the `unit` setting renders the suffix; titles say _what_, not _how much_ (\"CPU utilization\", not \"CPU utilization (%)\").\n- Never abbreviate words (\"Average query latency\", not \"Avg query latency\"). Universal acronyms (CPU, HTTP, DNS, ...) are fine; narrower ones (NIC, SDK, SLO, ADLS) are not — if you'd hesitate to use it in onboarding documentation, spell it out. Applies to titles AND tooltips.\n- The full naming rules (abbreviation list, domain acronyms, parentheses ban, \"X by Y\" phrasing, \"&\" vs \"and\") live in the `dashboard-builder` skill — follow them for every dashboard, section, and chart title.\n\n## Explanation (tooltip)\n\nShows as a tooltip next to the chart title. Use rarely — charts must be comprehensible without it. A tooltip earns its place only by teaching something the chart can't show on its own: a non-obvious threshold (\"DiskPressure flips at 85% used — once tripped, kubelet evicts pods until usage drops\"), an invariant (\"Capture backlog > 0 means the pipeline is falling behind\"), a debugging hint, or a one-clause definition of an unfamiliar term used in the title (PTU, DLQ, ...). If you can't meet that bar, **leave the field empty** — the chart is better without filler.\n\n**Forbidden content** (these belong on the chart visually, not in prose):\n\n- How the metric is computed — aggregations, ratios, per-tag fan-outs are chart properties, not tooltip topics\n- That the value reflects the selected time window (every chart does)\n- Paraphrases of the chart title (\"Availability — shows the availability of the resource\" adds zero; cut it)\n- Unit explanations or conversions (the `unit` setting handles that)\n- What the legend already shows\n- Unexplained abbreviations or internal-sounding jargon (\"tail latency events\", \"poison-message queue\", \"AppLevelReconnectStorm\") — write plain English a customer reading the dashboard for the first time understands\n- Anything pointing outside the dashboard — other tools, how the dashboard was sourced, build/review process, \"previously this was X\". The customer sees only the dashboard; it must be self-contained. This rule applies to titles, section titles, and descriptions too.\n\n**Punctuation:** single-sentence tooltip → no trailing full-stop; 2+ sentences → every sentence ends with one. No parentheses. No code-shaped symbols (`=`, `→`, `&`, ASCII art) — write words (\"caps at 100\", not \"caps = 100\"); real numbers (\"above 85%\") and conventional abbreviations (`vs.`, `e.g.`) are fine. `vs` always with a period — in tooltips and titles.\n\n## Common Mistakes\n\nRead `references/common-mistakes.md` (in this skill's directory) before you create or edit a chart: it lists the settings and query mistakes that break charts (units, percent ratios, legends, series names, axis bounds) and the correct approach for each.\n\n## Dashboard Layout\n\nSee `dashboard-layout` skill for layout rules, row templates, coordinate math, and the mandatory planning process.\n\n## Critical checklist\n\nBefore creating each chart:\n\n- [ ] Query executed and data verified that its not all null\n"
}SHA-256 of public snapshot: 7ae3e210354c32a51d15aed29b43512d97573007dffe02b051897a85cf4d7de5