Grafana Developer Portal

https://grafana.com/developers/
Admin
The Grafana Developer Portal provides tools, APIs, and resources for developers to build plugins,...
Tokens:160,458
Snippets:848
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Grafana Plugin Development Next Steps and Commands

Source: https://grafana.com/developers/plugin-tools

This snippet outlines the essential commands to run after scaffolding a Grafana plugin, providing a quick start guide for installing dependencies, building frontend and backend code, and launching a Grafana development server using Docker. It also includes a recommendation for Git initialization.

```Shell
## What's next?

Run the following commands to get started:

    * cd ./orgName-pluginName-app
    * npm install to install frontend dependencies.
    * npm exec playwright install chromium to install e2e test dependencies.
    * npm run dev to build (and watch) the plugin frontend code.
    * mage -v build:backend to build the plugin backend code. Rerun this command every time you edit your backend files.
    * docker compose up to start a grafana development server.
    * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin.

Note: We strongly recommend creating a new Git repository by running git init in ./org-pluginname-app before continuing.

    * Learn more about Grafana Plugin Development at https://grafana.com/developers/plugin-tools
```

--------------------------------

### Install Grafana Scenes ML Package

Source: https://grafana.com/developers/scenes/scenes-ml/getting-started

This command adds the `@grafana/scenes-ml` npm package to your project, making its machine learning powered functionalities available for use within your Grafana Scenes application.

```bash
yarn add @grafana/scenes-ml
```

--------------------------------

### Start Grafana Development Server

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/get-started

Instructions to start the Grafana development server locally, which is a prerequisite for running end-to-end tests. Examples are provided for npm, Yarn, and pnpm.

```shell
npm run server
```

```shell
yarn server
```

```shell
pnpm run server
```

--------------------------------

### Initial Plugin Development Setup Commands

Source: https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment

Provides the sequence of commands to set up and run a Grafana plugin development environment. This includes installing frontend dependencies, building and watching frontend code, building backend code, and starting the Grafana development server.

```Shell
npm install
npm run dev
mage -v build:linux
npm run server
```

--------------------------------

### Build and Run Grafana App Plugin

Source: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-backend-component

These commands illustrate the process of building the frontend and backend components of a Grafana app plugin, and then starting Grafana using Docker Compose to test the plugin. A log output example is provided to verify plugin registration.

```bash
npm run dev
```

```bash
mage -v build:linux
```

```bash
docker compose up
```

```bash
INFO[01-01|12:00:00] Plugin registered       logger=plugin.loader pluginID=<your-plugin>
```

--------------------------------

### Scaffold Grafana Plugin Project

Source: https://grafana.com/developers/plugin-tools

This snippet demonstrates how to initialize a new Grafana plugin project using the `@grafana/create-plugin` tool. It provides the command-line instructions for npm, Yarn, and pnpm, guiding users to answer prompts to set up their initial project structure.

```Shell
npx @grafana/create-plugin@latest
```

```Shell
yarn dlx @grafana/create-plugin@latest
```

```Shell
pnpm dlx @grafana/create-plugin@latest
```

--------------------------------

### Install Grafana Plugin Dependencies

Source: https://grafana.com/developers/plugin-tools

This snippet provides the commands to navigate into the newly scaffolded Grafana plugin directory and install its dependencies using different package managers. It covers npm, Yarn, and pnpm, ensuring all necessary frontend packages are set up for development.

```Shell
cd <orgName>-<pluginName>-<pluginType>
npm install
```

```Shell
cd <orgName>-<pluginName>-<pluginType>
yarn install
```

```Shell
cd <orgName>-<pluginName>-<pluginType>
pnpm install
```

--------------------------------

### Start Specific Grafana Version for Development

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/get-started

Demonstrates how to start a specific version of the Grafana development server by setting the `GRAFANA_VERSION` environment variable before running the `npm run server` command.

```shell
GRAFANA_VERSION=10.4.1 npm run server
```

--------------------------------

### Start Grafana with Docker Compose

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Launches Grafana and its associated services (as defined in `docker-compose.yml`) using Docker Compose. This command typically starts a local Grafana instance where the developed plugin can be tested and verified.

```bash
docker compose up
```

--------------------------------

### Install Plugin Frontend Dependencies

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Installs all required Node.js dependencies for the Grafana plugin frontend, as defined in the `package.json` file. This ensures all necessary packages are available for development and building the frontend assets.

```bash
npm install
```

--------------------------------

### Start Grafana from Source in Development Mode

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Commands to start Grafana from its source repository in development mode. The `make run` command starts the Grafana backend, and `make run-frontend` starts the frontend development server, typically used for active development.

```bash
make run & make run-frontend
```

--------------------------------

### Initialize Grafana App Plugin Project

Source: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-backend-component

This snippet demonstrates the initial steps to create a new Grafana app plugin using the `@grafana/create-plugin` CLI tool, followed by navigating into the project directory and installing dependencies. It sets up the basic structure and prepares the environment for development.

```bash
npx @grafana/create-plugin@latest
```

```bash
cd <your-plugin>
```

```bash
npm install
```

--------------------------------

### Verify Node.js and npm Installation Paths

Source: https://grafana.com/developers/plugin-tools/troubleshooting

These commands help verify the installed Node.js version and the binary paths for Node.js and npx. This is crucial for ensuring you are using the correct Node.js installation, especially in environments with multiple installations or when encountering issues with `create-plugin`.

```Shell
node --version
```

```Shell
which node
```

```Shell
which npx
```

--------------------------------

