From 8868fc3018378f6aec29bfcb25fac1f246bc3f92 Mon Sep 17 00:00:00 2001 From: Arthur Verrez Date: Tue, 23 Jun 2026 13:06:41 +0200 Subject: [PATCH] docs(tsuga-build-dashboard): document query alias key format The alias key format was undocumented and easy to get wrong: aliases.queries is keyed by the query's zero-based index as a string, not formula's q1/q2. Mis-keyed aliases are silently ignored and legends fall back to a generated label. Patch bump 0.8.2 -> 0.8.3. --- .claude-plugin/marketplace.json | 2 +- plugins/tsuga/.claude-plugin/plugin.json | 2 +- .../tsuga/skills/tsuga-build-dashboard/SKILL.md | 1 + .../references/widget-reference.md | 15 +++++++++++++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2383665..59a92f7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Tsuga toolkit for AI coding agents: one plugin with the tsuga CLI driver, live-platform investigation, dashboards, incident workflows, OpenTelemetry instrumentation, Collector, signal-choice, telemetry debug, and audit skills.", - "version": "0.8.2" + "version": "0.8.3" }, "plugins": [ { diff --git a/plugins/tsuga/.claude-plugin/plugin.json b/plugins/tsuga/.claude-plugin/plugin.json index a5ab312..3539002 100644 --- a/plugins/tsuga/.claude-plugin/plugin.json +++ b/plugins/tsuga/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "tsuga", "description": "Tsuga observability plugin: the `tsuga` CLI driver (commands, TQL syntax, aggregation bodies, counter math, deep links, cloud/k8s translators); live-platform investigation for service health, errors, latency, and monitor coverage; dashboard building; incident orchestration; OpenTelemetry SDK, Collector, OTTL, signal-choice, telemetry debug, and audit skills; and meta-skills for building and validating skill bundles.", - "version": "0.8.2", + "version": "0.8.3", "author": { "name": "Tsuga Engineering", "email": "engineering@tsuga.com" diff --git a/plugins/tsuga/skills/tsuga-build-dashboard/SKILL.md b/plugins/tsuga/skills/tsuga-build-dashboard/SKILL.md index 2f0db01..15791c6 100644 --- a/plugins/tsuga/skills/tsuga-build-dashboard/SKILL.md +++ b/plugins/tsuga/skills/tsuga-build-dashboard/SKILL.md @@ -79,6 +79,7 @@ Key structural rules: - `owner` must be a team ID — resolve with `tsuga teams list` - Each graph requires a unique `id`, a `visualization` object, and a `layout` object - `query-value` does not support `groupBy` — the API silently drops it +- Name each series in the legend via `visualization.aliases.queries`, keyed by the query's zero-based index as a string (`"0"`, `"1"`, ...) — NOT `formula`'s `"q1"`/`"q2"`; wrong keys are silently ignored (see `references/widget-reference.md`) - List-style widgets take a single `query` string. Variants: `list` (logs matching a Tsuga query), `list-log-patterns` (logs clustered into patterns), `list-connection` (datastore rows via `connectionId` + read-only SQL) - Include dashboard-level env + team filters when they are relevant to the dashboard audience: diff --git a/plugins/tsuga/skills/tsuga-build-dashboard/references/widget-reference.md b/plugins/tsuga/skills/tsuga-build-dashboard/references/widget-reference.md index 2327f47..bca494c 100644 --- a/plugins/tsuga/skills/tsuga-build-dashboard/references/widget-reference.md +++ b/plugins/tsuga/skills/tsuga-build-dashboard/references/widget-reference.md @@ -25,6 +25,21 @@ Max 15 queries per widget. `formula` references queries by position: `"q1"` = fi **Never send an empty `name` or `description` (`""`)** — the API rejects it with a 400 (`must NOT have fewer than 1 characters`). When a widget has no label (common for notes), **omit the key entirely** rather than passing `""`. (For aggregate/query-body rules — `count` not valid on `metrics`, Unix-seconds `timeRange`, etc. — see `tsuga-cli`.) +### Series names in the legend (`aliases`) + +Every series renders with an auto-generated label like `Count on ()` unless you name it. To set legible legend names, add `aliases` to the visualization: + +```json +"aliases": { + "queries": {"0": "Humans", "1": "AI agents", "2": "Automation"}, + "formula": "Programmatic %" +} +``` + +- `aliases.queries` is keyed by each query's **zero-based index as a string** — `"0"` is the first query in `queries`, `"1"` the second, and so on. +- ⚠️ this key is NOT the `formula` syntax. `formula` references queries as `"q1"`, `"q2"`; `aliases.queries` uses `"0"`, `"1"`. Using `"q1"` as an alias key is silently ignored and the generated label stays. +- Works on every aggregation widget (`timeseries`, `top-list`, `pie`, `bar`, `gauge`, ...). On `table`, aliases are set per column instead (see the `table` section). + --- ## `timeseries`