Update to Better Stack
Snapshot Nov 13, 2026 · 12:08 UTC · version 1.3.14
Collection source: downloaded plugin package.
Instructions updated for grafana-import
Skill instructions — Now says: `references/cloudwatch-translation.md`) - CloudWatch → use the CloudWatch translation rules in `references/cloudwatch-translation.md` **CloudWatch...
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
CloudWatch Translation below) - CloudWatch → use CloudWatch translation rules **CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See CloudWatch Translation section for the full mapping. ### M...
Nov 13, 2026 · 12:08 UTC
`references/cloudwatch-translation.md`) - CloudWatch → use the CloudWatch translation rules in `references/cloudwatch-translation.md` **CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See `r...
Supporting files
Nov 11, 2026 · 06:08 UTC
[]
Nov 13, 2026 · 12:08 UTC
[{"relative_path":"references/chart-patterns.md","size_in_bytes":7740},{"relative_path":"references/cloudwatch-translation.md","size_in_bytes":6176},{"relative_path":"scripts/extract-layout.js","size_in_bytes":17579}]
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -56,7 +56,7 @@ 2. **Skip `metrics_schema`** — you can't discover metrics or tags from live data 3. **Derive metric names from the Grafana query:** - PromQL metrics: use as-is (Prometheus metrics keep their exact names in Better Stack) - - CloudWatch metrics: translate `namespace/metricName` → underscore format with suffix (see CloudWatch Translation below) + - CloudWatch metrics: translate `namespace/metricName` → underscore format with suffix (see `references/cloudwatch-translation.md`) 4. **Derive tag names from the query:** - PromQL `by (label)` → `label('label')` (Prometheus labels keep their names) - CloudWatch `dimensions` → `label('snake_case')` (CloudWatch tags are snake_case) @@ -95,7 +95,7 @@ 1. **Check datasource type** — Prometheus (has `expr`) vs CloudWatch (has `namespace.metricName`): - PromQL → use PromQL translation rules - - CloudWatch → use CloudWatch translation rules + - CloudWatch → use the CloudWatch translation rules in `references/cloudwatch-translation.md` - Both use `label()` for tag/label access 2. **Check panel type** — determines chart type: @@ -175,7 +175,7 @@ **Prometheus labels keep their original names** — `instance`, `job`, `device`, `mode`, `cpu`, etc. Always verify with a test query. -**CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See CloudWatch Translation section for the full mapping. +**CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See `references/cloudwatch-translation.md` for the full mapping. ### PromQL Variable Translation @@ -214,129 +214,7 @@ ## CloudWatch → ClickHouse Translation -### Metric Name Translation - -CloudWatch metrics in Better Stack follow the pattern: `aws_<service>_<metric_name>_<statistic_suffix>` - -| CloudWatch | ClickHouse metric name | -| ----------------------------------- | -------------------------------- | -| `AWS/RDS` / `CPUUtilization` | `aws_rds_cpuutilization_average` | -| `AWS/EC2` / `CPUUtilization` | `aws_ec2_cpuutilization_average` | -| `AWS/ELB` / `RequestCount` [Sum] | `aws_elb_request_count_sum` | -| `AWS/Lambda` / `Duration` [Average] | `aws_lambda_duration_average` | - -Common suffixes: `_average`, `_sum`, `_count`, `_max`, `_min` - -**Always use `metrics_schema` to discover the actual name:** - -``` -metrics_schema(id, name_filter: "aws_rds*") -``` - -The naming convention is not always predictable. CamelCase → lowercase, but word boundaries vary. Always verify. - -### Statistic Mapping - -| CloudWatch statistic | ClickHouse merge function | Notes | -| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- | -| `Average` | `avgMerge(value_avg)` | Most common | -| `Sum` | `maxMerge(value_max)` on `_sum` metric | CloudWatch `_sum` stores pre-aggregated counts; using `avgMerge` smooths spikes | -| `Maximum` | `maxMerge(value_max)` | | -| `Minimum` | `minMerge(value_min)` | | -| `SampleCount` | `maxMerge(value_max)` on `_count` metric | | - -### CRITICAL: CloudWatch `Sum` Statistic and Hidden Tag Dimensions - -When CloudWatch queries use `Sum` statistic with multiple dimensions, the same hidden-tag problem applies as with Datadog `sum:` prefix. - -**When the query has NO dimension grouping** (single aggregate value), you MUST: - -1. Check `metrics_schema` for ALL tags on the metric -2. GROUP BY ALL tag dimensions in inner query -3. Wrap with SUM in outer query - -```sql --- CloudWatch: AWS/RDS RequestCount [Sum] — no dimension grouping --- WRONG: gives per-instance count, not total -SELECT maxMerge(value_max) AS "Requests" -FROM {{source}} WHERE name = 'aws_rds_request_count_sum' - --- CORRECT: GROUP BY all tags, SUM in outer query -SELECT SUM(requests) AS "Requests" -FROM ( - SELECT label('db_instance_identifier') AS instance, - maxMerge(value_max) AS requests - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'aws_rds_request_count_sum' - GROUP BY instance -) -``` - -### CloudWatch Dimension Mapping - -CloudWatch dimensions are stored as **snake_case** tags accessed via `label()`: - -**Dimension name mapping:** - -| Grafana dimension | ClickHouse label key | -| ---------------------- | ------------------------ | -| `DBInstanceIdentifier` | `db_instance_identifier` | -| `DBClusterIdentifier` | `db_cluster_identifier` | -| `InstanceId` | `instance_id` | -| `FunctionName` | `function_name` | -| `BucketName` | `bucket_name` | -| `LoadBalancer` | `load_balancer` | -| `TargetGroup` | `target_group` | -| `QueueName` | `queue_name` | -| `TopicName` | `topic_name` | -| `CacheClusterId` | `cache_cluster_id` | -| `VolumeId` | `volume_id` | -| `AvailabilityZone` | `availability_zone` | - -**CRITICAL: `label()` returns NULL (not empty string) for absent tags.** Using `= ''` or `!= ''` does NOT work — both evaluate to NULL and exclude the row. Use `IS NULL` / `IS NOT NULL`: - -```sql --- Instance-level only (tag present) -WHERE label('db_instance_identifier') IS NOT NULL --- Cluster-level only (cluster present, instance absent) -WHERE label('db_cluster_identifier') IS NOT NULL AND label('db_instance_identifier') IS NULL -``` - -**Multiple aggregation levels:** AWS metrics often have multiple series at different granularities (account-level, cluster-level, instance-level). Some rows have absent instance tags. Always filter to the correct level. - -### CloudWatch Dimension Filter Translation - -| Grafana dimension | ClickHouse equivalent | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `"DBInstanceIdentifier": "$dbinstance"` | Create a `dbinstance` variable + `[[ AND label('db_instance_identifier') = {{dbinstance}} ]]` (see Template Variable Translation) | -| `"DBInstanceIdentifier": "my-db"` | `AND label('db_instance_identifier') = 'my-db'` | -| `"DBInstanceIdentifier": "*"` | (no filter — return all) | -| `matchExact: false` | No extra filtering needed | - -### CloudWatch Metric Math - -Grafana CloudWatch metric math uses `expression` field referencing other targets by `id`: - -```json -{ "id": "m1", "metricName": "CPUUtilization", ... }, -{ "expression": "m1/100", "id": "e1", ... } -``` - -Translate to CTE pattern: - -```sql -WITH metrics AS ( - SELECT {{time}} AS time, avgMerge(value_avg) AS cpu - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'aws_rds_cpuutilization_average' - GROUP BY time -) -SELECT time, cpu / 100 AS "CPU utilization" FROM metrics ORDER BY time -``` - ---- +For CloudWatch panels, read `references/cloudwatch-translation.md` (in this skill's directory): metric name translation, statistic mapping, the `Sum` statistic and hidden dimensions, dimension mapping and filters, and metric math. ## Panel Type Mapping @@ -404,242 +282,7 @@ ## Line Chart Patterns -### Counter Rate with Label - -**PromQL:** `irate(node_network_receive_bytes_total{device="eth0"}[5m])` - -```sql -SELECT {{time}} AS time, label('device') AS series, avgMerge(rate_avg) AS "Bytes received" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'node_network_receive_bytes_total' -GROUP BY time, series ORDER BY time -``` - -### Sum by Label - -**PromQL:** `sum by (mode)(irate(node_cpu_seconds_total[5m]))` - -```sql -WITH cpu AS ( - SELECT {{time}} AS time, label('mode') AS mode, label('cpu') AS cpu, avgMerge(rate_avg) AS rate - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} AND name = 'node_cpu_seconds_total' - GROUP BY time, mode, cpu -) -SELECT time, mode AS series, sum(rate) AS "CPU usage" FROM cpu GROUP BY time, mode ORDER BY time -``` - -### Multi-Metric Arithmetic - -**PromQL:** `(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)` - -```sql -WITH mem AS ( - SELECT {{time}} AS time, name, avgMerge(value_avg) AS value - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name IN ('node_memory_MemTotal_bytes', 'node_memory_MemAvailable_bytes') - GROUP BY time, name -) -SELECT time, - (1 - sumIf(value, name='node_memory_MemAvailable_bytes') / sumIf(value, name='node_memory_MemTotal_bytes')) AS "Memory used" -FROM mem GROUP BY time ORDER BY time -``` - -### Multiple Metrics as Series - -**PromQL:** `node_memory_Cached_bytes`, `node_memory_Buffers_bytes` (separate targets) - -```sql -SELECT {{time}} AS time, - multiIf(name='node_memory_Cached_bytes', 'Cache', name='node_memory_Buffers_bytes', 'Buffers', name) AS series, - avgMerge(value_avg) AS "Usage" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name IN ('node_memory_Cached_bytes', 'node_memory_Buffers_bytes') -GROUP BY time, name ORDER BY time -``` - -### Composite Series — Tag + Metric Direction - -When a chart shows multiple metrics (e.g., bytes in/out) grouped by an instance tag, concat both dimensions into the series label. This is critical for multi-instance deployments where "Bytes in" / "Bytes out" alone doesn't identify which instance. - -**Pattern:** `concat(label('instance_tag'), ' ', direction_label)` - -```sql --- Bytes in/out per broker (Kafka example) -SELECT {{time}} AS time, - concat(label('instance'), ' ', multiIf(name = 'bytes_in_metric', 'in', 'out')) AS series, - avgMerge(rate_avg) AS "Throughput" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name IN ('bytes_in_metric', 'bytes_out_metric') -GROUP BY time, name, series ORDER BY time -``` - -**When to use:** Any chart combining multiple metrics (in/out, read/write, sent/received) where instances are also grouped by a tag. Without this, multi-instance deployments show ambiguous series like "in", "out" with no way to tell which instance they belong to. - -### Bytes to Bits (Network Traffic) - -**PromQL:** `rate(node_network_receive_bytes_total[5m]) * 8` - -```sql -SELECT {{time}} AS time, - concat(if(name='node_network_receive_bytes_total', 'Rx ', 'Tx '), label('device')) AS series, - avgMerge(rate_avg) * 8 AS "Throughput" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name IN ('node_network_receive_bytes_total', 'node_network_transmit_bytes_total') -GROUP BY time, name, label('device') ORDER BY time -``` - -### CloudWatch Line Chart — Average - -**Grafana:** `AWS/RDS` / `CPUUtilization` / `Average` / dims: `DBInstanceIdentifier = $dbinstance` - -```sql -SELECT {{time}} AS time, label('db_instance_identifier') AS series, - avgMerge(value_avg) AS "CPU utilization" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'aws_rds_cpuutilization_average' - AND label('db_instance_identifier') IS NOT NULL -GROUP BY time, series ORDER BY time -``` - -### CloudWatch Line Chart — Sum (Request Count) - -**Grafana:** `AWS/ELB` / `RequestCount` / `Sum` - -```sql -SELECT {{time}} AS time, maxMerge(value_max) AS "Request count" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'aws_elb_request_count_sum' -GROUP BY time ORDER BY time -``` - ---- - -## Gauge/Number Chart Patterns - -**For irate() in gauges, always use argMax() pattern** - -### Simple irate (Gauge) - -**PromQL:** `irate(node_pressure_cpu_waiting_seconds_total[5m])` - -```sql -SELECT 'CPU Pressure' AS series, argMax(rate, time) AS "Pressure" -FROM ( - SELECT {{time}} AS time, avgMerge(rate_avg) AS rate - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'node_pressure_cpu_waiting_seconds_total' - GROUP BY time -) -``` - -### avg(irate()) Across Labels — CPU Busy % - -**PromQL:** `100 * (1 - avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))` - -```sql -WITH cpu_rates AS ( - SELECT {{time}} AS time, label('cpu') AS cpu, avgMerge(rate_avg) AS rate - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'node_cpu_seconds_total' AND label('mode') = 'idle' - GROUP BY time, cpu -), -latest_per_cpu AS ( - SELECT cpu, argMax(rate, time) AS rate - FROM cpu_rates - GROUP BY cpu -) -SELECT 'CPU Busy' AS series, (1 - avg(rate)) AS "CPU busy" -FROM latest_per_cpu -``` - -Returns 0–1. Use `unit: percent`, `y_axis_max: 1`. - -### Instant Gauge Value (non-rate) - -**PromQL:** `node_memory_MemFree_bytes` - -```sql -SELECT 'Memory Free' AS series, argMax(value, time) AS "Memory free" -FROM ( - SELECT {{time}} AS time, avgMerge(value_avg) AS value - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'node_memory_MemFree_bytes' - GROUP BY time -) -``` - -### Uptime (Monotonic Timestamps) - -**PromQL:** `node_time_seconds - node_boot_time_seconds` - -```sql -WITH metrics AS ( - SELECT name, maxMerge(value_max) AS value - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name IN ('node_time_seconds', 'node_boot_time_seconds') - GROUP BY name -) -SELECT 'Uptime' AS series, - sumIf(value, name = 'node_time_seconds') - sumIf(value, name = 'node_boot_time_seconds') AS "Uptime" -FROM metrics -``` - -Use `maxMerge(value_max)` for timestamps — they increase monotonically so max = latest. - -### Static Number (RAM Total) - -**PromQL:** `node_memory_MemTotal_bytes` - -```sql -SELECT 'RAM Total' AS series, avgMerge(value_avg) AS "RAM total" -FROM {{source}} -WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} AND name = 'node_memory_MemTotal_bytes' -``` - -No time grouping needed for static values. - -### CloudWatch Number Chart - -**Grafana:** `AWS/RDS` / `FreeableMemory` / `Average` / stat panel with `lastNotNull` - -```sql -SELECT 'Freeable memory' AS series, argMax(value, time) AS "Freeable memory" -FROM ( - SELECT {{time}} AS time, avgMerge(value_avg) AS value - FROM {{source}} - WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} - AND name = 'aws_rds_freeable_memory_average' - GROUP BY time -) -``` - -### Grafana Stat reduceOptions Mapping - -Grafana stat panels have `reduceOptions.calcs` controlling how values reduce: - -| Grafana calc | ClickHouse equivalent | Notes | -| ------------- | ----------------------------------- | -------------------------- | -| `lastNotNull` | `argMax(value, time)` from subquery | Most recent non-null value | -| `last` | `argMax(value, time)` from subquery | Same in practice | -| `mean` | Plain query (no wrapper) | Average over window | -| `max` | CTE + `MAX()` wrapper | Peak over window | -| `min` | CTE + `MIN()` wrapper | Minimum over window | -| `sum` | CTE + `SUM()` wrapper | Total over window | -| `count` | CTE + `COUNT()` wrapper | Number of data points | - ---- +Read `references/chart-patterns.md` (in this skill's directory) before you write a panel's query: it has worked PromQL and CloudWatch → ClickHouse translations for line charts (counter rates, sums by label, arithmetic, composite series, bytes to bits) and for gauge and number charts (irate, instant values, uptime, static numbers, Grafana Stat `reduceOptions`). ## Layout Conversion
Full technical diff · 2 changed fields
changed /included_files
[]
[
{
"relative_path": "references/chart-patterns.md",
"size_in_bytes": 7740
},
{
"relative_path": "references/cloudwatch-translation.md",
"size_in_bytes": 6176
},
{
"relative_path": "scripts/extract-layout.js",
"size_in_bytes": 17579
}
]changed /skill_md_contents
"---\nname: grafana-import\ndescription: Import Grafana dashboards from grafana.com templates. Translates PromQL to ClickHouse. Load when user asks to import, convert, or recreate a Grafana dashboard in Better Stack.\n---\n\n# Grafana Dashboard Import\n\n## Quick Start\n\n```bash\n# 1. Get summary first (always start here)\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --summary\nnode <this skill's directory>/scripts/extract-layout.js --file <path> --summary\n\n# 2. Extract and build section-by-section\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 1\n# ... build section 1 charts ...\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 2\n# ... build section 2 charts ... and so on\n```\n\n## Tool Setup\n\nYou need the Better Stack dashboard tools (`create_dashboard`, `add_chart_to_dashboard`, `set_dashboard_variable`) and the query tools (`sources`, `source`, `metrics_schema`, `query`). If your client loads tools on demand, load them before starting.\n\nThe extract script is `scripts/extract-layout.js` in this skill's directory, run with Node.js 18 or newer. If you can't run scripts, read the export yourself and pull out the same fields: sections, panels, their queries, units and template variables.\n\n## Workflow\n\n1. **Extract summary:** `node scripts/extract-layout.js --dashboard <ID> --summary` — see all sections and panel counts\n2. **Check metrics:** `metrics_schema(id)` — identify available metrics AND their tags\n3. **Discover tag names:** `SELECT DISTINCT tags FROM {{source}} WHERE name = 'your.first.metric' LIMIT 5` — use exact tag names from real data, never guess\n4. **Create dashboard:** `create_dashboard(source_id, name)`\n5. **Translate template variables** — For each `templating.list` entry, create a Better Stack variable with `set_dashboard_variable` AND reference it in the queries that used `$name` via an optional `[[ ]]` clause. Never just omit them. See Template Variable Translation below.\n6. **Process section-by-section** — For each section:\n - Extract: `node scripts/extract-layout.js --dashboard <ID> --section <n>`\n - Build queries using translation rules below (load `metrics-query` skill)\n - Validate each query via `query` before creating charts\n - Add charts (load `chart-generation` + `dashboard-builder` skills), always pass `height: 6` and `section: \"Name\"`\n - Move to next section only after completing current one\n\n**Query translation checklist:**\n\n- Identify datasource type (Prometheus or CloudWatch) from extract output\n- For PromQL: match `rate()`/`irate()` to correct merge function, handle `sum by`/`avg by` aggregations\n- For CloudWatch: match `statistics` field (Average/Sum/Maximum/Minimum) to correct merge function\n- Check for multi-metric arithmetic (`a / b`) requiring CTEs\n\n### No-data mode (blind import)\n\n**Use ONLY when explicitly requested** (e.g., \"import without data\", \"no metrics available\", \"blind import\"). Never default to this mode — always try the normal workflow first.\n\nWhen the service has no metric data in Better Stack, you cannot validate queries. Instead:\n\n1. **Extract layout** as normal with the extract script\n2. **Skip `metrics_schema`** — you can't discover metrics or tags from live data\n3. **Derive metric names from the Grafana query:**\n - PromQL metrics: use as-is (Prometheus metrics keep their exact names in Better Stack)\n - CloudWatch metrics: translate `namespace/metricName` → underscore format with suffix (see CloudWatch Translation below)\n4. **Derive tag names from the query:**\n - PromQL `by (label)` → `label('label')` (Prometheus labels keep their names)\n - CloudWatch `dimensions` → `label('snake_case')` (CloudWatch tags are snake_case)\n5. **Build queries using known patterns** — follow ALL translation rules from this skill\n6. **Self-review every query before creating the chart:**\n - Re-read the SQL character by character\n - Check: Does `{{time}}` only appear where `dt` is in scope? (pitfall #1)\n - Check: Does `value_columns` match the SQL alias exactly? (Mismatch = chart appears empty. Never leave as default `[\"value\"]` when SQL uses a descriptive alias.)\n - Check: Is the merge function correct for the statistic/aggregation?\n - Check: Is `series_column` set when there's a GROUP BY on a tag?\n - Check: For `unit: \"percent\"`, are values 0–1? (divide by 100 if needed)\n7. **Create the dashboard and charts** — follow all layout rules, height: 6, section naming\n8. **No cross-checking is possible** — there's no data to compare against\n\n**Key principle:** In no-data mode, the queries may not return results, but they must be **structurally correct** so they work once data starts flowing. A broken query (wrong column name, bad syntax, missing GROUP BY) is worse than no chart at all.\n\n---\n\n## Interpreting Extract Script Output\n\nThe extract script shows each panel with its type, queries, and layout info:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n `PromQL expression` → \"Legend format\"\n```\n\nOr for CloudWatch panels:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n CW: AWS/RDS.CPUUtilization [Average] dims: DBInstanceIdentifier=$dbinstance\n```\n\n**Decision tree for each panel:**\n\n1. **Check datasource type** — Prometheus (has `expr`) vs CloudWatch (has `namespace.metricName`):\n - PromQL → use PromQL translation rules\n - CloudWatch → use CloudWatch translation rules\n - Both use `label()` for tag/label access\n\n2. **Check panel type** — determines chart type:\n - `timeseries` / `graph` → `line_chart` (default)\n - `timeseries` with `drawStyle: bars` → `bar_chart` with time dimension\n - `timeseries` with `stacking: normal` → `line_chart` with `stacking: \"stack\"`\n - `stat` / `singlestat` → `number_chart`, single scalar value\n - `gauge` / `bargauge` → `gauge_chart` or `bar_chart`\n - `table` → `table_chart`\n - `piechart` → `pie_chart`\n - `barchart` → `bar_chart` (category bar, no time dimension)\n - `heatmap` → `heatmap_chart`\n\n3. **Check for `by (labels)`** in PromQL or multi-dimension CloudWatch:\n - Present → Add tag-based series column and include in GROUP BY\n - Absent → single-series chart\n\n4. **Check for instant vs range queries:**\n - `instant: true` or stat/gauge panel → no `{{time}}`, scalar result\n - Range query or timeseries panel → needs `{{time}} AS time` and `GROUP BY time`\n\n---\n\n## PromQL → ClickHouse Translation\n\n### Function Mapping\n\n| PromQL | Line Chart | Gauge/Number |\n| ----------------------- | --------------------------- | -------------------------------------- |\n| `rate(metric[5m])` | `avgMerge(rate_avg)` | `avgMerge(rate_avg)` |\n| `irate(metric[5m])` | `avgMerge(rate_avg)` | **`argMax(rate, time)`** from subquery |\n| `metric` (gauge) | `avgMerge(value_avg)` | `argMax(value, time)` from subquery |\n| `sum(...)` / `avg(...)` | CTE + `sum()`/`avg()` | same |\n| `count by (label)` | `uniqExact(label('label'))` | same |\n| `clamp_min(x, 0)` | `greatest(x, 0)` | same |\n| `clamp_max(x, 100)` | `least(x, 100)` | same |\n\n### Why irate() Needs argMax for Gauges\n\n| Function | Computes |\n| ------------------------------- | -------------------------------- |\n| Prometheus `irate()` | Instant rate from last 2 samples |\n| ClickHouse `avgMerge(rate_avg)` | Average rate over entire window |\n\nUse `argMax(rate, time)` to get the most recent bucket's rate (90-99% match vs Prometheus).\n\n### Aggregation Over Time\n\n| PromQL | ClickHouse |\n| --------------------------- | --------------------- |\n| `avg_over_time(metric[5m])` | `avgMerge(value_avg)` |\n| `max_over_time(metric[5m])` | `maxMerge(value_max)` |\n| `min_over_time(metric[5m])` | `minMerge(value_min)` |\n\n### Arithmetic Operations\n\n| PromQL | ClickHouse |\n| --------------------- | ------------------------------------------------------- |\n| `metric_a / metric_b` | CTE + `sumIf(value, name='a') / sumIf(value, name='b')` |\n| `metric * 100` | `avgMerge(value_avg) * 100` |\n| `1 - metric` | `1 - avgMerge(value_avg)` |\n\n### Tag Access\n\nAll metric types (Prometheus, CloudWatch, collector) use `label('tag_name')` to access tags:\n\n```sql\n-- Access a tag\nlabel('device') AS series\n\n-- Filter by tag\nWHERE label('mode') = 'idle'\n\n-- Group by tag\nGROUP BY label('device')\n```\n\n**Prometheus labels keep their original names** — `instance`, `job`, `device`, `mode`, `cpu`, etc. Always verify with a test query.\n\n**CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See CloudWatch Translation section for the full mapping.\n\n### PromQL Variable Translation\n\n| Grafana token | ClickHouse handling |\n| ------------------ | ----------------------------------------------------------------- |\n| `$__rate_interval` | Ignore — `{{time}}` handles bucketing |\n| `$__interval` | Ignore |\n| `{label=\"$var\"}` | `[[ AND label('label') = {{var}} ]]` (single-value variable) |\n| `{label=~\"$var\"}` | `[[ AND match(label('label'), {{var}}) ]]` (multi-value variable) |\n| `{job=\"$job\"}` | `[[ AND label('job') = {{job}} ]]` |\n\nDo NOT just omit `$var` label filters — recreate each as a dashboard variable and reference it with an optional `[[ ]]` clause. See Template Variable Translation below.\n\n### Template Variable Translation\n\nGrafana `templating.list` variables (the `$var` selectors at the top) must be recreated as **Better Stack dashboard variables** — a variable only appears once a query references it, so do BOTH steps.\n\nFor each entry in `templating.list` (skip `type: interval` → `{{time}}` handles it; skip `datasource`/`adhoc`):\n\n1. **Create the variable** with `set_dashboard_variable` (type reference: `dashboard-builder` skill → \"Dashboard template variables\"):\n - `type: query` (e.g. `label_values(node_cpu_seconds_total, instance)`) → `multi_select_with_sql` (or `select_with_sql` if `multi: false`), `sql_definition: \"label('<label>')\"` where `<label>` is the label the variable queries (Prometheus labels keep their names; CloudWatch dimensions → snake_case).\n - `type: custom` (fixed options) → `select_value`, `default_values: [the option values]`.\n - `type: constant` / `textbox` → `string`, `default_values: [value]`.\n2. **Reference it in every query that used `$name`** (or `${name}` / `[[name]]`), as an OPTIONAL `[[ ]]` clause so charts render with nothing selected (matches Grafana's \"All\" default):\n - multi: `[[ AND match(label('<label>'), {{name}}) ]]`\n - single: `[[ AND label('<label>') = {{name}} ]]`\n\nName the variable after the Grafana variable's `name`.\n\nExample — `templating.list: [{ name: \"instance\", type: \"query\", query: \"label_values(node_cpu_seconds_total, instance)\", multi: true }]`, PromQL `rate(node_cpu_seconds_total{instance=~\"$instance\"}[5m])`:\n\n1. `set_dashboard_variable(dashboard_id, name: \"instance\", variable_type: \"multi_select_with_sql\", sql_definition: \"label('instance')\")`\n2. `SELECT {{time}} AS time, label('instance') AS series, avgMerge(rate_avg) AS \"CPU\" FROM {{source}} WHERE name = 'node_cpu_seconds_total' [[ AND match(label('instance'), {{instance}}) ]] GROUP BY time, series`\n\n---\n\n## CloudWatch → ClickHouse Translation\n\n### Metric Name Translation\n\nCloudWatch metrics in Better Stack follow the pattern: `aws_<service>_<metric_name>_<statistic_suffix>`\n\n| CloudWatch | ClickHouse metric name |\n| ----------------------------------- | -------------------------------- |\n| `AWS/RDS` / `CPUUtilization` | `aws_rds_cpuutilization_average` |\n| `AWS/EC2` / `CPUUtilization` | `aws_ec2_cpuutilization_average` |\n| `AWS/ELB` / `RequestCount` [Sum] | `aws_elb_request_count_sum` |\n| `AWS/Lambda` / `Duration` [Average] | `aws_lambda_duration_average` |\n\nCommon suffixes: `_average`, `_sum`, `_count`, `_max`, `_min`\n\n**Always use `metrics_schema` to discover the actual name:**\n\n```\nmetrics_schema(id, name_filter: \"aws_rds*\")\n```\n\nThe naming convention is not always predictable. CamelCase → lowercase, but word boundaries vary. Always verify.\n\n### Statistic Mapping\n\n| CloudWatch statistic | ClickHouse merge function | Notes |\n| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |\n| `Average` | `avgMerge(value_avg)` | Most common |\n| `Sum` | `maxMerge(value_max)` on `_sum` metric | CloudWatch `_sum` stores pre-aggregated counts; using `avgMerge` smooths spikes |\n| `Maximum` | `maxMerge(value_max)` | |\n| `Minimum` | `minMerge(value_min)` | |\n| `SampleCount` | `maxMerge(value_max)` on `_count` metric | |\n\n### CRITICAL: CloudWatch `Sum` Statistic and Hidden Tag Dimensions\n\nWhen CloudWatch queries use `Sum` statistic with multiple dimensions, the same hidden-tag problem applies as with Datadog `sum:` prefix.\n\n**When the query has NO dimension grouping** (single aggregate value), you MUST:\n\n1. Check `metrics_schema` for ALL tags on the metric\n2. GROUP BY ALL tag dimensions in inner query\n3. Wrap with SUM in outer query\n\n```sql\n-- CloudWatch: AWS/RDS RequestCount [Sum] — no dimension grouping\n-- WRONG: gives per-instance count, not total\nSELECT maxMerge(value_max) AS \"Requests\"\nFROM {{source}} WHERE name = 'aws_rds_request_count_sum'\n\n-- CORRECT: GROUP BY all tags, SUM in outer query\nSELECT SUM(requests) AS \"Requests\"\nFROM (\n SELECT label('db_instance_identifier') AS instance,\n maxMerge(value_max) AS requests\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'aws_rds_request_count_sum'\n GROUP BY instance\n)\n```\n\n### CloudWatch Dimension Mapping\n\nCloudWatch dimensions are stored as **snake_case** tags accessed via `label()`:\n\n**Dimension name mapping:**\n\n| Grafana dimension | ClickHouse label key |\n| ---------------------- | ------------------------ |\n| `DBInstanceIdentifier` | `db_instance_identifier` |\n| `DBClusterIdentifier` | `db_cluster_identifier` |\n| `InstanceId` | `instance_id` |\n| `FunctionName` | `function_name` |\n| `BucketName` | `bucket_name` |\n| `LoadBalancer` | `load_balancer` |\n| `TargetGroup` | `target_group` |\n| `QueueName` | `queue_name` |\n| `TopicName` | `topic_name` |\n| `CacheClusterId` | `cache_cluster_id` |\n| `VolumeId` | `volume_id` |\n| `AvailabilityZone` | `availability_zone` |\n\n**CRITICAL: `label()` returns NULL (not empty string) for absent tags.** Using `= ''` or `!= ''` does NOT work — both evaluate to NULL and exclude the row. Use `IS NULL` / `IS NOT NULL`:\n\n```sql\n-- Instance-level only (tag present)\nWHERE label('db_instance_identifier') IS NOT NULL\n-- Cluster-level only (cluster present, instance absent)\nWHERE label('db_cluster_identifier') IS NOT NULL AND label('db_instance_identifier') IS NULL\n```\n\n**Multiple aggregation levels:** AWS metrics often have multiple series at different granularities (account-level, cluster-level, instance-level). Some rows have absent instance tags. Always filter to the correct level.\n\n### CloudWatch Dimension Filter Translation\n\n| Grafana dimension | ClickHouse equivalent |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `\"DBInstanceIdentifier\": \"$dbinstance\"` | Create a `dbinstance` variable + `[[ AND label('db_instance_identifier') = {{dbinstance}} ]]` (see Template Variable Translation) |\n| `\"DBInstanceIdentifier\": \"my-db\"` | `AND label('db_instance_identifier') = 'my-db'` |\n| `\"DBInstanceIdentifier\": \"*\"` | (no filter — return all) |\n| `matchExact: false` | No extra filtering needed |\n\n### CloudWatch Metric Math\n\nGrafana CloudWatch metric math uses `expression` field referencing other targets by `id`:\n\n```json\n{ \"id\": \"m1\", \"metricName\": \"CPUUtilization\", ... },\n{ \"expression\": \"m1/100\", \"id\": \"e1\", ... }\n```\n\nTranslate to CTE pattern:\n\n```sql\nWITH metrics AS (\n SELECT {{time}} AS time, avgMerge(value_avg) AS cpu\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'aws_rds_cpuutilization_average'\n GROUP BY time\n)\nSELECT time, cpu / 100 AS \"CPU utilization\" FROM metrics ORDER BY time\n```\n\n---\n\n## Panel Type Mapping\n\n| Grafana panel | Better Stack chart | Notes |\n| ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |\n| `timeseries` | `line_chart` | Default; time-series with `{{time}}` |\n| `timeseries` (drawStyle: bars) | `bar_chart` | Time-series bars — needs `{{time}}` |\n| `timeseries` (stacking: normal) | `line_chart` | `stacking: \"stack\"` |\n| `graph` (legacy) | `line_chart` | Same as timeseries |\n| `stat` | `number_chart` | Single value, no time |\n| `singlestat` (legacy) | `number_chart` | Same as stat |\n| `gauge` | `gauge_chart` | |\n| `bargauge` | `gauge_chart` | |\n| `table` / `table-old` | `table_chart` | Set `column_units` per column + `percentage_highlight_columns` for ratio cols (see chart-generation skill) |\n| `barchart` | `bar_chart` | Category bar, no time dimension |\n| `piechart` | `pie_chart` | |\n| `heatmap` | `heatmap_chart` | |\n\n**Skip:** `text`, `row`, `news`, `dashlist`, `alertlist`, `annolist`, `logs`, `nodeGraph`, `traces`, `flamegraph`, `canvas`, `geomap`\n\n### Bar chart configuration\n\nGrafana **`barchart`** → category bar chart (no `{{time}}`); **`timeseries` with drawStyle bars** → time-series bar chart. Configure per the `chart-generation` skill's Bar Chart Configuration (category bars need `x_axis_type: \"category\"` + `time_column: \"series\"`).\n\n---\n\n## Unit Mapping (Grafana → Better Stack)\n\n| Grafana unit | Better Stack unit | Notes |\n| ------------------- | ----------------- | ------------------------------------------------------------------------------------------- |\n| `bytes`, `decbytes` | `B_si` | |\n| `bits`, `decbits` | `bps` | Only if rate; otherwise `B_si` |\n| `Bps` (bytes/sec) | `B_si` | |\n| `bps` (bits/sec) | `bps` | PromQL `* 8` for bytes→bits |\n| `s` | `s` | |\n| `ms` | `ms` | |\n| `us`, `µs` | `μs` | |\n| `ns` | `ns` | |\n| `percent` | `percent` | **Grafana `percent` = 0–100 input; Better Stack `percent` = 0–1 input. MUST divide by 100** |\n| `percentunit` | `percent` | Grafana `percentunit` = 0–1 input — maps directly, no conversion |\n| `short` | `shortened` | |\n| `none` | `shortened` | |\n| `ops`, `iops` | `e/s` | |\n| `reqps` | `rps` | |\n| `locale` | `shortened` | |\n| `celsius` | (custom) | Last resort — use `unit: \"none\"`, add \"°C\" in title |\n| `hertz` | `e/s` | |\n\n**Always prefer predefined units.** The table above covers nearly all Grafana units. Never use `custom_unit` when a predefined Better Stack unit exists (e.g., use `B_si` not `custom_unit: \"bytes\"`, use `e/s` not `custom_unit: \"/s\"`, use `B_si/s` not `custom_unit: \"bytes/sec\"`). Custom units lack auto-scaling and produce worse formatting. Only use `custom_unit` for truly exotic units like °C where no predefined equivalent exists.\n\n**CRITICAL: Grafana `percent` vs `percentunit`:**\n\n- Grafana `percent` → values are 0–100. Better Stack `percent` expects 0–1. **You MUST divide by 100 in the query** or values will display as 4000% instead of 40%.\n- Grafana `percentunit` → values are 0–1. Maps directly to Better Stack `percent`. No conversion needed.\n\n**Default unit for counts:** Connection counts, query counts, transaction counts, and similar integer metrics should use `unit: \"shortened\"` for auto-scaling (1.5K, 2.3M). Do NOT leave unit unset on count metrics.\n\n---\n\n## Naming Convention\n\nFollow the `dashboard-builder` skill's naming rules (sentence case, no abbreviations, no units or parentheses in titles). Grafana templates often use \"Avg\"/\"Max\"/\"Config\" and parenthetical units (\"Output events bytes rate (bytes/sec)\") — always expand/strip at chart-create time.\n\n---\n\n## Line Chart Patterns\n\n### Counter Rate with Label\n\n**PromQL:** `irate(node_network_receive_bytes_total{device=\"eth0\"}[5m])`\n\n```sql\nSELECT {{time}} AS time, label('device') AS series, avgMerge(rate_avg) AS \"Bytes received\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'node_network_receive_bytes_total'\nGROUP BY time, series ORDER BY time\n```\n\n### Sum by Label\n\n**PromQL:** `sum by (mode)(irate(node_cpu_seconds_total[5m]))`\n\n```sql\nWITH cpu AS (\n SELECT {{time}} AS time, label('mode') AS mode, label('cpu') AS cpu, avgMerge(rate_avg) AS rate\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} AND name = 'node_cpu_seconds_total'\n GROUP BY time, mode, cpu\n)\nSELECT time, mode AS series, sum(rate) AS \"CPU usage\" FROM cpu GROUP BY time, mode ORDER BY time\n```\n\n### Multi-Metric Arithmetic\n\n**PromQL:** `(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)`\n\n```sql\nWITH mem AS (\n SELECT {{time}} AS time, name, avgMerge(value_avg) AS value\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name IN ('node_memory_MemTotal_bytes', 'node_memory_MemAvailable_bytes')\n GROUP BY time, name\n)\nSELECT time,\n (1 - sumIf(value, name='node_memory_MemAvailable_bytes') / sumIf(value, name='node_memory_MemTotal_bytes')) AS \"Memory used\"\nFROM mem GROUP BY time ORDER BY time\n```\n\n### Multiple Metrics as Series\n\n**PromQL:** `node_memory_Cached_bytes`, `node_memory_Buffers_bytes` (separate targets)\n\n```sql\nSELECT {{time}} AS time,\n multiIf(name='node_memory_Cached_bytes', 'Cache', name='node_memory_Buffers_bytes', 'Buffers', name) AS series,\n avgMerge(value_avg) AS \"Usage\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name IN ('node_memory_Cached_bytes', 'node_memory_Buffers_bytes')\nGROUP BY time, name ORDER BY time\n```\n\n### Composite Series — Tag + Metric Direction\n\nWhen a chart shows multiple metrics (e.g., bytes in/out) grouped by an instance tag, concat both dimensions into the series label. This is critical for multi-instance deployments where \"Bytes in\" / \"Bytes out\" alone doesn't identify which instance.\n\n**Pattern:** `concat(label('instance_tag'), ' ', direction_label)`\n\n```sql\n-- Bytes in/out per broker (Kafka example)\nSELECT {{time}} AS time,\n concat(label('instance'), ' ', multiIf(name = 'bytes_in_metric', 'in', 'out')) AS series,\n avgMerge(rate_avg) AS \"Throughput\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name IN ('bytes_in_metric', 'bytes_out_metric')\nGROUP BY time, name, series ORDER BY time\n```\n\n**When to use:** Any chart combining multiple metrics (in/out, read/write, sent/received) where instances are also grouped by a tag. Without this, multi-instance deployments show ambiguous series like \"in\", \"out\" with no way to tell which instance they belong to.\n\n### Bytes to Bits (Network Traffic)\n\n**PromQL:** `rate(node_network_receive_bytes_total[5m]) * 8`\n\n```sql\nSELECT {{time}} AS time,\n concat(if(name='node_network_receive_bytes_total', 'Rx ', 'Tx '), label('device')) AS series,\n avgMerge(rate_avg) * 8 AS \"Throughput\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name IN ('node_network_receive_bytes_total', 'node_network_transmit_bytes_total')\nGROUP BY time, name, label('device') ORDER BY time\n```\n\n### CloudWatch Line Chart — Average\n\n**Grafana:** `AWS/RDS` / `CPUUtilization` / `Average` / dims: `DBInstanceIdentifier = $dbinstance`\n\n```sql\nSELECT {{time}} AS time, label('db_instance_identifier') AS series,\n avgMerge(value_avg) AS \"CPU utilization\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'aws_rds_cpuutilization_average'\n AND label('db_instance_identifier') IS NOT NULL\nGROUP BY time, series ORDER BY time\n```\n\n### CloudWatch Line Chart — Sum (Request Count)\n\n**Grafana:** `AWS/ELB` / `RequestCount` / `Sum`\n\n```sql\nSELECT {{time}} AS time, maxMerge(value_max) AS \"Request count\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'aws_elb_request_count_sum'\nGROUP BY time ORDER BY time\n```\n\n---\n\n## Gauge/Number Chart Patterns\n\n**For irate() in gauges, always use argMax() pattern**\n\n### Simple irate (Gauge)\n\n**PromQL:** `irate(node_pressure_cpu_waiting_seconds_total[5m])`\n\n```sql\nSELECT 'CPU Pressure' AS series, argMax(rate, time) AS \"Pressure\"\nFROM (\n SELECT {{time}} AS time, avgMerge(rate_avg) AS rate\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'node_pressure_cpu_waiting_seconds_total'\n GROUP BY time\n)\n```\n\n### avg(irate()) Across Labels — CPU Busy %\n\n**PromQL:** `100 * (1 - avg(irate(node_cpu_seconds_total{mode=\"idle\"}[5m])))`\n\n```sql\nWITH cpu_rates AS (\n SELECT {{time}} AS time, label('cpu') AS cpu, avgMerge(rate_avg) AS rate\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'node_cpu_seconds_total' AND label('mode') = 'idle'\n GROUP BY time, cpu\n),\nlatest_per_cpu AS (\n SELECT cpu, argMax(rate, time) AS rate\n FROM cpu_rates\n GROUP BY cpu\n)\nSELECT 'CPU Busy' AS series, (1 - avg(rate)) AS \"CPU busy\"\nFROM latest_per_cpu\n```\n\nReturns 0–1. Use `unit: percent`, `y_axis_max: 1`.\n\n### Instant Gauge Value (non-rate)\n\n**PromQL:** `node_memory_MemFree_bytes`\n\n```sql\nSELECT 'Memory Free' AS series, argMax(value, time) AS \"Memory free\"\nFROM (\n SELECT {{time}} AS time, avgMerge(value_avg) AS value\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'node_memory_MemFree_bytes'\n GROUP BY time\n)\n```\n\n### Uptime (Monotonic Timestamps)\n\n**PromQL:** `node_time_seconds - node_boot_time_seconds`\n\n```sql\nWITH metrics AS (\n SELECT name, maxMerge(value_max) AS value\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name IN ('node_time_seconds', 'node_boot_time_seconds')\n GROUP BY name\n)\nSELECT 'Uptime' AS series,\n sumIf(value, name = 'node_time_seconds') - sumIf(value, name = 'node_boot_time_seconds') AS \"Uptime\"\nFROM metrics\n```\n\nUse `maxMerge(value_max)` for timestamps — they increase monotonically so max = latest.\n\n### Static Number (RAM Total)\n\n**PromQL:** `node_memory_MemTotal_bytes`\n\n```sql\nSELECT 'RAM Total' AS series, avgMerge(value_avg) AS \"RAM total\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}} AND name = 'node_memory_MemTotal_bytes'\n```\n\nNo time grouping needed for static values.\n\n### CloudWatch Number Chart\n\n**Grafana:** `AWS/RDS` / `FreeableMemory` / `Average` / stat panel with `lastNotNull`\n\n```sql\nSELECT 'Freeable memory' AS series, argMax(value, time) AS \"Freeable memory\"\nFROM (\n SELECT {{time}} AS time, avgMerge(value_avg) AS value\n FROM {{source}}\n WHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND name = 'aws_rds_freeable_memory_average'\n GROUP BY time\n)\n```\n\n### Grafana Stat reduceOptions Mapping\n\nGrafana stat panels have `reduceOptions.calcs` controlling how values reduce:\n\n| Grafana calc | ClickHouse equivalent | Notes |\n| ------------- | ----------------------------------- | -------------------------- |\n| `lastNotNull` | `argMax(value, time)` from subquery | Most recent non-null value |\n| `last` | `argMax(value, time)` from subquery | Same in practice |\n| `mean` | Plain query (no wrapper) | Average over window |\n| `max` | CTE + `MAX()` wrapper | Peak over window |\n| `min` | CTE + `MIN()` wrapper | Minimum over window |\n| `sum` | CTE + `SUM()` wrapper | Total over window |\n| `count` | CTE + `COUNT()` wrapper | Number of data points |\n\n---\n\n## Layout Conversion\n\n- **Grafana grid:** 24 columns → divide x and w by 2 for Better Stack's 12-column grid\n- **Heights:** Always `height: 6` (ignore Grafana heights)\n- **Rows:** `type: \"row\"` panels → `section: \"Row Title\"`\n\nThen apply the `dashboard-layout` skill's rules and planning process (rows sum to 12, prefer 3 per row, no full-width charts, no orphan rows, number charts ≤ w:4).\n\n---\n\n## Additional Rules\n\nFor series_column, value_columns, legend, section organization, pie charts, stacking, and treat_missing_values — see `dashboard-builder` skill.\n\n**Import-specific:** Latency — always check the source metric's native unit FIRST with `query` before applying any conversion. Some metrics are in seconds (→ `* 1000`, `unit: \"ms\"`), others are already in milliseconds. Don't assume.\n\n---\n\n## Common Pitfalls\n\n1. **Macros in nested queries** — `{{time}}`, `label()`, `{{source}}` only work directly against `{{source}}`, not in outer queries. See `dashboard-builder` skill.\n\n2. **Nested aggregates forbidden** → Use CTEs for `sum by (label)(rate(...))` patterns.\n\n3. **Uptime/timestamps** → Use `maxMerge(value_max)` not `avgMerge(value_avg)`.\n\n4. **Gauge/number charts need series label** → Always include `'Label' AS series`. Number charts only display the chart title, so make it descriptive.\n\n5. **Always validate queries** — Run `query` before creating charts. A broken chart wastes more time than validating upfront.\n""---\nname: grafana-import\ndescription: Import Grafana dashboards from grafana.com templates. Translates PromQL to ClickHouse. Load when user asks to import, convert, or recreate a Grafana dashboard in Better Stack.\n---\n\n# Grafana Dashboard Import\n\n## Quick Start\n\n```bash\n# 1. Get summary first (always start here)\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --summary\nnode <this skill's directory>/scripts/extract-layout.js --file <path> --summary\n\n# 2. Extract and build section-by-section\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 1\n# ... build section 1 charts ...\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 2\n# ... build section 2 charts ... and so on\n```\n\n## Tool Setup\n\nYou need the Better Stack dashboard tools (`create_dashboard`, `add_chart_to_dashboard`, `set_dashboard_variable`) and the query tools (`sources`, `source`, `metrics_schema`, `query`). If your client loads tools on demand, load them before starting.\n\nThe extract script is `scripts/extract-layout.js` in this skill's directory, run with Node.js 18 or newer. If you can't run scripts, read the export yourself and pull out the same fields: sections, panels, their queries, units and template variables.\n\n## Workflow\n\n1. **Extract summary:** `node scripts/extract-layout.js --dashboard <ID> --summary` — see all sections and panel counts\n2. **Check metrics:** `metrics_schema(id)` — identify available metrics AND their tags\n3. **Discover tag names:** `SELECT DISTINCT tags FROM {{source}} WHERE name = 'your.first.metric' LIMIT 5` — use exact tag names from real data, never guess\n4. **Create dashboard:** `create_dashboard(source_id, name)`\n5. **Translate template variables** — For each `templating.list` entry, create a Better Stack variable with `set_dashboard_variable` AND reference it in the queries that used `$name` via an optional `[[ ]]` clause. Never just omit them. See Template Variable Translation below.\n6. **Process section-by-section** — For each section:\n - Extract: `node scripts/extract-layout.js --dashboard <ID> --section <n>`\n - Build queries using translation rules below (load `metrics-query` skill)\n - Validate each query via `query` before creating charts\n - Add charts (load `chart-generation` + `dashboard-builder` skills), always pass `height: 6` and `section: \"Name\"`\n - Move to next section only after completing current one\n\n**Query translation checklist:**\n\n- Identify datasource type (Prometheus or CloudWatch) from extract output\n- For PromQL: match `rate()`/`irate()` to correct merge function, handle `sum by`/`avg by` aggregations\n- For CloudWatch: match `statistics` field (Average/Sum/Maximum/Minimum) to correct merge function\n- Check for multi-metric arithmetic (`a / b`) requiring CTEs\n\n### No-data mode (blind import)\n\n**Use ONLY when explicitly requested** (e.g., \"import without data\", \"no metrics available\", \"blind import\"). Never default to this mode — always try the normal workflow first.\n\nWhen the service has no metric data in Better Stack, you cannot validate queries. Instead:\n\n1. **Extract layout** as normal with the extract script\n2. **Skip `metrics_schema`** — you can't discover metrics or tags from live data\n3. **Derive metric names from the Grafana query:**\n - PromQL metrics: use as-is (Prometheus metrics keep their exact names in Better Stack)\n - CloudWatch metrics: translate `namespace/metricName` → underscore format with suffix (see `references/cloudwatch-translation.md`)\n4. **Derive tag names from the query:**\n - PromQL `by (label)` → `label('label')` (Prometheus labels keep their names)\n - CloudWatch `dimensions` → `label('snake_case')` (CloudWatch tags are snake_case)\n5. **Build queries using known patterns** — follow ALL translation rules from this skill\n6. **Self-review every query before creating the chart:**\n - Re-read the SQL character by character\n - Check: Does `{{time}}` only appear where `dt` is in scope? (pitfall #1)\n - Check: Does `value_columns` match the SQL alias exactly? (Mismatch = chart appears empty. Never leave as default `[\"value\"]` when SQL uses a descriptive alias.)\n - Check: Is the merge function correct for the statistic/aggregation?\n - Check: Is `series_column` set when there's a GROUP BY on a tag?\n - Check: For `unit: \"percent\"`, are values 0–1? (divide by 100 if needed)\n7. **Create the dashboard and charts** — follow all layout rules, height: 6, section naming\n8. **No cross-checking is possible** — there's no data to compare against\n\n**Key principle:** In no-data mode, the queries may not return results, but they must be **structurally correct** so they work once data starts flowing. A broken query (wrong column name, bad syntax, missing GROUP BY) is worse than no chart at all.\n\n---\n\n## Interpreting Extract Script Output\n\nThe extract script shows each panel with its type, queries, and layout info:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n `PromQL expression` → \"Legend format\"\n```\n\nOr for CloudWatch panels:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n CW: AWS/RDS.CPUUtilization [Average] dims: DBInstanceIdentifier=$dbinstance\n```\n\n**Decision tree for each panel:**\n\n1. **Check datasource type** — Prometheus (has `expr`) vs CloudWatch (has `namespace.metricName`):\n - PromQL → use PromQL translation rules\n - CloudWatch → use the CloudWatch translation rules in `references/cloudwatch-translation.md`\n - Both use `label()` for tag/label access\n\n2. **Check panel type** — determines chart type:\n - `timeseries` / `graph` → `line_chart` (default)\n - `timeseries` with `drawStyle: bars` → `bar_chart` with time dimension\n - `timeseries` with `stacking: normal` → `line_chart` with `stacking: \"stack\"`\n - `stat` / `singlestat` → `number_chart`, single scalar value\n - `gauge` / `bargauge` → `gauge_chart` or `bar_chart`\n - `table` → `table_chart`\n - `piechart` → `pie_chart`\n - `barchart` → `bar_chart` (category bar, no time dimension)\n - `heatmap` → `heatmap_chart`\n\n3. **Check for `by (labels)`** in PromQL or multi-dimension CloudWatch:\n - Present → Add tag-based series column and include in GROUP BY\n - Absent → single-series chart\n\n4. **Check for instant vs range queries:**\n - `instant: true` or stat/gauge panel → no `{{time}}`, scalar result\n - Range query or timeseries panel → needs `{{time}} AS time` and `GROUP BY time`\n\n---\n\n## PromQL → ClickHouse Translation\n\n### Function Mapping\n\n| PromQL | Line Chart | Gauge/Number |\n| ----------------------- | --------------------------- | -------------------------------------- |\n| `rate(metric[5m])` | `avgMerge(rate_avg)` | `avgMerge(rate_avg)` |\n| `irate(metric[5m])` | `avgMerge(rate_avg)` | **`argMax(rate, time)`** from subquery |\n| `metric` (gauge) | `avgMerge(value_avg)` | `argMax(value, time)` from subquery |\n| `sum(...)` / `avg(...)` | CTE + `sum()`/`avg()` | same |\n| `count by (label)` | `uniqExact(label('label'))` | same |\n| `clamp_min(x, 0)` | `greatest(x, 0)` | same |\n| `clamp_max(x, 100)` | `least(x, 100)` | same |\n\n### Why irate() Needs argMax for Gauges\n\n| Function | Computes |\n| ------------------------------- | -------------------------------- |\n| Prometheus `irate()` | Instant rate from last 2 samples |\n| ClickHouse `avgMerge(rate_avg)` | Average rate over entire window |\n\nUse `argMax(rate, time)` to get the most recent bucket's rate (90-99% match vs Prometheus).\n\n### Aggregation Over Time\n\n| PromQL | ClickHouse |\n| --------------------------- | --------------------- |\n| `avg_over_time(metric[5m])` | `avgMerge(value_avg)` |\n| `max_over_time(metric[5m])` | `maxMerge(value_max)` |\n| `min_over_time(metric[5m])` | `minMerge(value_min)` |\n\n### Arithmetic Operations\n\n| PromQL | ClickHouse |\n| --------------------- | ------------------------------------------------------- |\n| `metric_a / metric_b` | CTE + `sumIf(value, name='a') / sumIf(value, name='b')` |\n| `metric * 100` | `avgMerge(value_avg) * 100` |\n| `1 - metric` | `1 - avgMerge(value_avg)` |\n\n### Tag Access\n\nAll metric types (Prometheus, CloudWatch, collector) use `label('tag_name')` to access tags:\n\n```sql\n-- Access a tag\nlabel('device') AS series\n\n-- Filter by tag\nWHERE label('mode') = 'idle'\n\n-- Group by tag\nGROUP BY label('device')\n```\n\n**Prometheus labels keep their original names** — `instance`, `job`, `device`, `mode`, `cpu`, etc. Always verify with a test query.\n\n**CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See `references/cloudwatch-translation.md` for the full mapping.\n\n### PromQL Variable Translation\n\n| Grafana token | ClickHouse handling |\n| ------------------ | ----------------------------------------------------------------- |\n| `$__rate_interval` | Ignore — `{{time}}` handles bucketing |\n| `$__interval` | Ignore |\n| `{label=\"$var\"}` | `[[ AND label('label') = {{var}} ]]` (single-value variable) |\n| `{label=~\"$var\"}` | `[[ AND match(label('label'), {{var}}) ]]` (multi-value variable) |\n| `{job=\"$job\"}` | `[[ AND label('job') = {{job}} ]]` |\n\nDo NOT just omit `$var` label filters — recreate each as a dashboard variable and reference it with an optional `[[ ]]` clause. See Template Variable Translation below.\n\n### Template Variable Translation\n\nGrafana `templating.list` variables (the `$var` selectors at the top) must be recreated as **Better Stack dashboard variables** — a variable only appears once a query references it, so do BOTH steps.\n\nFor each entry in `templating.list` (skip `type: interval` → `{{time}}` handles it; skip `datasource`/`adhoc`):\n\n1. **Create the variable** with `set_dashboard_variable` (type reference: `dashboard-builder` skill → \"Dashboard template variables\"):\n - `type: query` (e.g. `label_values(node_cpu_seconds_total, instance)`) → `multi_select_with_sql` (or `select_with_sql` if `multi: false`), `sql_definition: \"label('<label>')\"` where `<label>` is the label the variable queries (Prometheus labels keep their names; CloudWatch dimensions → snake_case).\n - `type: custom` (fixed options) → `select_value`, `default_values: [the option values]`.\n - `type: constant` / `textbox` → `string`, `default_values: [value]`.\n2. **Reference it in every query that used `$name`** (or `${name}` / `[[name]]`), as an OPTIONAL `[[ ]]` clause so charts render with nothing selected (matches Grafana's \"All\" default):\n - multi: `[[ AND match(label('<label>'), {{name}}) ]]`\n - single: `[[ AND label('<label>') = {{name}} ]]`\n\nName the variable after the Grafana variable's `name`.\n\nExample — `templating.list: [{ name: \"instance\", type: \"query\", query: \"label_values(node_cpu_seconds_total, instance)\", multi: true }]`, PromQL `rate(node_cpu_seconds_total{instance=~\"$instance\"}[5m])`:\n\n1. `set_dashboard_variable(dashboard_id, name: \"instance\", variable_type: \"multi_select_with_sql\", sql_definition: \"label('instance')\")`\n2. `SELECT {{time}} AS time, label('instance') AS series, avgMerge(rate_avg) AS \"CPU\" FROM {{source}} WHERE name = 'node_cpu_seconds_total' [[ AND match(label('instance'), {{instance}}) ]] GROUP BY time, series`\n\n---\n\n## CloudWatch → ClickHouse Translation\n\nFor CloudWatch panels, read `references/cloudwatch-translation.md` (in this skill's directory): metric name translation, statistic mapping, the `Sum` statistic and hidden dimensions, dimension mapping and filters, and metric math.\n\n## Panel Type Mapping\n\n| Grafana panel | Better Stack chart | Notes |\n| ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |\n| `timeseries` | `line_chart` | Default; time-series with `{{time}}` |\n| `timeseries` (drawStyle: bars) | `bar_chart` | Time-series bars — needs `{{time}}` |\n| `timeseries` (stacking: normal) | `line_chart` | `stacking: \"stack\"` |\n| `graph` (legacy) | `line_chart` | Same as timeseries |\n| `stat` | `number_chart` | Single value, no time |\n| `singlestat` (legacy) | `number_chart` | Same as stat |\n| `gauge` | `gauge_chart` | |\n| `bargauge` | `gauge_chart` | |\n| `table` / `table-old` | `table_chart` | Set `column_units` per column + `percentage_highlight_columns` for ratio cols (see chart-generation skill) |\n| `barchart` | `bar_chart` | Category bar, no time dimension |\n| `piechart` | `pie_chart` | |\n| `heatmap` | `heatmap_chart` | |\n\n**Skip:** `text`, `row`, `news`, `dashlist`, `alertlist`, `annolist`, `logs`, `nodeGraph`, `traces`, `flamegraph`, `canvas`, `geomap`\n\n### Bar chart configuration\n\nGrafana **`barchart`** → category bar chart (no `{{time}}`); **`timeseries` with drawStyle bars** → time-series bar chart. Configure per the `chart-generation` skill's Bar Chart Configuration (category bars need `x_axis_type: \"category\"` + `time_column: \"series\"`).\n\n---\n\n## Unit Mapping (Grafana → Better Stack)\n\n| Grafana unit | Better Stack unit | Notes |\n| ------------------- | ----------------- | ------------------------------------------------------------------------------------------- |\n| `bytes`, `decbytes` | `B_si` | |\n| `bits`, `decbits` | `bps` | Only if rate; otherwise `B_si` |\n| `Bps` (bytes/sec) | `B_si` | |\n| `bps` (bits/sec) | `bps` | PromQL `* 8` for bytes→bits |\n| `s` | `s` | |\n| `ms` | `ms` | |\n| `us`, `µs` | `μs` | |\n| `ns` | `ns` | |\n| `percent` | `percent` | **Grafana `percent` = 0–100 input; Better Stack `percent` = 0–1 input. MUST divide by 100** |\n| `percentunit` | `percent` | Grafana `percentunit` = 0–1 input — maps directly, no conversion |\n| `short` | `shortened` | |\n| `none` | `shortened` | |\n| `ops`, `iops` | `e/s` | |\n| `reqps` | `rps` | |\n| `locale` | `shortened` | |\n| `celsius` | (custom) | Last resort — use `unit: \"none\"`, add \"°C\" in title |\n| `hertz` | `e/s` | |\n\n**Always prefer predefined units.** The table above covers nearly all Grafana units. Never use `custom_unit` when a predefined Better Stack unit exists (e.g., use `B_si` not `custom_unit: \"bytes\"`, use `e/s` not `custom_unit: \"/s\"`, use `B_si/s` not `custom_unit: \"bytes/sec\"`). Custom units lack auto-scaling and produce worse formatting. Only use `custom_unit` for truly exotic units like °C where no predefined equivalent exists.\n\n**CRITICAL: Grafana `percent` vs `percentunit`:**\n\n- Grafana `percent` → values are 0–100. Better Stack `percent` expects 0–1. **You MUST divide by 100 in the query** or values will display as 4000% instead of 40%.\n- Grafana `percentunit` → values are 0–1. Maps directly to Better Stack `percent`. No conversion needed.\n\n**Default unit for counts:** Connection counts, query counts, transaction counts, and similar integer metrics should use `unit: \"shortened\"` for auto-scaling (1.5K, 2.3M). Do NOT leave unit unset on count metrics.\n\n---\n\n## Naming Convention\n\nFollow the `dashboard-builder` skill's naming rules (sentence case, no abbreviations, no units or parentheses in titles). Grafana templates often use \"Avg\"/\"Max\"/\"Config\" and parenthetical units (\"Output events bytes rate (bytes/sec)\") — always expand/strip at chart-create time.\n\n---\n\n## Line Chart Patterns\n\nRead `references/chart-patterns.md` (in this skill's directory) before you write a panel's query: it has worked PromQL and CloudWatch → ClickHouse translations for line charts (counter rates, sums by label, arithmetic, composite series, bytes to bits) and for gauge and number charts (irate, instant values, uptime, static numbers, Grafana Stat `reduceOptions`).\n\n## Layout Conversion\n\n- **Grafana grid:** 24 columns → divide x and w by 2 for Better Stack's 12-column grid\n- **Heights:** Always `height: 6` (ignore Grafana heights)\n- **Rows:** `type: \"row\"` panels → `section: \"Row Title\"`\n\nThen apply the `dashboard-layout` skill's rules and planning process (rows sum to 12, prefer 3 per row, no full-width charts, no orphan rows, number charts ≤ w:4).\n\n---\n\n## Additional Rules\n\nFor series_column, value_columns, legend, section organization, pie charts, stacking, and treat_missing_values — see `dashboard-builder` skill.\n\n**Import-specific:** Latency — always check the source metric's native unit FIRST with `query` before applying any conversion. Some metrics are in seconds (→ `* 1000`, `unit: \"ms\"`), others are already in milliseconds. Don't assume.\n\n---\n\n## Common Pitfalls\n\n1. **Macros in nested queries** — `{{time}}`, `label()`, `{{source}}` only work directly against `{{source}}`, not in outer queries. See `dashboard-builder` skill.\n\n2. **Nested aggregates forbidden** → Use CTEs for `sum by (label)(rate(...))` patterns.\n\n3. **Uptime/timestamps** → Use `maxMerge(value_max)` not `avgMerge(value_avg)`.\n\n4. **Gauge/number charts need series label** → Always include `'Label' AS series`. Number charts only display the chart title, so make it descriptive.\n\n5. **Always validate queries** — Run `query` before creating charts. A broken chart wastes more time than validating upfront.\n"Full snapshot data
{
"description": "Import Grafana dashboards from grafana.com templates. Translates PromQL to ClickHouse. Load when user asks to import, convert, or recreate a Grafana dashboard in Better Stack.",
"included_files": [
{
"relative_path": "references/chart-patterns.md",
"size_in_bytes": 7740
},
{
"relative_path": "references/cloudwatch-translation.md",
"size_in_bytes": 6176
},
{
"relative_path": "scripts/extract-layout.js",
"size_in_bytes": 17579
}
],
"name": "grafana-import",
"skill_md_contents": "---\nname: grafana-import\ndescription: Import Grafana dashboards from grafana.com templates. Translates PromQL to ClickHouse. Load when user asks to import, convert, or recreate a Grafana dashboard in Better Stack.\n---\n\n# Grafana Dashboard Import\n\n## Quick Start\n\n```bash\n# 1. Get summary first (always start here)\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --summary\nnode <this skill's directory>/scripts/extract-layout.js --file <path> --summary\n\n# 2. Extract and build section-by-section\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 1\n# ... build section 1 charts ...\nnode <this skill's directory>/scripts/extract-layout.js --dashboard <ID> --section 2\n# ... build section 2 charts ... and so on\n```\n\n## Tool Setup\n\nYou need the Better Stack dashboard tools (`create_dashboard`, `add_chart_to_dashboard`, `set_dashboard_variable`) and the query tools (`sources`, `source`, `metrics_schema`, `query`). If your client loads tools on demand, load them before starting.\n\nThe extract script is `scripts/extract-layout.js` in this skill's directory, run with Node.js 18 or newer. If you can't run scripts, read the export yourself and pull out the same fields: sections, panels, their queries, units and template variables.\n\n## Workflow\n\n1. **Extract summary:** `node scripts/extract-layout.js --dashboard <ID> --summary` — see all sections and panel counts\n2. **Check metrics:** `metrics_schema(id)` — identify available metrics AND their tags\n3. **Discover tag names:** `SELECT DISTINCT tags FROM {{source}} WHERE name = 'your.first.metric' LIMIT 5` — use exact tag names from real data, never guess\n4. **Create dashboard:** `create_dashboard(source_id, name)`\n5. **Translate template variables** — For each `templating.list` entry, create a Better Stack variable with `set_dashboard_variable` AND reference it in the queries that used `$name` via an optional `[[ ]]` clause. Never just omit them. See Template Variable Translation below.\n6. **Process section-by-section** — For each section:\n - Extract: `node scripts/extract-layout.js --dashboard <ID> --section <n>`\n - Build queries using translation rules below (load `metrics-query` skill)\n - Validate each query via `query` before creating charts\n - Add charts (load `chart-generation` + `dashboard-builder` skills), always pass `height: 6` and `section: \"Name\"`\n - Move to next section only after completing current one\n\n**Query translation checklist:**\n\n- Identify datasource type (Prometheus or CloudWatch) from extract output\n- For PromQL: match `rate()`/`irate()` to correct merge function, handle `sum by`/`avg by` aggregations\n- For CloudWatch: match `statistics` field (Average/Sum/Maximum/Minimum) to correct merge function\n- Check for multi-metric arithmetic (`a / b`) requiring CTEs\n\n### No-data mode (blind import)\n\n**Use ONLY when explicitly requested** (e.g., \"import without data\", \"no metrics available\", \"blind import\"). Never default to this mode — always try the normal workflow first.\n\nWhen the service has no metric data in Better Stack, you cannot validate queries. Instead:\n\n1. **Extract layout** as normal with the extract script\n2. **Skip `metrics_schema`** — you can't discover metrics or tags from live data\n3. **Derive metric names from the Grafana query:**\n - PromQL metrics: use as-is (Prometheus metrics keep their exact names in Better Stack)\n - CloudWatch metrics: translate `namespace/metricName` → underscore format with suffix (see `references/cloudwatch-translation.md`)\n4. **Derive tag names from the query:**\n - PromQL `by (label)` → `label('label')` (Prometheus labels keep their names)\n - CloudWatch `dimensions` → `label('snake_case')` (CloudWatch tags are snake_case)\n5. **Build queries using known patterns** — follow ALL translation rules from this skill\n6. **Self-review every query before creating the chart:**\n - Re-read the SQL character by character\n - Check: Does `{{time}}` only appear where `dt` is in scope? (pitfall #1)\n - Check: Does `value_columns` match the SQL alias exactly? (Mismatch = chart appears empty. Never leave as default `[\"value\"]` when SQL uses a descriptive alias.)\n - Check: Is the merge function correct for the statistic/aggregation?\n - Check: Is `series_column` set when there's a GROUP BY on a tag?\n - Check: For `unit: \"percent\"`, are values 0–1? (divide by 100 if needed)\n7. **Create the dashboard and charts** — follow all layout rules, height: 6, section naming\n8. **No cross-checking is possible** — there's no data to compare against\n\n**Key principle:** In no-data mode, the queries may not return results, but they must be **structurally correct** so they work once data starts flowing. A broken query (wrong column name, bad syntax, missing GROUP BY) is worse than no chart at all.\n\n---\n\n## Interpreting Extract Script Output\n\nThe extract script shows each panel with its type, queries, and layout info:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n `PromQL expression` → \"Legend format\"\n```\n\nOr for CloudWatch panels:\n\n```\n- **Panel Title** | chart_type (Grafana: grafana_type) | unit | x:N y:N w:N h:N {settings}\n CW: AWS/RDS.CPUUtilization [Average] dims: DBInstanceIdentifier=$dbinstance\n```\n\n**Decision tree for each panel:**\n\n1. **Check datasource type** — Prometheus (has `expr`) vs CloudWatch (has `namespace.metricName`):\n - PromQL → use PromQL translation rules\n - CloudWatch → use the CloudWatch translation rules in `references/cloudwatch-translation.md`\n - Both use `label()` for tag/label access\n\n2. **Check panel type** — determines chart type:\n - `timeseries` / `graph` → `line_chart` (default)\n - `timeseries` with `drawStyle: bars` → `bar_chart` with time dimension\n - `timeseries` with `stacking: normal` → `line_chart` with `stacking: \"stack\"`\n - `stat` / `singlestat` → `number_chart`, single scalar value\n - `gauge` / `bargauge` → `gauge_chart` or `bar_chart`\n - `table` → `table_chart`\n - `piechart` → `pie_chart`\n - `barchart` → `bar_chart` (category bar, no time dimension)\n - `heatmap` → `heatmap_chart`\n\n3. **Check for `by (labels)`** in PromQL or multi-dimension CloudWatch:\n - Present → Add tag-based series column and include in GROUP BY\n - Absent → single-series chart\n\n4. **Check for instant vs range queries:**\n - `instant: true` or stat/gauge panel → no `{{time}}`, scalar result\n - Range query or timeseries panel → needs `{{time}} AS time` and `GROUP BY time`\n\n---\n\n## PromQL → ClickHouse Translation\n\n### Function Mapping\n\n| PromQL | Line Chart | Gauge/Number |\n| ----------------------- | --------------------------- | -------------------------------------- |\n| `rate(metric[5m])` | `avgMerge(rate_avg)` | `avgMerge(rate_avg)` |\n| `irate(metric[5m])` | `avgMerge(rate_avg)` | **`argMax(rate, time)`** from subquery |\n| `metric` (gauge) | `avgMerge(value_avg)` | `argMax(value, time)` from subquery |\n| `sum(...)` / `avg(...)` | CTE + `sum()`/`avg()` | same |\n| `count by (label)` | `uniqExact(label('label'))` | same |\n| `clamp_min(x, 0)` | `greatest(x, 0)` | same |\n| `clamp_max(x, 100)` | `least(x, 100)` | same |\n\n### Why irate() Needs argMax for Gauges\n\n| Function | Computes |\n| ------------------------------- | -------------------------------- |\n| Prometheus `irate()` | Instant rate from last 2 samples |\n| ClickHouse `avgMerge(rate_avg)` | Average rate over entire window |\n\nUse `argMax(rate, time)` to get the most recent bucket's rate (90-99% match vs Prometheus).\n\n### Aggregation Over Time\n\n| PromQL | ClickHouse |\n| --------------------------- | --------------------- |\n| `avg_over_time(metric[5m])` | `avgMerge(value_avg)` |\n| `max_over_time(metric[5m])` | `maxMerge(value_max)` |\n| `min_over_time(metric[5m])` | `minMerge(value_min)` |\n\n### Arithmetic Operations\n\n| PromQL | ClickHouse |\n| --------------------- | ------------------------------------------------------- |\n| `metric_a / metric_b` | CTE + `sumIf(value, name='a') / sumIf(value, name='b')` |\n| `metric * 100` | `avgMerge(value_avg) * 100` |\n| `1 - metric` | `1 - avgMerge(value_avg)` |\n\n### Tag Access\n\nAll metric types (Prometheus, CloudWatch, collector) use `label('tag_name')` to access tags:\n\n```sql\n-- Access a tag\nlabel('device') AS series\n\n-- Filter by tag\nWHERE label('mode') = 'idle'\n\n-- Group by tag\nGROUP BY label('device')\n```\n\n**Prometheus labels keep their original names** — `instance`, `job`, `device`, `mode`, `cpu`, etc. Always verify with a test query.\n\n**CloudWatch dimensions are snake_case** — `DBInstanceIdentifier` → `db_instance_identifier`. See `references/cloudwatch-translation.md` for the full mapping.\n\n### PromQL Variable Translation\n\n| Grafana token | ClickHouse handling |\n| ------------------ | ----------------------------------------------------------------- |\n| `$__rate_interval` | Ignore — `{{time}}` handles bucketing |\n| `$__interval` | Ignore |\n| `{label=\"$var\"}` | `[[ AND label('label') = {{var}} ]]` (single-value variable) |\n| `{label=~\"$var\"}` | `[[ AND match(label('label'), {{var}}) ]]` (multi-value variable) |\n| `{job=\"$job\"}` | `[[ AND label('job') = {{job}} ]]` |\n\nDo NOT just omit `$var` label filters — recreate each as a dashboard variable and reference it with an optional `[[ ]]` clause. See Template Variable Translation below.\n\n### Template Variable Translation\n\nGrafana `templating.list` variables (the `$var` selectors at the top) must be recreated as **Better Stack dashboard variables** — a variable only appears once a query references it, so do BOTH steps.\n\nFor each entry in `templating.list` (skip `type: interval` → `{{time}}` handles it; skip `datasource`/`adhoc`):\n\n1. **Create the variable** with `set_dashboard_variable` (type reference: `dashboard-builder` skill → \"Dashboard template variables\"):\n - `type: query` (e.g. `label_values(node_cpu_seconds_total, instance)`) → `multi_select_with_sql` (or `select_with_sql` if `multi: false`), `sql_definition: \"label('<label>')\"` where `<label>` is the label the variable queries (Prometheus labels keep their names; CloudWatch dimensions → snake_case).\n - `type: custom` (fixed options) → `select_value`, `default_values: [the option values]`.\n - `type: constant` / `textbox` → `string`, `default_values: [value]`.\n2. **Reference it in every query that used `$name`** (or `${name}` / `[[name]]`), as an OPTIONAL `[[ ]]` clause so charts render with nothing selected (matches Grafana's \"All\" default):\n - multi: `[[ AND match(label('<label>'), {{name}}) ]]`\n - single: `[[ AND label('<label>') = {{name}} ]]`\n\nName the variable after the Grafana variable's `name`.\n\nExample — `templating.list: [{ name: \"instance\", type: \"query\", query: \"label_values(node_cpu_seconds_total, instance)\", multi: true }]`, PromQL `rate(node_cpu_seconds_total{instance=~\"$instance\"}[5m])`:\n\n1. `set_dashboard_variable(dashboard_id, name: \"instance\", variable_type: \"multi_select_with_sql\", sql_definition: \"label('instance')\")`\n2. `SELECT {{time}} AS time, label('instance') AS series, avgMerge(rate_avg) AS \"CPU\" FROM {{source}} WHERE name = 'node_cpu_seconds_total' [[ AND match(label('instance'), {{instance}}) ]] GROUP BY time, series`\n\n---\n\n## CloudWatch → ClickHouse Translation\n\nFor CloudWatch panels, read `references/cloudwatch-translation.md` (in this skill's directory): metric name translation, statistic mapping, the `Sum` statistic and hidden dimensions, dimension mapping and filters, and metric math.\n\n## Panel Type Mapping\n\n| Grafana panel | Better Stack chart | Notes |\n| ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |\n| `timeseries` | `line_chart` | Default; time-series with `{{time}}` |\n| `timeseries` (drawStyle: bars) | `bar_chart` | Time-series bars — needs `{{time}}` |\n| `timeseries` (stacking: normal) | `line_chart` | `stacking: \"stack\"` |\n| `graph` (legacy) | `line_chart` | Same as timeseries |\n| `stat` | `number_chart` | Single value, no time |\n| `singlestat` (legacy) | `number_chart` | Same as stat |\n| `gauge` | `gauge_chart` | |\n| `bargauge` | `gauge_chart` | |\n| `table` / `table-old` | `table_chart` | Set `column_units` per column + `percentage_highlight_columns` for ratio cols (see chart-generation skill) |\n| `barchart` | `bar_chart` | Category bar, no time dimension |\n| `piechart` | `pie_chart` | |\n| `heatmap` | `heatmap_chart` | |\n\n**Skip:** `text`, `row`, `news`, `dashlist`, `alertlist`, `annolist`, `logs`, `nodeGraph`, `traces`, `flamegraph`, `canvas`, `geomap`\n\n### Bar chart configuration\n\nGrafana **`barchart`** → category bar chart (no `{{time}}`); **`timeseries` with drawStyle bars** → time-series bar chart. Configure per the `chart-generation` skill's Bar Chart Configuration (category bars need `x_axis_type: \"category\"` + `time_column: \"series\"`).\n\n---\n\n## Unit Mapping (Grafana → Better Stack)\n\n| Grafana unit | Better Stack unit | Notes |\n| ------------------- | ----------------- | ------------------------------------------------------------------------------------------- |\n| `bytes`, `decbytes` | `B_si` | |\n| `bits`, `decbits` | `bps` | Only if rate; otherwise `B_si` |\n| `Bps` (bytes/sec) | `B_si` | |\n| `bps` (bits/sec) | `bps` | PromQL `* 8` for bytes→bits |\n| `s` | `s` | |\n| `ms` | `ms` | |\n| `us`, `µs` | `μs` | |\n| `ns` | `ns` | |\n| `percent` | `percent` | **Grafana `percent` = 0–100 input; Better Stack `percent` = 0–1 input. MUST divide by 100** |\n| `percentunit` | `percent` | Grafana `percentunit` = 0–1 input — maps directly, no conversion |\n| `short` | `shortened` | |\n| `none` | `shortened` | |\n| `ops`, `iops` | `e/s` | |\n| `reqps` | `rps` | |\n| `locale` | `shortened` | |\n| `celsius` | (custom) | Last resort — use `unit: \"none\"`, add \"°C\" in title |\n| `hertz` | `e/s` | |\n\n**Always prefer predefined units.** The table above covers nearly all Grafana units. Never use `custom_unit` when a predefined Better Stack unit exists (e.g., use `B_si` not `custom_unit: \"bytes\"`, use `e/s` not `custom_unit: \"/s\"`, use `B_si/s` not `custom_unit: \"bytes/sec\"`). Custom units lack auto-scaling and produce worse formatting. Only use `custom_unit` for truly exotic units like °C where no predefined equivalent exists.\n\n**CRITICAL: Grafana `percent` vs `percentunit`:**\n\n- Grafana `percent` → values are 0–100. Better Stack `percent` expects 0–1. **You MUST divide by 100 in the query** or values will display as 4000% instead of 40%.\n- Grafana `percentunit` → values are 0–1. Maps directly to Better Stack `percent`. No conversion needed.\n\n**Default unit for counts:** Connection counts, query counts, transaction counts, and similar integer metrics should use `unit: \"shortened\"` for auto-scaling (1.5K, 2.3M). Do NOT leave unit unset on count metrics.\n\n---\n\n## Naming Convention\n\nFollow the `dashboard-builder` skill's naming rules (sentence case, no abbreviations, no units or parentheses in titles). Grafana templates often use \"Avg\"/\"Max\"/\"Config\" and parenthetical units (\"Output events bytes rate (bytes/sec)\") — always expand/strip at chart-create time.\n\n---\n\n## Line Chart Patterns\n\nRead `references/chart-patterns.md` (in this skill's directory) before you write a panel's query: it has worked PromQL and CloudWatch → ClickHouse translations for line charts (counter rates, sums by label, arithmetic, composite series, bytes to bits) and for gauge and number charts (irate, instant values, uptime, static numbers, Grafana Stat `reduceOptions`).\n\n## Layout Conversion\n\n- **Grafana grid:** 24 columns → divide x and w by 2 for Better Stack's 12-column grid\n- **Heights:** Always `height: 6` (ignore Grafana heights)\n- **Rows:** `type: \"row\"` panels → `section: \"Row Title\"`\n\nThen apply the `dashboard-layout` skill's rules and planning process (rows sum to 12, prefer 3 per row, no full-width charts, no orphan rows, number charts ≤ w:4).\n\n---\n\n## Additional Rules\n\nFor series_column, value_columns, legend, section organization, pie charts, stacking, and treat_missing_values — see `dashboard-builder` skill.\n\n**Import-specific:** Latency — always check the source metric's native unit FIRST with `query` before applying any conversion. Some metrics are in seconds (→ `* 1000`, `unit: \"ms\"`), others are already in milliseconds. Don't assume.\n\n---\n\n## Common Pitfalls\n\n1. **Macros in nested queries** — `{{time}}`, `label()`, `{{source}}` only work directly against `{{source}}`, not in outer queries. See `dashboard-builder` skill.\n\n2. **Nested aggregates forbidden** → Use CTEs for `sum by (label)(rate(...))` patterns.\n\n3. **Uptime/timestamps** → Use `maxMerge(value_max)` not `avgMerge(value_avg)`.\n\n4. **Gauge/number charts need series label** → Always include `'Label' AS series`. Number charts only display the chart title, so make it descriptive.\n\n5. **Always validate queries** — Run `query` before creating charts. A broken chart wastes more time than validating upfront.\n"
}SHA-256 of public snapshot: cac4361893a8f37f3a8125240adb70caba7cba2977a606ab267d4460f2aa3467