### Update Grafana Plugin Configuration

Source: https://grafana.com/developers/scenes/scenes-ml/getting-started

This command updates an existing Grafana Scenes app plugin's configuration to ensure it's compatible with the latest versions, preparing it for the addition of new features like `@grafana/scenes-ml`.

```bash
npx @grafana/create-plugin@latest --update
```

--------------------------------

### Grafana Plugin Scaffolded Folder Structure

Source: https://grafana.com/developers/plugin-tools

This snippet illustrates the typical directory structure generated when scaffolding a new Grafana plugin. It provides an overview of the key files and folders, including configuration, source code, build scripts, and Docker setup, which form the foundation for plugin development.

```Shell
<orgName>-<pluginName>-<pluginType>
├── .config/
├── .eslintrc
├── .github
│   └── workflows
├── .gitignore
├── .nvmrc
├── .prettierrc.js
├── CHANGELOG.md
├── LICENSE
├── Magefile.go
├── README.md
├── cypress
│   └── integration
├── docker-compose.yaml
├── go.mod
├── go.sum
├── jest-setup.js
├── jest.config.js
├── node_modules
├── package.json
├── pkg
│   ├── main.go
│   └── plugin
├── src
│   ├── README.md
│   ├── components
│   ├── datasource.ts
│   ├── img
│   ├── module.ts
│   ├── plugin.json
│   └── types.ts
└── tsconfig.json
```

--------------------------------

### Execute Playwright E2E Tests

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/get-started

Commands to run Playwright end-to-end tests for a Grafana plugin from the local development directory. Examples are provided for npm, Yarn, and pnpm.

```shell
npx playwright test
```

```shell
yarn dlx playwright test
```

```shell
pnpm dlx playwright test
```

--------------------------------

### Run Grafana Development Server with Docker Compose

Source: https://grafana.com/developers/plugin-tools

This command launches the Grafana development server using Docker Compose. The `--build` flag ensures that necessary Docker images are built or rebuilt before starting the services, providing a fresh environment for testing the plugin.

```Docker
docker compose up --build
```

--------------------------------

### Verify Plugin Registration in Grafana Logs

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

An example log entry indicating that Grafana has successfully discovered and registered a plugin. This snippet helps verify that the plugin is recognized by the Grafana instance after startup.

```plaintext
INFO[01-01|12:00:00] Plugin registered       logger=plugin.loader pluginID=<your-plugin>
```

--------------------------------

### Scaffold a new Grafana plugin project

Source: https://grafana.com/developers/plugin-tools

This command initiates the scaffolding process for a new Grafana plugin. It prompts the user to answer questions about the plugin type and configuration, setting up a new project with the necessary files and dependencies. This command can be executed using various package managers.

```bash
npx @grafana/create-plugin@latest
```

```bash
yarn dlx @grafana/create-plugin@latest
```

```bash
pnpm dlx @grafana/create-plugin@latest
```

--------------------------------

### Implement Interactive Query Examples in Grafana Editor Help

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-query-editor-help

This comprehensive snippet illustrates how to enhance the `QueryEditorHelp` component with a list of predefined query examples. Each example includes a title, expression, and label, and clicking an example automatically populates the query editor using `props.onClickExample`.

```tsx
import React from 'react';
import { QueryEditorHelpProps, DataQuery } from '@grafana/data';

const examples = [
  {
    title: 'Addition',
    expression: '1 + 2',
    label: 'Add two integers',
  },
  {
    title: 'Subtraction',
    expression: '2 - 1',
    label: 'Subtract an integer from another',
  },
];

export default (props: QueryEditorHelpProps) => {
  return (
    <div>
      <h2>Cheat Sheet</h2>
      {examples.map((item, index) => (
        <div className="cheat-sheet-item" key={index}>
          <div className="cheat-sheet-item__title">{item.title}</div>
          {item.expression ? (
            <div
              className="cheat-sheet-item__example"
              onClick={(e) => props.onClickExample({ refId: 'A', queryText: item.expression } as DataQuery)}
            >
              <code>{item.expression}</code>
            </div>
          ) : null}
          <div className="cheat-sheet-item__label">{item.label}</div>
        </div>
      ))}
    </div>
  );
};
```

--------------------------------

### Install Grafana Scenes with create-plugin CLI

Source: https://grafana.com/developers/scenes

Use the `@grafana/create-plugin` command-line interface to initialize a new project. This tool helps set up a complete development environment for Grafana plugins, including the necessary dependencies for Grafana Scenes.

```bash
npx @grafana/create-plugin@latest
```

--------------------------------

### Mage Build Targets API Documentation

Source: https://grafana.com/developers/plugin-tools

Documentation for Mage build targets, specifically for building binaries for different architectures. This allows developers to compile the backend plugin for various operating systems.

```APIDOC
Mage Build Targets:

build:[arch]
  - Description: Builds a binary for a specific architecture.
  - Parameters:
    - [arch]: The target architecture (e.g., `linux`, `windows`, `darwin`).
  - Example Usage:
    - `mage -v build:Linux` (Builds for Linux architecture with verbose output)
```

--------------------------------

### Build Plugin Frontend in Development Mode

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Starts the development build process for the Grafana plugin's frontend. This command typically watches for file changes and automatically rebuilds frontend assets, facilitating rapid iteration during development.

```bash
npm run dev
```

--------------------------------

### Build Grafana Plugin Frontend for Production

Source: https://grafana.com/developers/plugin-tools

