Greptimedb Perses Dashboard

Perses Dashboard Generator

Generate Perses Dashboard or single Panel JSON for the GreptimeDB Dashboard app.

Read first: catalog.md — panel shapes, JSON examples, live dashboard index.

Also: reference.md (schema, SQL/PromQL rules).

Output modes:

Datasource constraint (hard rule)

Greptime Dashboard only supports two datasource plugins. Never use any other kind or name:

Forbidden: Loki, Tempo, Elasticsearch, InfluxDB, ${ds}, Grafana datasource variables, inline URLs, or any other datasource.

When migrating Grafana JSON, replace all datasource references with promql-default or sql-default.

Data access (required)

Before generating panels, discover real table/column names and dry-run queries. Use either path below — not both unless cross-checking.

Do not invent table/column names without discovery.

MCP (GreptimeDB MCP server)

The GreptimeDB MCP server is agent-agnostic — any host that implements the Model Context Protocol can use it (Cursor, Claude Desktop, Claude Code, VS Code Copilot, Codex, Gemini CLI, custom runners, etc.). The server name in config may vary (e.g. user-greptimedb, greptimedb); tool names below are what the server exposes.

MCP host/auth is not passed per tool call — it is set once in the agent’s MCP config (stdio command, env vars, or remote URL). If health_check fails, fix that MCP server entry or fall back to HTTP.

HTTP (no MCP)

Same operations via GreptimeDB HTTP API on {host}:

Confirm host (HTTP only) — resolve in order, stop when a probe succeeds:

1. User-provided URL (e.g. https://greptime.example.com, http://127.0.0.1:4000)
2. GREPTIME_HOST environment variable
3. Local default: http://127.0.0.1:4000 (GreptimeDB HTTP API; matches config/vite.config.base.ts dev proxy target)
4. Same origin as Dashboard UI — if the user runs Greptime Dashboard in dev, frontend /v1/* is proxied to 127.0.0.1:4000; direct curl still targets that backend unless deployed otherwise

Probe (replace host and auth as needed):

HOST="${GREPTIME_HOST:-http://127.0.0.1:4000}"
curl -sS -o /dev/null -w "%{http_code}" -X POST "$HOST/v1/sql" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "sql=SELECT 1"
# Expect HTTP 200

Auth headers for HTTP: GREPTIME_AUTH (Basic), GREPTIME_DB (x-greptime-db-name) — same as save-dashboard.sh. Full curl patterns: reference.md — HTTP API.

If discovery and HTTP both fail, use offline catalog.md shapes only and tell the user which host/MCP setting is missing.

Live reference API

Fetch existing dashboards before generating (match real query/panel shapes):

curl -s "${GREPTIME_HOST:-http://127.0.0.1:4000}/v1/dashboards"

See catalog.md for parsed panel JSON per modality.

Workflow

1. Clarify input

Identify one of:

• Table name (schema.table or public.my_table)
• Natural language goal ("monitor CPU", "temperature by location")
• Existing SQL or PromQL query
• Grafana JSON to migrate (use percli migrate, then tweak — see reference.md)
• Multi-modal observability (metrics + logs + traces)
• Single panel only (paste into Perses editor → Add panel → JSON)

Default to single panel when the user mentions: panel, single panel, paste JSON, add panel, import panel.

Default to full dashboard when the user mentions: dashboard, save dashboard, /v1/dashboards.

2. Choose data path

Follow the Greptime + Perses guide:

3. Discover data (MCP or HTTP)

SQL path — MCP: describe_table + execute_sql … LIMIT 5. HTTP: DESCRIBE TABLE / information_schema + POST /v1/sql.

Identify:

• Time column: use schema detection (below) — not column-name guessing
• Time unit: read data_type for Nanosecond vs Millisecond — nanosecond columns (e.g. web_trace_demo.timestamp) must use to_timestamp_millis(col) AS ts in TimeSeriesChart / Table queries or the UI can hang/crash (reference.md — Timestamp precision)
• Value columns: numeric fields for charts
• Tag columns: dimensions for series grouping (host, loc, sensor_id)
• Trace columns: trace_id, span_id, parent_span_id
• Log columns: message, content, body, level

Time column (same as SQL Builder — src/components/sql-builder/index.vue, src/utils/table-normalizer.ts):

1. From describe_table columns, keep those where data_type.toLowerCase().includes('timestamp')
2. Prefer semantic_type === 'TIMESTAMP'
3. Pick the first match in that preferred set; else the first timestamp data_type column
4. If none → no time column; do not assume ts / greptime_timestamp by name

See reference.md — Time column detection.

PromQL path — MCP: query_range. HTTP: GET /v1/prometheus/api/v1/query_range (or labels API).