| name | grafana-to-guance-dashboard |
| author | liurui |
| description | Convert Grafana dashboard JSON into Guance dashboard JSON with a fully self-contained skill package. Use when the user wants to analyze Grafana dashboards before conversion, run conversion, audit conversion gaps, improve units or PromQL compatibility with LLM-assisted review, repair panel or variable mappings, preserve settings, groups, and vars as much as possible, validate generated Guance dashboard JSON against the bundled schemas, or debug why a Grafana dashboard does not convert cleanly. |
Grafana To Guance Dashboard
Overview
Use this skill when working on Grafana dashboard to Guance dashboard conversion as a standalone package.
This skill is self-contained. Use only the files in this skill directory unless the user explicitly asks to compare with older repository code or migrate logic elsewhere.
This is not just a script-running skill. Use the LLM before and after conversion to analyze risk, explain missing mappings, compare Grafana and Guance structures, infer likely units when Grafana leaves them implicit, audit PromQL dialect differences, and propose or implement converter fixes.
For the default end-to-end operating sequence, also use references/conversion-audit-checklist.md.
The skill directory now includes its own:
- converter scripts
- validation script
- schema copy
- fixture input
- test suite
package.json for standalone dependency installation
Core Workflow
- Change into the skill root directory.
- Install standalone dependencies with
npm install when needed.
- Read the input Grafana dashboard and perform a preflight analysis before running the converter.
- Identify the output path and choose conversion flags.
- Run the standalone skill script.
- Validate the generated Guance dashboard against the skill-local schemas.
- Audit the conversion result:
- compare Grafana panel count to Guance chart count
- identify dropped or partially converted panels
- identify variable and query mapping gaps
- identify missing or suspicious unit mappings
- identify PromQL expressions that may need Guance-specific normalization
- explain likely causes
- If conversion gaps remain, patch the standalone skill script in this skill directory and re-run validation.
- Run the skill-local test suite before finishing substantial changes.
- Produce a concise conversion report for the user.
- Only inspect older repository converters if the user explicitly asks to compare outputs or port behavior.
Schema maintenance follows these defaults:
- treat
test/guance-all-charts.json as the baseline real Guance export sample
- when a local schema disagrees with that sample, first decide whether the schema is too strict before changing converter output
- prefer binding
chart.type -> extend.settings in schemas/charts/chart-schema.json whenever a dedicated settings schema exists
- prefer allowing explicit empty or null states that appear in real exports, instead of rejecting them just because they are unset
LLM Responsibilities
Use the model for the parts that the deterministic converter cannot do reliably on its own.
- Preflight analysis:
- inspect panel types, datasources, variables, transformations, and likely risk areas before conversion
- decide whether to recommend
--guance-promql-compatible or --keep-grafana-meta
- Unit inference:
- when Grafana does not provide an explicit unit, inspect metric names, PromQL functions, panel titles, legends, and threshold semantics
- infer likely units such as bytes, percent, ms, s, reqps, ops, or count-like
none
- separate high-confidence guesses from low-confidence guesses
- PromQL compatibility audit:
- inspect whether Grafana-side PromQL assumes naming or selector conventions that differ from Guance expectations
- flag queries that may need
measurement:field normalization, label handling adjustments, or manual rewrite
- distinguish safe rewrites from suspicious rewrites that need human review
- Post-conversion audit:
- compare input Grafana structure to output Guance structure
- explain which panels converted cleanly, which were dropped, and which are only partially represented
- explain where units, query semantics, or chart intent were guessed instead of explicitly mapped
- Repair mode:
- inspect the original Grafana panel JSON plus the generated Guance chart JSON
- infer whether the gap belongs in panel type mapping, query classification, settings extraction, variable conversion, or layout conversion
- propose and, when asked, implement the smallest converter patch that closes the gap
- Reporting:
- summarize risk, output quality, missing mappings, and next actions in user-facing language
Do not use the LLM to replace deterministic conversion logic when a stable script rule is more appropriate. Use the LLM to analyze, compare, explain, and narrow down the next converter change.
When the LLM makes an inference, state the confidence level and reason. Prefer:
high
- strong signal from explicit metric names, titles, units, or standard PromQL patterns
medium
- probable signal from multiple weak hints
low
- ambiguous cases that should be surfaced for review rather than silently accepted
Preferred Modes
Choose the mode that matches the user request.
analyze
- inspect a Grafana dashboard without converting it yet
- report likely risks, unsupported panel types, datasource concerns, and recommended flags
convert
- run the converter and validate the output
audit
- compare Grafana input and Guance output to identify missing or partial mappings
unit-audit
- identify panels where unit inference is missing, suspicious, or worth improving
compatibility
- inspect PromQL expressions for Grafana-to-Guance dialect mismatches and recommend flags or rewrites
repair
- patch the standalone converter to improve one concrete conversion gap
report
- produce a concise handoff summary for human review or the next agent
Commands
Use these commands from the skill root directory.
npm install
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.json \
--validate
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.guance-promql.json \
--validate \
--guance-promql-compatible
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.keep-meta.json \
--validate \
--keep-grafana-meta
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.keep-job.json \
--validate \
--keep-job-variable
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.sls.json \
--validate \
--sls-namespace L
npm run convert -- \
--input ./fixtures/grafana-dashboard.json \
--output ./output/guance-dashboard.mysql.json \
--validate \
--mysql-external-datasource custom.mysql.datasource
npm run validate:file -- ./output/guance-dashboard.json
npm test
Preflight Checklist
Before converting, inspect:
- panel types present in the dashboard
- datasource types used by variables and targets
- row panels and collapse behavior
- transformations, overrides, and panel links
- built-in Grafana variables versus user-defined variables
- query fields used by targets such as
expr, query, queryText, expression, and rawSql
- likely implied units from metric names, panel titles, legends, and query structure
- likely PromQL dialect mismatches between Grafana usage and Guance usage
Call out:
- unsupported panel types
- dashboards likely to need
--keep-grafana-meta
- dashboards likely to benefit from
--guance-promql-compatible
- panels whose unit is likely implicit and should be inferred during audit
- dashboards likely to need manual cleanup after conversion
- whether Grafana datasource variables such as
ds_prometheus can be dropped outright
- whether the target Guance dashboard still needs a
job variable; if not, drop the variable and its query filters
- whether the dashboard mixes
prometheus, cloudwatch, or aliyun-log-service-datasource
- whether SLS panels already contain
FROM <logstore> or still need a source such as logstore / logstoreName
Post-Conversion Audit
After converting, always check:
- how many Grafana panels were present
- how many Guance charts were emitted
- which Grafana panels were dropped or collapsed into groups
- whether expected variables were converted
- whether query text and qtype classification look correct
- whether unit mapping is explicit, inferred with confidence, or still missing
- whether PromQL normalization looks safe or suspicious
- whether important settings were mapped or only preserved under
extend.grafana
- whether validation passed cleanly
When gaps are found, explain them explicitly instead of only saying the output is invalid or incomplete.
Conversion Report
When the user asks for conversion, audit, or repair work, provide a short report that includes:
- input file
- output file
- flags used
- validation result
- converted successfully
- dropped or unsupported panels
- partial mappings or suspicious settings
- inferred units and their confidence when relevant
- PromQL compatibility concerns and whether
--guance-promql-compatible was used
- recommended next step
Use this shape by default:
Conversion report
- input: ...
- output: ...
- flags: ...
- validation: pass | fail
- panel summary: X Grafana panels -> Y Guance charts
- dropped: ...
- partial: ...
- units inferred: ...
- compatibility concerns: ...
- next step: ...
Decision Rules
Use these defaults unless the user asks otherwise.
- Recommend
--guance-promql-compatible when:
- most queries are PromQL
- metric names follow underscore-heavy Prometheus naming
- the dashboard appears intended for Guance metrics compatibility rather than stock Prometheus naming
- Do not recommend
--guance-promql-compatible when:
- the dashboard already mixes Guance-native metric names
- query text looks hand-tuned for a non-Guance Prometheus backend
- normalization would be low-confidence or risky
- Recommend
--keep-grafana-meta when:
- the user is debugging missing settings or dropped panels
- plugin-specific options or complex transformations are present
- the conversion result needs a detailed forensic comparison
- Do not enable
--keep-grafana-meta by default for final output unless debugging context is explicitly useful
- Drop Grafana datasource selector variables such as
ds_prometheus by default because Guance does not need datasource parameters.
- Drop the Grafana
job variable and related query filters by default.
- Use
--keep-job-variable only when the user confirms the target Guance dashboard still depends on job.
- Keep Prometheus datasource targets on the existing default conversion path.
- Force CloudWatch targets to use
promql query type.
- Route
aliyun-log-service-datasource targets through the local sls2dql converter first, and use --sls-namespace when the default log namespace is not correct.
- Map MySQL query variables to the Guance external datasource
DFF672F02CAD7D94CA1ABA9B6213537875C.syn_huoshan_mysql by default.
- Override MySQL mappings with
--mysql-external-datasource <id> for a simple replacement or --sql-datasource-map <json|@file> for per-type or per-uid mappings.
- Emit MySQL query variables using the minimal Guance
OUTER_DATASOURCE shape; keep extend limited to starMeaning.
- Emit MySQL
table panel targets as native Guance outer_datasource queries instead of the older compatibility wrapper.
- For mapped MySQL
table queries, write the datasource id to query.funcName and emit query.type: "func".
- Normalize the outermost MySQL
table SQL select list: time fields must be emitted as integer UNIX millisecond time; when no explicit time field exists and the query has a FROM clause, default to create_time; label fields must use AS tag_<name>; and the final query must use LIMIT 5000.
- Keep SLS conversion metadata internal to the converter; do not emit
slsConversion-style debug payloads into final dashboard JSON.
Confidence Rules
When reporting inferred units or compatibility advice, classify each item as:
high
- explicit metric suffixes or standard patterns strongly support the conclusion
medium
- multiple hints support the conclusion, but at least one ambiguity remains
low
- evidence is weak or conflicting
For low confidence cases:
- surface the issue explicitly
- avoid presenting the guess as settled fact
- prefer saying manual review is needed
Panel Audit Template
When the user asks for a deeper audit, summarize per panel using a compact structure:
- panel: <title>
status: clean | partial | dropped | suspicious
chart type: <grafana type> -> <guance type or none>
query: promql | dql | unknown
unit: explicit | inferred(high/medium/low) | missing
notes: <main risk or mapping gap>
Do not enumerate every panel when the dashboard is large unless the user asks for that level of detail. Prefer summarizing only the risky, dropped, or suspicious panels.
Audit Examples
Use outputs like these as style references. Do not copy them blindly; adapt them to the actual dashboard.
Example: missing unit, high confidence
Conversion report
- input: ./fixtures/example.json
- output: ./output/example.guance.json
- flags: --validate
- validation: pass
- panel summary: 12 Grafana panels -> 12 Guance charts
- dropped: none
- partial: one latency panel kept its chart but had no explicit unit in Grafana
- units inferred:
- API P95 Latency -> ms (high)
reason: query contains `histogram_quantile`, panel title contains `Latency`, metric names contain `_bucket`
- compatibility concerns: none
- next step: accept output and spot-check latency charts in UI
Example: PromQL compatibility concern
Conversion report
- input: ./fixtures/example.json
- output: ./output/example.guance-promql.json
- flags: --validate --guance-promql-compatible
- validation: pass
- panel summary: 8 Grafana panels -> 8 Guance charts
- dropped: none
- partial:
- one panel marked suspicious because metric names may already be Guance-native
- units inferred: none
- compatibility concerns:
- Request Volume panel -> suspicious
reason: query mixes underscore-style Prometheus metrics with a recording-rule name that already contains `:`
- next step: review the rewritten query before using this output as final
Example: dropped panel with repair suggestion
- panel: JVM Heap Breakdown
status: dropped
chart type: state-timeline -> none
query: promql
unit: inferred(high) -> bytes
notes: panel type is unsupported; likely next fix belongs in panel type map plus settings conversion
Unit Inference Cheatsheet
Use references/unit-inference-cheatsheet.md when:
- unit inference is part of the user request
- panel units are missing or suspicious
- you need a quick evidence-based guess before proposing a converter change
Treat the cheatsheet as a guide, not a hard rule. If real dashboard context contradicts it, explain why.
PromQL Compatibility Cheatsheet
Use references/promql-compatibility-cheatsheet.md when:
- PromQL compatibility is part of the user request
- you need to decide whether
--guance-promql-compatible is a good default
- rewritten queries look suspicious
- Grafana queries appear to mix Prometheus-native naming with Guance-native naming
Treat the cheatsheet as a review aid, not an automatic rewrite mandate.
Repair Example
Use a flow like this when moving from audit to repair.
Observed issue
- panel: Request Volume
- status: suspicious
- chart type: timeseries -> sequence
- query: promql
- unit: inferred(high) -> reqps
- notes: query rewrites metric names, but one recording-rule metric already contains `:`
Reasoning
- base mapping is probably correct
- the main risk is not panel type
- the likely gap belongs in PromQL normalization, not in settings conversion
Patch plan
- inspect the normalization rule that rewrites `metric_name` to `measurement:field`
- keep underscore-style Prometheus metric names eligible for rewrite
- skip rewriting tokens that already contain `:`
- re-run conversion with and without `--guance-promql-compatible`
- compare the resulting query text and keep the safer variant
User-facing summary
- the panel was not dropped
- the chart type is acceptable
- the risky part is query normalization
- next step is a small normalization patch, not a broad converter refactor
Script Layout
The skill script directory contains two files:
scripts/convert-grafana-dashboard.mjs
- executable wrapper
- parses CLI args
- validates output against local schemas
- imports
./convert-grafana-dashboard-core.js
scripts/convert-grafana-dashboard-core.js
- pure conversion logic
- no file-system or schema-validation responsibilities
The skill directory also includes:
scripts/validate-file.mjs
- standalone validation entrypoint
- always validates against the skill-local
schemas/
schemas/
- local schema copy used for standalone validation
fixtures/
- bundled sample Grafana dashboard for standalone smoke tests
test/
- bundled standalone regression tests
package.json
- standalone runtime dependencies and convenience scripts
Treat these two files as the source of truth for this skill.
How To Edit
This skill must remain usable on its own. Do not rely on repository sync/build steps as the default workflow.
- For conversion behavior changes:
- edit
scripts/convert-grafana-dashboard-core.js
- For CLI / validation behavior changes:
- edit
scripts/convert-grafana-dashboard.mjs
- After editing:
- re-run the standalone converter command from this skill
- re-run validation against the target output file
- re-run the post-conversion audit
Only touch repository-level converters or build scripts when the user explicitly asks to keep them in sync.
What The Standalone Skill Converter Supports
- Grafana variables of type
query, custom, textbox, constant, and interval
- Grafana datasource variables such as
ds_prometheus are intentionally skipped because Guance dashboards do not need datasource selector params
- Grafana row panels mapped to Guance groups
- Row collapse state mapped to
dashboardExtend.groupUnfoldStatus
- Panel links gathered from panel links, default links, and override links
- Common panel types:
stat, singlestat -> singlestattimeseries, graph -> sequencebarchart -> barpiechart -> piehistogram -> histogrambargauge -> toplistgauge -> gaugetable -> tabletext -> textheatmap -> heatmaptreemap -> treemap
- Query extraction from Grafana
targets[] using expr, query, or queryText
- Datasource-aware query classification for Prometheus-like, CloudWatch, SLS, and SQL-like targets
guance-guance-datasource targets default to dql, but explicit qtype: "promql" is preserved as promqlcloudwatch targets are emitted as promqlaliyun-log-service-datasource targets are converted via the repository-local ./sls2dql/bin/sls2dql tool and emitted as dql--sls-namespace can override the default SLS log namespace L- SLS conversion status is used only during conversion and is not emitted as dashboard metadata
- MySQL query variables are emitted as
datasource: "outer_datasource" and type: "OUTER_DATASOURCE"
- MySQL query variable datasource ids are written to
definition.metric
- MySQL query variable
extend only keeps starMeaning, matching the real Guance export shape
- when a MySQL variable is currently
All / $__all, the emitted definition.defaultVal is normalized to empty strings
- when a MySQL variable already has a concrete selected value, the emitted
definition.defaultVal keeps that value
- MySQL
table panel targets are emitted as native Guance outer_datasource queries
- mapped MySQL
table queries use qtype: "outer_datasource" plus query.type: "func"
- the mapped external datasource id is written to
query.funcName
- the outermost MySQL
table SQL select list is normalized for Guance external datasource typing
- time fields are emitted as integer UNIX millisecond
time; when no time-like field exists and the query has a FROM clause, emit CAST(UNIX_TIMESTAMP(create_time) * 1000 AS SIGNED) AS time; remove Grafana time-range macro filters from the outer WHERE
- label fields are emitted with
AS tag_<name>
- the outer query limit is forced to
LIMIT 5000
- the default MySQL external datasource id is
DFF672F02CAD7D94CA1ABA9B6213537875C.syn_huoshan_mysql
--sql-datasource-map <json|@file> supports customer mappings such as {"byUid":{"mysql-1":"custom.mysql.datasource"},"byType":{"mysql":"fallback.mysql.datasource"}}[$__rate_interval] is removed from PromQL queries during conversion[$__interval] is removed from PromQL queries during conversion- PromQL metric names are preserved exactly as they appear in Grafana, even if
--guance-promql-compatible is passed
- Default output omits raw
extend.grafana metadata; pass --keep-grafana-meta only when debugging conversion fidelity
- Variable replacement from Grafana
$var / ${var} to Guance #{var}
- Settings extraction from both newer
fieldConfig / options panels and older Grafana graph / singlestat fields
- Settings mapping for thresholds, value mappings, legend, units, decimals, min, max, stack mode, null handling, panel links, and common chart display settings
- Transformation-aware table mapping for
organize, filterFieldsByName, and filterByValue
- Extra appearance metadata preserved under
extend.grafana and settings.extend.appearance, including line width, fill opacity, point mode, stat text/color mode, reduce calcs, and gauge display hints
Known Limits
- The converter is still Prometheus/PromQL-oriented for query extraction.
- Plugin-specific Grafana options are converted heuristically, not losslessly.
- Unsupported panel types are filtered out unless the mapping table is extended.
- Complex transformations and non-standard datasource payloads may still need manual cleanup.
- Standalone validation depends on installing the skill-local
package.json dependencies.
- The bundled tests cover conversion plus schema validation for the bundled fixture dashboard.
- The bundled tests also validate
test/guance-all-charts.json as a real export compatibility sample.
- LLM-based audit and repair suggestions are heuristic; confirm proposed fixes against a real dashboard sample and schema validation.
- LLM-based unit inference and PromQL compatibility advice should be treated as guided review, not silent truth, unless confidence is high.
When conversion fails or output is incomplete, read references/converter-notes.md.
Editing Rules
- Only change schemas when the generated Guance JSON is valid real data but the schema is too strict.
- Prefer changing the standalone converter before relaxing schemas.
- Prefer relaxing schemas only for shapes confirmed by a real Guance export sample or stable product output.
- Prefer validating the concrete output file first:
npm run validate:file -- ./output/guance-dashboard.json
- When schema work is involved, also validate:
npm run validate:file -- ./test/guance-all-charts.json
- For substantial converter changes, also run:
- When adding support for a new Grafana panel type, update the standalone script's panel type map first, then validate an example dashboard.
- When debugging a missing panel, compare the original Grafana panel JSON and the generated Guance chart JSON before changing code.
- When debugging a wrong query or setting, identify whether the gap is in extraction, classification, or setting-mapping logic before editing.
- When a panel is missing a unit, inspect query names, panel title, legend, and thresholds before deciding whether the converter should infer one.
- When a query looks valid in Grafana but suspicious in Guance, audit naming conventions and selector syntax before changing classification rules.
Standalone Use Rules
- Default to the standalone converter shipped in this skill.
- Keep all conversion logic needed by the skill inside
scripts/.
- Keep validation schemas needed by the skill inside
schemas/.
- Keep the local schemas aligned with both converter output and the real export sample
test/guance-all-charts.json.
- Keep smoke-test inputs and regression tests inside this skill directory.
- Do not make the skill depend on
lib/scripts/*, sync steps, root-level schemas, repository fixtures, or build steps for normal use.
- If behavior is duplicated elsewhere in the repository, treat that as optional follow-up work, not part of the default skill workflow.
Typical Requests This Skill Should Handle
- "Analyze this Grafana dashboard and tell me the conversion risks before you run anything."
- "Convert this Grafana dashboard JSON to Guance format."
- "Why did this Grafana panel disappear after conversion?"
- "Compare this Grafana dashboard and generated Guance dashboard, then list missing panels and likely causes."
- "Decide whether this dashboard should use
--guance-promql-compatible."
- "Infer missing units for these panels and tell me which guesses are high confidence."
- "Audit these PromQL queries for Grafana-to-Guance compatibility problems."
- "Patch the converter so this Grafana panel type maps correctly."
- "Add support for Grafana panel type
xyz."
- "Map Grafana variables into Guance vars correctly."
- "Validate the converted Guance dashboard against the local schema."
- "Compare a Grafana dashboard and generated Guance dashboard to find missing panels."