This snippet demonstrates how to build the frontend of a Grafana plugin for production, optimizing it for deployment. It uses common JavaScript package managers to execute the production build script.

```npm
npm run build
```

```yarn
yarn build
```

```pnpm
pnpm run build
```

--------------------------------

### Build Grafana Plugin Backend with Mage

Source: https://grafana.com/developers/plugin-tools

This snippet shows how to build the backend component of a Grafana plugin using Mage, a Go build tool. The command specifies building for a particular architecture, such as Linux, with verbose output.

```Mage
mage -v build:linux
```

--------------------------------

### List Available Mage Build Targets

Source: https://grafana.com/developers/plugin-tools

This command lists all available build targets and commands provided by Mage, which is useful for discovering additional build options or functionalities for the backend component of the plugin.

```Mage
mage -l
```

--------------------------------

### Navigate to Plugin Directory

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Changes the current directory to the newly created Grafana plugin's root directory. This step is essential before performing any further operations like installing dependencies or building the plugin.

```bash
cd <your-plugin>
```

--------------------------------

### Start Grafana with Docker Compose

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-plugin

Launches Grafana and its associated services using Docker Compose, providing a development environment to test the plugin.

```Shell
docker compose up
```

--------------------------------

### Install Plugin Dependencies

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-plugin

Installs all required Node.js packages and dependencies for the Grafana plugin project, as defined in `package.json`.

```Shell
npm install
```

--------------------------------

### Install Plugin Dependencies

Source: https://grafana.com/developers/plugin-tools/tutorials/build-an-app-plugin

This command installs all required Node.js packages and dependencies specified in the plugin's `package.json` file. This is a crucial step before building or running the plugin.

```Shell
npm install
```

--------------------------------

### Start Grafana Instance with Docker Compose

Source: https://grafana.com/developers/plugin-tools/tutorials/build-an-app-plugin

Initiates the Grafana instance along with its dependencies using Docker Compose, making it accessible for development and testing at the specified local address.

```Shell
docker compose up
```

--------------------------------

### Create OpenTelemetry Spans in Go Plugin

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-logs-metrics-traces-for-backend-plugins

This Go example demonstrates how to use the `trace.Tracer` to start new spans within a plugin's function, such as a query handler. It shows how to add various attributes to the span, providing detailed context about the operation, and ensures the span is properly ended using `defer span.End()`.

```Go
func (d *Datasource) query(ctx context.Context, pCtx backend.PluginContext, query backend.DataQuery) (backend.DataResponse, error) {
    ctx, span := tracing.DefaultTracer().Start(
        ctx,
        "query processing",
        trace.WithAttributes(
            attribute.String("query.ref_id", query.RefID),
            attribute.String("query.type", query.QueryType),
            attribute.Int64("query.max_data_points", query.MaxDataPoints),
            attribute.Int64("query.interval_ms", query.Interval.Milliseconds()),
            attribute.Int64("query.time_range.from", query.TimeRange.From.Unix()),
            attribute.Int64("query.time_range.to", query.TimeRange.To.Unix()),
        ),
    )
    defer span.End()

    // ...
}
```

--------------------------------

### Install Node.js Dependencies for Grafana Plugin

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-panel-plugin

Installs all required Node.js packages and dependencies for the Grafana plugin project. This command should be run after scaffolding the plugin and navigating into its directory to ensure all necessary libraries are available.

```shell
npm install
```

--------------------------------

### Start Grafana with Docker Compose

Source: https://grafana.com/developers/plugin-tools/tutorials/build-an-app-plugin

This command launches a Grafana instance using Docker Compose, providing a local environment to test and run your newly developed plugin within Grafana.

```Shell
docker compose up
```

--------------------------------

### Render Grafana Scene in a React Component

Source: https://grafana.com/developers/scenes/scenes-ml/getting-started

This React component demonstrates how to render a previously defined Grafana Scene within a plugin page. It imports the `getScene` function, instantiates the scene, and then renders it using the scene's `Component` property, making the interactive scene visible in the Grafana UI.

```typescript
import React from 'react';
import { getScene } from './helloMLScene';

export const HelloMLPluginPage = () => {
  const scene = getScene();

  return <scene.Component model={scene} />;
};
```

--------------------------------

### Start Grafana Development Environment with Docker Compose

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-panel-plugin

Starts the Grafana development environment using Docker Compose, which typically includes a Grafana instance and any other services required for plugin development. This allows you to test your plugin within a running Grafana instance.

```shell
docker compose up
```

--------------------------------

### Implement Basic Switch Component

Source: https://grafana.com/developers/saga/components/switch

This example demonstrates the basic usage of the `Switch` component with a label and disabled state. It shows how to render a standard switch that can be toggled by the user.

```JavaScript
<Switch invalid={false} label="Toggle feature" disabled={false} />
```

--------------------------------

### Configure Grafana Version for Development Server

Source: https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment

Demonstrates how to specify a particular Grafana version for the development server by setting the GRAFANA_VERSION environment variable. Examples are provided for npm, Yarn, and pnpm package managers.

```npm
GRAFANA_VERSION=10.0.0 npm run server
```

```Yarn
GRAFANA_VERSION=10.0.0 yarn server
```

```pnpm
GRAFANA_VERSION=10.0.0 pnpm run server
```

--------------------------------

### Add Grafana Scenes to existing project using Yarn

Source: https://grafana.com/developers/scenes

Integrate the `@grafana/scenes` package into an existing Grafana app plugin project. This command adds the Scenes library as a dependency, allowing you to start building interactive dashboards and visualizations.

