Generate Resource Stubs

Generate Typed Resource Stubs

Generate ready-to-edit Go files for dashboards and alert rules using gcx dev generate. The generated code uses the grafana-foundation-sdk builder pattern and compiles without modification.

Quick Start

# Dashboard stub
gcx dev generate dashboards/my-service-overview.go

# Alert rule stub
gcx dev generate alerts/high-cpu-usage.go

# Batch generation
gcx dev generate dashboards/a.go dashboards/b.go alerts/c.go

How Type Inference Works

The resource type is inferred from the immediate parent directory:

Override with --type when the directory doesn't match:

gcx dev generate internal/monitoring/cpu-alert.go --type alertrule

Output

• Filename is normalized to snake_case: my-dashboard.go → my_dashboard.go
• Function name is CamelCase: my-dashboard → MyDashboard()
• Package name is derived from the parent directory

After Generation: Building Real Dashboards

The generated stub is a starting point. See references/foundation-sdk-guide.md for the full builder API reference to customize your dashboards and alerts.

Dashboard Customization Cheat Sheet

import (
    dashboard "github.com/grafana/grafana-foundation-sdk/go/dashboardv2beta1"
    "github.com/grafana/grafana-foundation-sdk/go/prometheus"
    "github.com/grafana/grafana-foundation-sdk/go/timeseries"
)

builder := dashboard.NewDashboardBuilder("My Dashboard").
    Tags([]string{"team:platform", "env:production"}).
    Editable(true).
    // Add a panel
    Panel("requests-panel",
        dashboard.NewPanelBuilder().
            Title("Request Rate").
            Visualization(timeseries.NewVisualizationBuilder()).
            Data(
                dashboard.NewQueryGroupBuilder().
                    Target(
                        dashboard.NewTargetBuilder().Query(
                            prometheus.NewDataqueryBuilder().
                                Expr(`rate(http_requests_total[$__rate_interval])`).
                                LegendFormat("{{method}} {{status}}"),
                        ),
                    ),
            ),
    ).
    // Layout
    AutoGridLayout(
        dashboard.AutoGrid().
            WithItem("requests-panel"),
    )

return dashboard.Manifest("my-dashboard", builder)

Alert Rule Customization Cheat Sheet

import (
    "github.com/grafana/grafana-foundation-sdk/go/alerting"
    "github.com/grafana/grafana-foundation-sdk/go/resource"
)

rule := alerting.NewRuleBuilder("High CPU Usage").
    Condition("A").
    For("5m").
    FolderUID("my-folder").
    RuleGroup("cpu-alerts").
    Labels(map[string]string{
        "severity": "critical",
        "team":     "platform",
    }).
    Annotations(map[string]string{
        "summary":     "CPU usage above 90% for 5 minutes",
        "description": "Instance {{ $labels.instance }} has high CPU usage.",
    })

Common Issues

Grafana Foundation SDK — Go Builder Reference (v0.0.12)

Reference for building dashboards and alerts using grafana-foundation-sdk/go.

Import Paths

import (
    dashboard "github.com/grafana/grafana-foundation-sdk/go/dashboardv2beta1"
    "github.com/grafana/grafana-foundation-sdk/go/resource"
    "github.com/grafana/grafana-foundation-sdk/go/alerting"
    // Visualization types
    "github.com/grafana/grafana-foundation-sdk/go/timeseries"
    "github.com/grafana/grafana-foundation-sdk/go/stat"
    "github.com/grafana/grafana-foundation-sdk/go/gauge"
    "github.com/grafana/grafana-foundation-sdk/go/barchart"
    "github.com/grafana/grafana-foundation-sdk/go/table"
    "github.com/grafana/grafana-foundation-sdk/go/heatmap"
    "github.com/grafana/grafana-foundation-sdk/go/piechart"
    "github.com/grafana/grafana-foundation-sdk/go/logs"
    "github.com/grafana/grafana-foundation-sdk/go/text"
    // Datasource query types
    "github.com/grafana/grafana-foundation-sdk/go/prometheus"
    "github.com/grafana/grafana-foundation-sdk/go/loki"
    "github.com/grafana/grafana-foundation-sdk/go/elasticsearch"
    "github.com/grafana/grafana-foundation-sdk/go/cloudwatch"
    "github.com/grafana/grafana-foundation-sdk/go/tempo"
    "github.com/grafana/grafana-foundation-sdk/go/testdata"
    // Utilities
    "github.com/grafana/grafana-foundation-sdk/go/common"
    "github.com/grafana/grafana-foundation-sdk/go/units"
)

DashboardBuilder (dashboardv2beta1)

dashboard.NewDashboardBuilder(title string) *DashboardBuilder

Key Methods

Adding Panels

.Panel("panel-key", panelBuilder)       // Named panel
.LibraryPanel("key", libraryBuilder)    // Library panel reference

Panel Builder

dashboard.NewPanelBuilder().
    Title("Panel Title").
    Description("Panel description").
    Visualization(timeseries.NewVisualizationBuilder()).  // or stat, gauge, etc.
    Data(queryGroupBuilder)

