← Better StackCONTENT HISTORY

Update to Better Stack

Snapshot Nov 13, 2026 · 12:08 UTC · version 1.3.14

Collection source: downloaded plugin package.

WHAT CHANGED

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.

Save Better Stack and check future changes in Following.

Up to 3 plugins free · no card required.

All fields and original values.

Skill instructions

Before

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...

After

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

Before

Nov 11, 2026 · 06:08 UTC

[]

After

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 JSON

SKILL.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

BEFORE
[]
AFTER
[
  {
    "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

BEFORE
"---\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"
AFTER
"---\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