```bash
yarn add @grafana/scenes
```

--------------------------------

### Build Grafana Plugin in Development Mode

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-plugin

Starts the development build process for the Grafana plugin, often including watch mode for live reloading during development.

```Shell
npm run dev
```

--------------------------------

### Backend Plugin Anatomy and Build Tools

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Describes the key files and folders involved in building a Grafana backend plugin, emphasizing the role of `Magefile.go` for build targets, `go.mod` for Go dependencies, `plugin.json` for plugin metadata, and `main.go` as the plugin's entry point.

```APIDOC
Magefile.go
  - Description: Not a strict requirement, but strongly recommended for using build targets provided by the plugin SDK.
/go.mod
  - Description: Go modules dependencies file.
/src/plugin.json
  - Description: A JSON file describing the plugin's metadata and configuration.
/pkg/main.go
  - Description: The starting point of the plugin binary, containing the main function.
```

--------------------------------

### Create New Grafana Plugin Project

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Initializes a new Grafana plugin project from a template using the `@grafana/create-plugin` CLI tool. This command scaffolds the basic structure and configuration, prompting for plugin type and backend inclusion.

```bash
npx @grafana/create-plugin@latest
```

--------------------------------

### Build Plugin Backend for Linux

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-backend-plugin

Compiles the Grafana plugin's backend for the Linux operating system using the `mage` build tool. This command creates the executable binary for the backend part of the plugin, ready for deployment or testing.

```bash
mage -v build:linux
```

--------------------------------

### Start Grafana Instance via Docker Compose

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/ci

Pulls the specified Grafana Docker image and starts a Grafana instance using Docker Compose in detached mode. It dynamically sets the Grafana version and image name based on provided matrix variables, facilitating flexible environment setup.

```shell
docker compose pull
GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d
```

--------------------------------

### Compare Heap Profiles using Go Pprof Tool

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/profile-backend-plugin

This command utilizes the `go tool pprof` to compare two previously collected heap profiles. It launches a web interface on `localhost:8081` for interactive visualization and analysis, with `heap1.pprof` serving as the baseline for comparison against `heap2.pprof`.

```Go
go tool pprof -http=localhost:8081 --base heap1.pprof heap2.pprof
```

--------------------------------

### Add VizPanel Objects to Grafana SceneFlexItems

Source: https://grafana.com/developers/scenes/scene-layout

This example extends the previous scene setup by populating `SceneFlexItem`s with actual `VizPanel` objects, specifically a `Timeseries` and a `Table` panel, using `PanelBuilders`.

```javascript
const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      expr: 'rate(prometheus_http_requests_total{}[5m])',
    },
  ],
});

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneFlexLayout({
    direction: 'column',
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().setTitle('Time series').build(),
      }),
      new SceneFlexItem({
        body: PanelBuilders.table().setTitle('Table').build(),
      }),
    ],
  }),
});
```

--------------------------------

### VSCode Launch Configuration for Go Backend Plugin Debugging

Source: https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment

This JSON configuration provides a `launch.json` setup for VSCode, enabling attachment to a Go backend plugin running inside a Docker container. It connects to a headless Delve instance exposed on port 2345, facilitating remote debugging of your Go code.

```JSON
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to plugin backend in docker",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "port": 2345,
      "host": "127.0.0.1",
      "showLog": true,
      "trace": "log",
      "logOutput": "rpc",
      "substitutePath": [
        {
          "from": "${workspaceFolder}",
          "to": "/root/<your-plugin-id>"
        }
      ]
    }
  ]
}
```

--------------------------------

### Analyze CPU Profile using Go Pprof Tool

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/profile-backend-plugin

This command uses the `go tool pprof` to analyze a previously collected CPU profile (`profile.pprof`). It launches a web interface on `localhost:8081`, providing an interactive environment to visualize and understand the CPU usage data, helping to identify performance bottlenecks.

```Go
go tool pprof -http=localhost:8081 profile.pprof
```

--------------------------------

### Test Grafana App Start Page with Custom Fixture in TypeScript

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/test-an-app-plugin/app-pages

This TypeScript example demonstrates how to write an end-to-end test for a Grafana app plugin's start page using the previously defined custom `gotoPage` fixture. It navigates to a specific app route (`/start`) and then asserts the visibility of a 'Welcome to my app' heading, showcasing a common testing pattern for UI elements.

```TypeScript
import { test, expect } from './fixtures.ts';

test('start page should welcome users to the app', async ({ gotoPage, page }) => {
  await gotoPage('/start');
  await expect(page.getByRole('heading', { name: 'Welcome to my app' })).toBeVisible();
});
```

--------------------------------

### Build Grafana Plugin Frontend in Development Mode

Source: https://grafana.com/developers/plugin-tools

This snippet shows how to build the frontend of a Grafana plugin in watch mode for development, continuously monitoring for changes. It uses common JavaScript package managers to execute the development script.

```npm
npm run dev
```

```yarn
yarn dev
```

```pnpm
pnpm run dev
```

--------------------------------

### Validating query responses in Grafana panel plugins

Source: https://grafana.com/developers/plugin-tools/how-to-guides/panel-plugins/error-handling-for-panel-plugins

Provides examples of validating common issues in Grafana query responses, such as missing expected data fields or an empty result set. Specific errors are thrown to guide the user on necessary query adjustments.

```javascript
if (!numberField) {
  throw new Error('Query result is missing a number field');
}

if (frame.length === 0) {
  throw new Error('Query returned an empty result');
}
```

--------------------------------