Query Group (data for a panel)

dashboard.NewQueryGroupBuilder().
    Target(
        dashboard.NewTargetBuilder().Query(
            prometheus.NewDataqueryBuilder().
                Expr(`rate(http_requests_total[$__rate_interval])`).
                LegendFormat("{{method}}"),
        ),
    ).
    Target(  // Multiple targets
        dashboard.NewTargetBuilder().Query(
            prometheus.NewDataqueryBuilder().
                Expr(`rate(http_errors_total[$__rate_interval])`),
        ),
    )

Layout Options

// AutoGrid — simplest, auto-arranges panels
.AutoGridLayout(
    dashboard.AutoGrid().
        WithItem("panel-1").
        WithItem("panel-2"),
)

// Grid — explicit row/col positioning
.GridLayout(
    dashboard.NewGridLayoutBuilder().
        Row(dashboard.NewGridLayoutRowBuilder().
            Panel(0, 0, 12, 8, dashboard.NewGridLayoutItemBuilder().Element("panel-1")).
            Panel(12, 0, 12, 8, dashboard.NewGridLayoutItemBuilder().Element("panel-2")),
        ),
)

// Rows — group panels into collapsible rows
.RowsLayout(
    dashboard.NewRowsLayoutBuilder().
        Row(dashboard.NewRowsLayoutRowBuilder().
            Title("Row Title").
            Panel(dashboard.NewRowsLayoutPanelBuilder().Element("panel-1")),
        ),
)

Variables

.QueryVariable(
    dashboard.NewQueryVariableKindBuilder().
        Name("datasource").
        Label("Data Source").
        DatasourceType("prometheus"),
)
.IntervalVariable(
    dashboard.NewIntervalVariableKindBuilder().
        Name("interval").
        Values([]string{"1m", "5m", "15m", "1h"}),
)

Wrapping for gcx

return dashboard.Manifest("resource-name", builder)

Visualization Types

Timeseries

timeseries.NewVisualizationBuilder()  // Line/area/bar chart over time

Stat

stat.NewVisualizationBuilder()  // Single big number

Gauge

gauge.NewVisualizationBuilder()  // Gauge with thresholds

Table

table.NewVisualizationBuilder()  // Data table

Bar Chart

barchart.NewVisualizationBuilder()  // Category bar chart

Heatmap

heatmap.NewVisualizationBuilder()  // Heatmap

Logs

logs.NewVisualizationBuilder()  // Log viewer

Text

text.NewVisualizationBuilder()  // Markdown/HTML text panel

Datasource Query Types

Prometheus

prometheus.NewDataqueryBuilder().
    Expr(`rate(http_requests_total{job="myapp"}[$__rate_interval])`).
    LegendFormat("{{method}} {{status}}").
    Instant(false)  // range query (default)

Loki

loki.NewDataqueryBuilder().
    Expr(`{app="myapp"} |= "error"`).
    LegendFormat("{{level}}")

Testdata (for examples/testing)

testdata.NewQueryBuilder().
    ScenarioId("random_walk").
    SeriesCount(3)

Alert Rule Builder (alerting)

alerting.NewRuleBuilder(title string) *RuleBuilder

Key Methods

Wrapping for gcx (no convenience Manifest function)

ruleObj, err := rule.Build()
if err != nil {
    // handle error
}

return resource.NewManifestBuilder().
    ApiVersion("notifications.alerting.grafana.app/v0alpha1").
    Kind("AlertRule").
    Metadata(resource.NewMetadataBuilder().Name("rule-name")).
    Spec(ruleObj)

Common Patterns

Multi-panel dashboard with Prometheus

func MyServiceDashboard() *resource.ManifestBuilder {
    requestRate := dashboard.NewPanelBuilder().
        Title("Request Rate").
        Visualization(timeseries.NewVisualizationBuilder()).
        Data(dashboard.NewQueryGroupBuilder().
            Target(dashboard.NewTargetBuilder().Query(
                prometheus.NewDataqueryBuilder().
                    Expr(`sum(rate(http_requests_total{service="my-svc"}[$__rate_interval])) by (method)`).
                    LegendFormat("{{method}}"),
            )),
        )

    errorRate := dashboard.NewPanelBuilder().
        Title("Error Rate").
        Visualization(stat.NewVisualizationBuilder()).
        Data(dashboard.NewQueryGroupBuilder().
            Target(dashboard.NewTargetBuilder().Query(
                prometheus.NewDataqueryBuilder().
                    Expr(`sum(rate(http_requests_total{service="my-svc",status=~"5.."}[$__rate_interval])) / sum(rate(http_requests_total{service="my-svc"}[$__rate_interval]))`).
                    LegendFormat("error ratio"),
            )),
        )

    builder := dashboard.NewDashboardBuilder("My Service Overview").
        Tags([]string{"team:platform"}).
        Panel("request-rate", requestRate).
        Panel("error-rate", errorRate).
        AutoGridLayout(
            dashboard.AutoGrid().
                WithItem("request-rate").
                WithItem("error-rate"),
        )

    return dashboard.Manifest("my-service-overview", builder)
}