name: Grafana Dashboard JSON to Jsonnet Transformer description: Transform Grafana dashboard JSON files into well-structured Jsonnet programs with extracted templates and variables. This skill should be used when converting Grafana dashboard configurations to Jsonnet for version control, templating, and reuse. license: MIT

Grafana Dashboard JSON to Jsonnet Transformer

Purpose

Transform Grafana dashboard JSON files into well-structured Jsonnet programs with:

• Extracted repeated values into local variables
• Reusable panel template functions
• Organized data source configurations
• Clean, maintainable structure

When to Use

Use this skill when:

• Converting Grafana dashboard JSON to Jsonnet for version control
• Creating reusable dashboard templates
• Extracting common configurations into shared libraries
• Migrating dashboards between Grafana instances
• Standardizing dashboard configurations across a team

How to Use

Basic Transformation

1. Prepare input: Ensure the JSON file is a valid Grafana dashboard export
2. Run transformation: Execute scripts/main.py with input file
3. Review output: Check the generated Jsonnet for accuracy
4. Customize: Modify templates or add custom logic as needed

Command Line Usage

# Transform a JSON file to Jsonnet
python scripts/main.py --input examples/input/sample_dashboard.json --output output.jsonnet

# Transform with options
python scripts/main.py --input dashboard.json --output dashboard.jsonnet \
    --no-comments --extract-repeated --create-templates

Python API Usage

from scripts import transform, TransformOptions

# Transform a file
result = transform('dashboard.json')
print(result.jsonnet_code)

# Transform with options
options = TransformOptions(
    extract_repeated=True,
    create_templates=True,
    add_comments=True
)
result = transform('dashboard.json', options)
print(result.jsonnet_code)

# Transform from string
json_string = '{"dashboard": {"title": "My Dashboard", "panels": []}}'
result = transform_string(json_string)

Reusable Resources

Scripts (scripts/)

The scripts directory contains all executable Python code for the transformation:

• scripts/main.py - Main transformation pipeline with transform() and transform_string() functions
• scripts/parser.py - JSON parsing and validation functions
• scripts/analyzer.py - Dashboard analysis and pattern detection
• scripts/generator.py - Jsonnet code generation
• scripts/patterns.py - Pattern detection for repeated values
• scripts/templates/panels.py - Panel template functions for all supported panel types
• scripts/templates/mixins.py - Reusable configuration mixins
• scripts/package_skill.py - Skill packaging script for distribution

References (references/)

The references directory contains documentation intended to be loaded as needed:

• references/README.md - Main documentation with installation and usage guide
• references/API.md - Complete API documentation
• references/grafana-schema.md - Grafana dashboard schema reference
• references/jsonnet-guide.md - Jsonnet syntax guide
• references/transformation-rules.md - Detailed transformation rules

Assets (assets/)

The assets directory contains files used in the output:

• assets/examples/input/ - Sample Grafana dashboard JSON files for testing
• assets/examples/output/ - Expected Jsonnet output for validation
• assets/templates/ - Built-in dashboard templates (kubernetes.jsonnet, prometheus.jsonnet, empty.jsonnet)

Transformation Examples

Input (JSON)

{
  "dashboard": {
    "title": "My Dashboard",
    "panels": [
      {
        "id": 1,
        "type": "graph",
        "title": "CPU Usage",
        "gridPos": {"x": 0, "y": 0, "w": 12, "h": 8},
        "targets": [{"expr": "cpu_usage", "refId": "A"}]
      }
    ]
  }
}

Output (Jsonnet)

// Generated by Grafana Dashboard JSON to Jsonnet Transformer
// Source: My Dashboard

{
    title: 'My Dashboard',
    panels: [
        {
            // CPU Usage
            id: 1,
            type: 'graph',
            title: 'CPU Usage',
            gridPos: { x: 0, y: 0, w: 12, h: 8 },
            targets: [
                { expr: 'cpu_usage', refId: 'A' },
            ],
        },
    ],
}

With Extracted Variables

// Common color definitions
local colors = {
    green: '#73bf69',
    red: '#f2495c',
    blue: '#5794f2',
};

// Threshold configurations
local defaultThresholds = {
    mode: 'absolute',
    steps: [
        { color: 'green', value: null },
        { color: 'green', value: 80 },
        { color: 'red', value: 90 },
    ],
};

// Panel template functions
local statPanel(title, gridPos, targets, datasource) = {
    type: 'stat',
    title: title,
    gridPos: gridPos,
    targets: targets,
    datasource: { type: datasource, uid: '${datasource}' },
    colorMode: 'value',
    graphMode: 'area',
    justifyMode: 'auto',
    textMode: 'auto',
    transparent: false,
};

{
    title: 'My Dashboard',
    panels: [
        statPanel(
            'Cluster CPU Usage',
            { x: 0, y: 1, w: 8, h: 8 },
            [{ expr: '...', refId: 'A' }],
            'prometheus'
        ),
    ],
}

Supported Panel Types

The transformer supports all standard Grafana panel types:

• graph - Line/area chart
• timeseries - Modern time series chart
• stat - Single value display
• gauge - Gauge visualization
• table - Tabular data
• piechart - Pie/donut chart
• barchart - Bar chart
• heatmap - Heatmap visualization
• logs - Log viewer
• text - Text panel
• row - Container panel

Configuration Options

TransformOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | validate | bool | True | Validate JSON structure | | min_pattern_occurrences | int | 2 | Minimum occurrences for pattern detection | | extract_repeated | bool | True | Extract repeated values | | create_templates | bool | True | Create panel templates | | add_comments | bool | True | Add comments to output | | include_imports | bool | False | Include import statements | | indent_size | int | 4 | Spaces per indent level | | max_line_length | int | 120 | Maximum line length | | output_file | str | None | Output file path | | overwrite | bool | False | Overwrite output file |

Limitations

• Does not support Grafana plugin-specific panel types (community plugins)
• May require manual adjustment for very complex dashboards with custom configurations
• Does not handle dashboard provisioning files (YAML/JSON in provisioning directories)
• Does not validate PromQL/LogQL queries for correctness
• Does not handle alert notification channels

Running Tests

# Run all tests
python -m pytest scripts/tests/

# Run with coverage
python -m pytest scripts/tests/ --cov=scripts

# Run specific test file
python -m pytest scripts/tests/test_parser.py

Packaging the Skill

To create a distributable package:

# Validate the skill structure
python scripts/package_skill.py --validate-only

# Package the skill
python scripts/package_skill.py

# Package with custom name
python scripts/package_skill.py --name my-skill

The packaging script will:

1. Validate the skill structure (SKILL.md, directories, etc.)
2. Create a timestamped zip file in the dist/ directory
3. Include all required files and maintain proper directory structure