### Update Grafana Go Plugin Bootstrap Logic

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-7_x-to-8_x

This snippet demonstrates the migration of a Grafana backend plugin's main package bootstrapping logic from an older SDK version to the new `grafana-plugin-sdk-go`. It shows how to replace the `plugin.Serve` call with `datasource.Manage` for simplified plugin management, reducing boilerplate and aligning with the updated SDK.

```Go
// before
package main

import (
  "github.com/grafana/grafana_plugin_model/go/datasource"
  hclog "github.com/hashicorp/go-hclog"
  plugin "github.com/hashicorp/go-plugin"

  "github.com/myorgid/datasource/pkg/plugin"
)

func main() {
  pluginLogger.Debug("Running GRPC server")

  ds, err := NewSampleDatasource(pluginLogger);
  if err != nil {
    pluginLogger.Error("Unable to create plugin");
  }

  plugin.Serve(&plugin.ServeConfig{
    HandshakeConfig: plugin.HandshakeConfig{
			ProtocolVersion:  1,
			MagicCookieKey:   "grafana_plugin_type",
			MagicCookieValue: "datasource",
		},
    Plugins: map[string]plugin.Plugin{
			"myorgid-datasource": &datasource.DatasourcePluginImpl{Plugin: ds},
    },
    GRPCServer: plugin.DefaultGRPCServer,
  })
}
```

```Go
// after
package main

import (
  "os"

  "github.com/grafana/grafana-plugin-sdk-go/backend/log"
  "github.com/grafana/grafana-plugin-sdk-go/backend/datasource"

  "github.com/myorgid/datasource/pkg/plugin"
)

func main() {
  log.DefaultLogger.Debug("Running GRPC server")

  if err := datasource.Manage("myorgid-datasource", NewSampleDatasource, datasource.ManageOpts{}); err != nil {
				log.DefaultLogger.Error(err.Error())
				os.Exit(1)
		}
}
```

--------------------------------

### Create Grafana Plugin with create-plugin CLI

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-plugin

Initializes a new Grafana plugin project using the `@grafana/create-plugin` command-line tool. When prompted, select 'datasource' to scaffold a data source plugin.

```Shell
npx @grafana/create-plugin@latest
```

--------------------------------

### Migrate Functional Component Styling to Grafana Theme v2 (useStyles2)

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-7_x-to-8_x

This example illustrates how to update functional components to use the new Grafana theming system (v2). It shows the transition from `useStyles` with `GrafanaTheme` and `emotion` for styling to `useStyles2` with `GrafanaTheme2` and `@emotion/css` for improved theme access and memoization.

```JavaScript
// before
import React, { ReactElement } from 'react';
import css from 'emotion';
import { GrafanaTheme } from '@grafana/data';
import { useStyles } from '@grafana/ui';

function Component(): ReactElement | null {
  const styles = useStyles(getStyles);
}

const getStyles = (theme: GrafanaTheme) => ({
  myStyle: css`
    background: ${theme.colors.bodyBg};
    display: flex;
  `,
});

// after
import React, { ReactElement } from 'react';
import { css } from '@emotion/css';
import { GrafanaTheme2 } from '@grafana/data';
import { useStyles2 } from '@grafana/ui';

function Component(): ReactElement | null {
  const theme = useStyles2(getStyles);
}

const getStyles = (theme: GrafanaTheme2) => ({
  myStyle: css`
    background: ${theme.colors.background.canvas};
    display: flex;
  `,
});
```

--------------------------------

### Implement basic logging in Grafana Go backend plugin

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-logs-metrics-traces-for-backend-plugins

This example demonstrates how to use the global `backend.Logger` from the Grafana plugin SDK for Go to log messages with different severity levels (Debug, Info, Warning, Error) and include key-value pairs for contextual information. This logger is suitable for most common logging scenarios within a plugin.

```Go
package plugin

import (
    "errors"

    "github.com/grafana/grafana-plugin-sdk-go/backend"
)

func main() {
    backend.Logger.Debug("Debug msg", "someID", 1)
    backend.Logger.Info("Info msg", "queryType", "default")
    backend.Logger.Warning("Warning msg", "someKey", "someValue")
    backend.Logger.Error("Error msg", "error", errors.New("An error occurred"))
}
```

--------------------------------

### Run Grafana Frontend Plugin E2E Tests with GitHub Actions

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/ci

This GitHub Actions workflow defines a comprehensive pipeline for running end-to-end tests on Grafana frontend plugins. It resolves Grafana image versions, sets up Node.js, installs dependencies using various package managers (npm, yarn, pnpm), builds the frontend, installs Playwright browsers, starts a Grafana instance via Docker Compose, waits for the server, and finally executes Playwright tests. The workflow is triggered on pull requests and a daily schedule.

```YAML
name: E2E tests
on:
  pull_request:
  schedule:
    - cron: '0 11 * * *' #Run e2e tests once a day at 11 UTC

permissions:
  contents: read
  id-token: write

jobs:
  resolve-versions:
    name: Resolve Grafana images
    runs-on: ubuntu-latest
    timeout-minutes: 3
    outputs:
      matrix: ${{ steps.resolve-versions.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Resolve Grafana E2E versions
        id: resolve-versions
        uses: grafana/plugin-actions/e2e-version@main

  playwright-tests:
    needs: resolve-versions
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        GRAFANA_IMAGE: ${{fromJson(needs.resolve-versions.outputs.matrix)}}
    name: e2e ${{ matrix.GRAFANA_IMAGE.name }}@${{ matrix.GRAFANA_IMAGE.VERSION }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install npm dependencies
        run: npm ci

      - name: Build frontend
        run: npm run build

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Start Grafana
        run: |
          docker compose pull
          GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d

      - name: Wait for grafana server
        uses: grafana/plugin-actions/wait-for-grafana@main

      - name: Run Playwright tests
        id: run-tests
        run: npx playwright test
```

