publisher

README

Grafana Publisher

A Go module for programmatically publishing Grafana dashboards to multiple Grafana Cloud stacks.

Configuration

The publisher module requires a publisher-config.yaml file in the root directory. This file defines which dashboards to publish and to which stacks.

Configuration File Structure

# List of stack slugs to exclude from publishing
exclusions:
  - "stackname1"
  - "stackname2"

# Common dashboards that will be published to all non-excluded stacks
commonDashboards:
  localFolder: "path/to/common/dashboards"    # Local folder containing dashboard JSON files
  grafanaFolder: "Common-Folder-Name"         # Destination folder name in Grafana

# Custom dashboards that will be published only to the custom-stack
customDashboards:
  localFolder: "path/to/custom/dashboards"    # Local folder containing dashboard JSON files
  grafanaFolder: "Custom-Folder-Name"         # Destination folder name in Grafana

# Stack slug for custom dashboards
customStack: "stackname"

# Stack slug for testing
testStack: "teststackname"

Integration

Prerequisites

1. Set the GRAFANA_CLOUD_TOKEN environment variable with your Grafana Cloud API token:

   export GRAFANA_CLOUD_TOKEN=your-token-here
   

Using the Module

The publisher supports two modes:

1. Test mode - publishes to test stack only:

   publisher.Publish(false)
   

2. All stacks mode - publishes to all non-excluded stacks:

   publisher.Publish(true)
   

Implementation Example

package main

import (
    "github.com/adevinta/go-grafana-toolkit/publisher"
    "log"
)

func main() {
    p, err := publisher.NewPublisher()
    if err != nil {
        log.Fatal(err)
    }

    // Publish to test stack only
    if err := p.Publish(false); err != nil {
        log.Fatal(err)
    }
}

Dashboard Files

• Place dashboard JSON files in the configured local folders
• To delete a dashboard, create a copy of its JSON file with the .deleted extension

Supported datasources

Metrics datasources

sFor metrics, ensure your dashboard has a datasource variable named $PROMPRO. This variable must be used in all metrics queries instead of the hard-coded datasource.

Logs datasources

For logs, ensure your dashboard has a datasource variable named $LOGSPRO. This variable must be used in all log queries instead of the hard-coded datasource.

Log usage datasources

For usage metrics about your stack log ingestion, ensure your dashboard uses a datasource variable named $LOGUSAGE.

File Types

The publisher supports two types of files:

• .json - Dashboard definitions to be created/updated
• .deleted - Dashboard definitions to be removed

Error Handling

• The publisher will retry failed uploads for individual stacks
• Detailed logs are provided for any failures
• The process will stop if retries fail

Documentation

Overview

Package publisher provides functionality to publish Grafana dashboards to multiple Grafana Cloud stacks. It supports publishing common dashboards to all stacks and custom dashboards to specific stacks. The publisher can operate in test mode (single stack) or production mode (all non-excluded stacks).

Index

• func IsConfigured() bool
• type Publisher
  • func NewPublisher() (*Publisher, error)
  • func NewPublisherWithCloudClient(gcc grafana.GrafanaCloudClient) (*Publisher, error)
  • func (p Publisher) Publish(syncAllStacks bool) error
• type PublisherConfig
  • func (c *PublisherConfig) ExclusionsMap() map[string]struct{}

Functions

func IsConfigured

func IsConfigured() bool

IsConfigured checks if the publisher configuration file exists.

Types

type Publisher

type Publisher struct {
	// contains filtered or unexported fields
}

Publisher manages the publishing of Grafana dashboards to multiple stacks. It uses a configuration file to determine which dashboards to publish and to which stacks.

func NewPublisher

func NewPublisher() (*Publisher, error)

NewPublisher creates a new Publisher instance. It loads the configuration from the publisher-config.yaml file. Returns an error if the configuration file cannot be loaded or parsed.

func NewPublisherWithCloudClient

func NewPublisherWithCloudClient(gcc grafana.GrafanaCloudClient) (*Publisher, error)

func (Publisher) Publish

func (p Publisher) Publish(syncAllStacks bool) error

Publish synchronizes dashboards with Grafana Cloud stacks according to the configuration. If syncAllStacks is true, it publishes to all non-excluded stacks. If syncAllStacks is false, it publishes only to the test stack. Requires GRAFANA_CLOUD_TOKEN environment variable to be set. Returns an error if the synchronization fails.

type PublisherConfig

type PublisherConfig struct {
	Exclusions []string `yaml:"exclusions,omitempty"`

	CommonDashboard struct {
		LocalFolder   string `yaml:"localFolder"`
		GrafanaFolder string `yaml:"grafanaFolder"`
	} `yaml:"commonDashboards"`

	CustomDashboard struct {
		LocalFolder   string `yaml:"localFolder"`
		GrafanaFolder string `yaml:"grafanaFolder"`
	} `yaml:"customDashboards"`

	CustomStack string `yaml:"customStack"`
	TestStack   string `yaml:"testStack"`
	// contains filtered or unexported fields
}

func (*PublisherConfig) ExclusionsMap

func (c *PublisherConfig) ExclusionsMap() map[string]struct{}