```YAML
name: E2E tests
on:
  pull_request:
  schedule:
    - cron: '0 11 * * *' #Run e2e tests once a day at 11 UTC

permissions:
  contents: read
  id-token: write

jobs:
  resolve-versions:
    name: Resolve Grafana images
    runs-on: ubuntu-latest
    timeout-minutes: 3
    outputs:
      matrix: ${{ steps.resolve-versions.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Resolve Grafana E2E versions
        id: resolve-versions
        uses: grafana/plugin-actions/e2e-version@main

  playwright-tests:
    needs: resolve-versions
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        GRAFANA_IMAGE: ${{fromJson(needs.resolve-versions.outputs.matrix)}}
    name: e2e ${{ matrix.GRAFANA_IMAGE.name }}@${{ matrix.GRAFANA_IMAGE.VERSION }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install yarn dependencies
        run: yarn install

      - name: Build frontend
        run: yarn build

      - name: Install Playwright Browsers
        run: yarn playwright install --with-deps

      - name: Start Grafana
        run: |
          docker compose pull
          GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d

      - name: Wait for grafana server
        uses: grafana/plugin-actions/wait-for-grafana@main

      - name: Run Playwright tests
        id: run-tests
        run: yarn playwright test
```

```YAML
name: E2E tests
on:
  pull_request:
  schedule:
    - cron: '0 11 * * *' #Run e2e tests once a day at 11 UTC

permissions:
  contents: read
  id-token: write

jobs:
  resolve-versions:
    name: Resolve Grafana images
    runs-on: ubuntu-latest
    timeout-minutes: 3
    outputs:
      matrix: ${{ steps.resolve-versions.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Resolve Grafana E2E versions
        id: resolve-versions
        uses: grafana/plugin-actions/e2e-version@main

  playwright-tests:
    needs: resolve-versions
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        GRAFANA_IMAGE: ${{fromJson(needs.resolve-versions.outputs.matrix)}}
    name: e2e ${{ matrix.GRAFANA_IMAGE.name }}@${{ matrix.GRAFANA_IMAGE.VERSION }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3

      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install pnpm dependencies
        run: pnpm install --frozen-lockfile

      - name: Build frontend
        run: pnpm run build

      - name: Install Playwright Browsers
        run: pnpm playwright install --with-deps

      - name: Start Grafana
        run: |
          docker compose pull
          GRAFANA_VERSION=${{ matrix.GRAFANA_IMAGE.VERSION }} GRAFANA_IMAGE=${{ matrix.GRAFANA_IMAGE.NAME }} docker compose up -d

      - name: Wait for grafana server
        uses: grafana/plugin-actions/wait-for-grafana@main
```

--------------------------------

### Grafana Plugin Configuration: grafanaDependency Property

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/get-started

Defines the `grafanaDependency` property within the `plugin.json` file, which specifies the compatible Grafana versions for a plugin. This property is crucial for ensuring the plugin functions correctly across different Grafana environments and is used by CI systems to run tests against all supported versions.

```APIDOC
plugin.json property: grafanaDependency
  Description: Specifies the versions of Grafana that the plugin is compatible with.
  Type: String or Array of Strings (version ranges)
  Usage Context: Used within the plugin's manifest file (`plugin.json`) to declare compatibility.
  Example (Conceptual):
    {
      "dependencies": {
        "grafanaDependency": ">=8.0.0 <10.0.0"
      }
    }
  Best Practice: Run Playwright end-to-end tests targeting all supported Grafana versions as defined by this property.
```

--------------------------------

### Create Basic Grafana Query Editor Help Component

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-query-editor-help

This snippet demonstrates the initial setup of a `QueryEditorHelp.tsx` file. It defines a basic React functional component that accepts `QueryEditorHelpProps` and renders a simple heading, serving as a placeholder for the interactive help content.

```tsx
import React from 'react';
import { QueryEditorHelpProps } from '@grafana/data';

export default (props: QueryEditorHelpProps) => {
  return <h2>My cheat sheet</h2>;
};
```

--------------------------------

### Migrate React Router v5 Switch to v6 Routes Component

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-9_x-to-10_x

In React Router v6, the `<Switch>` component is replaced by `<Routes>`. Update your routing configuration to import and use `<Routes>` for defining application routes, as demonstrated in the example. This change simplifies route matching logic.

```typescript
// Using <Routes> instead of <Switch> in `react-router` v6
import { Routes } from 'react-router-dom';

// ...

return (
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
);
```

--------------------------------

### Grafana HTTP API for Datasource Resources

Source: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-resource-handler

This section describes the Grafana HTTP API endpoint structure for accessing custom datasource resources. It specifies the base URL, required parameters like `DATASOURCE_UID`, and provides concrete examples for accessing 'namespaces' and 'projects' resources via HTTP GET requests.

```APIDOC
Endpoint: GET http://<GRAFANA_HOSTNAME>:<PORT>/api/datasources/uid/<DATASOURCE_UID>/resources{/<RESOURCE>}
Description: Accesses custom resources exposed by a Grafana backend datasource plugin.
Parameters:
  <GRAFANA_HOSTNAME>: The hostname where Grafana is running.
  <PORT>: The port Grafana is listening on.
  <DATASOURCE_UID>: The unique identifier (UID) of the datasource.
  <RESOURCE>: The specific resource path defined in the backend handler (e.g., 'namespaces', 'projects').

Example Usage:
  HTTP GET http://<GRAFANA_HOSTNAME>:<PORT>/api/datasources/uid/<DATASOURCE_UID>/resources/namespaces
  HTTP GET http://<GRAFANA_HOSTNAME>:<PORT>/api/datasources/uid/<DATASOURCE_UID>/resources/projects
```

--------------------------------

### Create a Grafana Scene with Machine Learning Features

Source: https://grafana.com/developers/scenes/scenes-ml/getting-started

This TypeScript code defines an `EmbeddedScene` that includes a time series panel. It integrates `@grafana/scenes-ml` by adding a `SceneBaseliner` to the panel's header actions, enabling built-in controls for trend, lower, and upper bounds on series data. It also registers a demo data source for testing purposes.

```typescript
// helloMLScene.ts

import {
  EmbeddedScene,
  SceneFlexLayout,
  SceneFlexItem,
  SceneQueryRunner,
  PanelBuilders,
  sceneUtils,
} from '@grafana/scenes';
import { SceneBaseliner, MLDemoDS } from '@grafana/scenes-ml';

// Register the demo datasource from `scenes-ml`.
// This isn't required for normal usage, it just gives us some sensible demo data.
sceneUtils.registerRuntimeDataSource({ dataSource: new MLDemoDS('ml-test', 'ml-test') });

function getForecastQueryRunner() {
  return new SceneQueryRunner({
    queries: [{ refId: 'A', datasource: { uid: 'ml-test', type: 'ml-test' }, type: 'forecasts' }],
  });
}

export function getScene() {
  return new EmbeddedScene({
    body: new SceneFlexLayout({
      children: [
        new SceneFlexItem({
          width: '50%',
          height: 300,
          body: PanelBuilders.timeseries()
            .setTitle('Forecast demo')
            .setData(getForecastQueryRunner())
            // Add the `SceneBaseliner` to the panel.
            .setHeaderActions([new SceneBaseliner({ interval: 0.95 })])
            .build(),
        }),
      ],
    }),
  });
}
```

--------------------------------

### Resolve Docker Image Platform Mismatch Errors

Source: https://grafana.com/developers/plugin-tools/troubleshooting

These Docker and npm commands provide a sequence to resolve `image with reference <plugin-name> was found but does not match the specified platform` errors, commonly seen on Apple Silicon Macs. The process involves stopping containers, removing the problematic image, and then restarting the Docker Compose setup.

```Shell
docker compose down
```

```Shell
docker rmi <plugin-name>
```

```Shell
docker compose up
```

```Shell
npm run server
```

--------------------------------

### Scaffold Grafana Plugin Project with create-plugin Tool

Source: https://grafana.com/developers/plugin-tools/tutorials/build-a-streaming-data-source-plugin

This command initializes a new Grafana plugin project using the `@grafana/create-plugin` tool. It interactively prompts the user for plugin details such as name, type (e.g., data source with backend), and organization, generating a basic skeleton with all necessary code and dependencies.

```Shell
npx @grafana/create-plugin@latest
```

--------------------------------

### Migrate Class Component Theme Access to Grafana Theme v2 (withTheme2)

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-7_x-to-8_x

This example illustrates how to update class components to utilize the new Grafana theming system (v2). It shows the transition from the `withTheme` Higher-Order Component (HOC) and `Themeable` type to `withTheme2` HOC and `Themeable2` type for accessing theme variables via props.

```JavaScript
// before
import React from 'react';
import { Themeable, withTheme } from '@grafana/ui';

type Props = {} & Themeable;

class Component extends React.Component<Props> {
  render() {
    const { theme } = this.props;
    // Your component has access to the theme variables now
  }
}

export default withTheme(Component);

// after
import React from 'react';
import { Themeable2, withTheme2 } from '@grafana/ui';

type Props = {} & Themeable2;

class Component extends React.Component<Props> {
  render() {
    const { theme } = this.props;
    // Your component has access to the theme variables now
  }
}

export default withTheme2(Component);
```

--------------------------------

### Initialize Go HTTP ServeMux for Grafana App Plugin

Source: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-backend-component

This Go snippet demonstrates how to set up `http.ServeMux` within a Grafana app plugin's `NewApp` function. It utilizes `httpadapter.New` from the SDK to allow mapping multiple resource routes to `CallResource` without requiring additional custom logic, providing a structured way to handle API endpoints.

```go
type App struct {
	backend.CallResourceHandler
}

// NewApp creates a new example *App instance.
func NewApp(_ context.Context, _ backend.AppInstanceSettings) (instancemgmt.Instance, error) {
	var app App

	// Use an httpadapter (provided by the SDK) for resource calls. This allows us
	// to use a *http.ServeMux for resource calls, so we can map multiple routes
	// to CallResource without having to implement extra logic.
	mux := http.NewServeMux()
	app.registerRoutes(mux)
  // implement the CallResourceHandler interface
	app.CallResourceHandler = httpadapter.New(mux)

	return &app, nil
}
```

--------------------------------

### Converting Legacy Data to DataFrames in Grafana Data Source Query

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-6_x-to-7_0

This example illustrates how to integrate the `toDataFrame` function within a Grafana data source's `query` method. It shows how to process a legacy data request, obtain a `TimeSeries` response, and then convert it into the `DataFrame` format before returning it, ensuring the data source is compatible with Grafana 7.0+ panels.

```TypeScript
async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
  return {
    data: options.targets.map(query => {
      const timeSeries: TimeSeries = await doLegacyRequest(query);
      return toDataFrame(timeSeries);
    }
  };
}
```

--------------------------------

### Register Custom Endpoint with Go ServeMux in Grafana App Plugin

Source: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-backend-component

This Go code illustrates how to register a custom HTTP endpoint (`/myCustomEndpoint`) using `mux.HandleFunc` within the `registerRoutes` function. It also provides an example implementation of the `handleMyCustomEndpoint` function, which processes incoming requests, writes a response, and sets the HTTP status, demonstrating a typical backend API handler.

```go
// this function already exists in the scaffolded app plugin
func (a *App) registerRoutes(mux *http.ServeMux) {
	mux.HandleFunc("/myCustomEndpoint", a.handleMyCustomEndpoint)
}

func (a *App) handleMyCustomEndpoint(w http.ResponseWriter, r *http.Request) {
  // handle the request
  // e.g. call a third-party API
  w.Write([]byte("my custom response"))
  w.WriteHeader(http.StatusOK)
}
```

--------------------------------

### Refactor Grafana Go Plugin Package with New SDK

Source: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/migrate-7_x-to-8_x

This example illustrates the necessary changes within a Grafana backend plugin's `plugin` package to adopt the new `grafana-plugin-sdk-go`. It updates the `NewSampleDatasource` function signature, introduces `Dispose` and `CheckHealth` methods for proper lifecycle management and health checks, and modifies the `Query` method to `QueryData` with updated request/response types.

```Go
// before
package plugin

import (
  "context"

  "github.com/grafana/grafana_plugin_model/go/datasource"
  "github.com/hashicorp/go-hclog"
)

func NewSampleDatasource(pluginLogger hclog.Logger) (*SampleDatasource, error) {
	return &SampleDatasource{
		logger: pluginLogger,
	}, nil
}

type SampleDatasource{
  logger hclog.Logger
}

func (d *SampleDatasource) Query(ctx context.Context, tsdbReq *datasource.DatasourceRequest) (*datasource.DatasourceResponse, error) {
  d.logger.Info("QueryData called", "request", req)
  // logic for querying your datasource.
}
```

```Go
// after
package plugin

import (
  "context"

  "github.com/grafana/grafana-plugin-sdk-go/backend"
  "github.com/grafana/grafana-plugin-sdk-go/backend/instancemgmt"
  "github.com/grafana/grafana-plugin-sdk-go/backend/log"
  "github.com/grafana/grafana-plugin-sdk-go/data"
)

func NewSampleDatasource(_ backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) {
	return &SampleDatasource{}, nil
}

type SampleDatasource{}

func (d *SampleDatasource) Dispose() {
	// Clean up datasource instance resources.
}

func (d *SampleDatasource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
  log.DefaultLogger.Info("QueryData called", "request", req)
  // logic for querying your datasource.
}

func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
  log.DefaultLogger.Info("CheckHealth called", "request", req)
  // The main use case for these health checks is the test button on the
  // datasource configuration page which allows users to verify that
  // a datasource is working as expected.
}
```

--------------------------------

### Access Grafana App Instance Settings in Go

Source: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/add-backend-component

These Go code snippets demonstrate two ways to access application instance settings within a Grafana backend plugin. The first shows accessing settings directly in the app constructor, while the second illustrates retrieving them from the request context in a handler function.

```go
func NewApp(ctx context.Context, settings backend.AppInstanceSettings) (instancemgmt.Instance, error) {
  jsonData := settings.JSONData // json.RawMessage
  secureJsonData := settings.DecryptedSecureJSONData // map[string]string
}
```

```go
func (a *App) handleMyRequest(w http.ResponseWriter, req *http.Request) {
  pluginConfig := backend.PluginConfigFromContext(req.Context())
  jsonData := pluginConfig.AppInstanceSettings.JSONData // json.RawMessage
}
```

--------------------------------

### Configure Grafana Plugin Bundle Stats Workflow

Source: https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment

This GitHub Actions workflow (`bundle-stats.yml`) helps developers monitor the size of their plugin's frontend assets. Triggered by pull requests, it compares webpack stats files between the default branch and the PR branch, calculates size differences, and posts a formatted comment to the PR. It requires `contents: write`, `pull-requests: write`, and `actions: read` permissions.

```yaml
name: Bundle Stats

on:
  workflow_dispatch:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write
  actions: read

jobs:
  compare:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - uses: grafana/plugin-actions/bundle-size@main
```

--------------------------------

### Install @grafana/plugin-e2e Development Dependency

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/migrate-from-grafana-e2e

This snippet provides commands to install the `@grafana/plugin-e2e` package as a development dependency using npm, Yarn, or pnpm. This package extends Playwright APIs and is essential for modern Grafana plugin end-to-end testing.

```Shell
npm install @grafana/plugin-e2e@latest --save-dev
```

```Shell
yarn add @grafana/plugin-e2e@latest --dev
```

```Shell
pnpm add @grafana/plugin-e2e@latest --save-dev
```

--------------------------------

### Install Playwright Browsers with Dependencies

Source: https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/ci

Installs the necessary browser binaries and their associated dependencies required for running Playwright tests. This ensures that the testing environment is fully equipped for browser automation and UI testing.

```shell
pnpm playwright install --with-deps
```
Tokens:
Raw