mirror of https://github.com/grafana/grafana
Docs: Plugins doc reorganization, part 1 (#69864)
* Initial commit * Prettier fixes * Doc-validator fixes part 1 * Doc-validator fixes part 2 * More doc-validator fixes * More doc-validator fixes * Test * link test * Linnk test * Link test * More fixes * More fixes * Doc-validator fixes * Doc-validator fixes * fix broken link * Fix * Testing * Doc fixes * Link fixes * Fix links * Update docs/sources/developers/plugins/create-a-grafana-plugin/_index.md Co-authored-by: David Harris <david.harris@grafana.com> * Testing * Testing * Testing * Testing * Doc-validator fixes * Doc-validator fixes * Doc-validator fixes * Fix broken links for plugins reorganization project * Prettier fixes * Prettier fixes * Incorporate reviewer feedback * Link fixes * Link fixes * Link fixes * Link fix * Deleted space * Codeowners fix * Change grafana.com links to absolute URLs for Hugo --------- Co-authored-by: David Harris <david.harris@grafana.com>pull/71098/head^2
Joseph Perez
3 years ago
committed by
GitHub
parent
bdf60d69de
commit
f9df1f3051
@ -1,27 +1,18 @@ |
||||
--- |
||||
description: How-to topics for plugin development |
||||
title: Create a plugin |
||||
title: Create a Grafana plugin |
||||
menuTitle: Create a plugin |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- documentation |
||||
description: An index of how-to topics for Grafana plugin development. |
||||
weight: 300 |
||||
--- |
||||
|
||||
# Create a Grafana plugin |
||||
|
||||
This section contains how-to topics for developing Grafana plugins. |
||||
This section contains how-to topics for developing and extending Grafana plugins with more advanced capabilities. |
||||
|
||||
- [Build a Grafana plugin](https://grafana.github.io/plugin-tools/docs/creating-a-plugin) |
||||
- [Build a panel plugin](https://grafana.com/tutorials/build-a-panel-plugin/) |
||||
- [Build a data source plugin](https://grafana.com/tutorials/build-a-data-source-plugin/) |
||||
- [Build a data source backend plugin](https://grafana.com/tutorials/build-a-data-source-backend-plugin/) |
||||
- [Build a logs data source plugin]({{< relref "../build-a-logs-data-source-plugin.md">}}) |
||||
- [Build a streaming data source plugin]({{< relref "../build-a-streaming-data-source-plugin.md">}}) |
||||
- Extend a Grafana plugin |
||||
- [Add annotations]({{< relref "add-support-for-annotations.md">}}) |
||||
- [Add anonymous usage reporting]({{< relref "add-anonymous-usage-reporting.md">}}) |
||||
- [Add authentication for a data source plugin]({{< relref "add-authentication-for-data-source-plugins.md">}}) |
||||
- [Add Explore queries]({{< relref "add-support-for-explore-queries.md">}}) |
||||
- [Add query editor help]({{< relref "add-query-editor-help.md">}}) |
||||
- [Add variables]({{< relref "add-support-for-variables.md">}}) |
||||
- [Create panel option editors]({{< relref "custom-panel-option-editors.md">}}) |
||||
- [Sign a plugin]({{< relref "sign-a-plugin.md">}}) |
||||
- [Automate development with CI](https://grafana.github.io/plugin-tools/docs/ci) |
||||
- [Create nested plugins](https://grafana.github.io/plugin-tools/docs/nested-plugins) |
||||
- [Extend configurations](https://grafana.github.io/plugin-tools/docs/advanced-configuration) |
||||
- [Develop a plugin]({{< relref "./develop-a-plugin" >}}) |
||||
- [Extend a plugin]({{< relref "./extend-a-plugin" >}}) |
||||
|
||||
@ -0,0 +1,28 @@ |
||||
--- |
||||
title: Develop a Grafana plugin |
||||
menuTitle: Develop a plugin |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- development |
||||
- documentation |
||||
description: An index of how-to topics for Grafana plugin development. |
||||
weight: 100 |
||||
--- |
||||
|
||||
# Develop a Grafana plugin |
||||
|
||||
This section contains how-to topics for developing Grafana plugins: |
||||
|
||||
- [Build a panel plugin]({{< relref "./build-a-panel-plugin.md" >}}) |
||||
- [Build a panel plugin with d3.js]({{< relref "./build-a-panel-plugin-with-d3.md" >}}) |
||||
- [Build a data source plugin]({{< relref "./build-a-data-source-plugin.md" >}}) |
||||
- [Build a data source backend plugin]({{< relref "./build-a-data-source-backend-plugin.md" >}}) |
||||
- [Build a logs data source plugin]({{< relref "./build-a-logs-data-source-plugin.md" >}}) |
||||
- [Build a streaming data source plugin]({{< relref "./build-a-streaming-data-source-plugin.md" >}}) |
||||
- [Work with data frames]({{< relref "./working-with-data-frames.md" >}}) |
||||
|
||||
Additional resources: |
||||
|
||||
- [Build a Grafana plugin with the create-plugin tool](https://grafana.github.io/plugin-tools/docs/creating-a-plugin) |
||||
@ -1,14 +1,15 @@ |
||||
--- |
||||
title: Build a panel plugin with D3.js |
||||
summary: Learn how to use D3.js in your panel plugins. |
||||
description: how to use D3.js in your panel plugins. |
||||
id: build-a-panel-plugin-with-d3 |
||||
categories: ['plugins'] |
||||
tags: ['beginner'] |
||||
status: Published |
||||
authors: ['grafana_labs'] |
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new |
||||
weight: 60 |
||||
weight: 200 |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- d3js |
||||
- d3 |
||||
- panel |
||||
- panel plugin |
||||
--- |
||||
|
||||
## Introduction |
||||
@ -1,14 +1,15 @@ |
||||
--- |
||||
title: Build a panel plugin |
||||
summary: Learn how to create a custom visualization for your dashboards. |
||||
description: Learn how to create a custom visualization for your dashboards. |
||||
id: build-a-panel-plugin |
||||
categories: ['plugins'] |
||||
tags: ['beginner'] |
||||
status: Published |
||||
authors: ['grafana_labs'] |
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new |
||||
weight: 50 |
||||
weight: 100 |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- visualization |
||||
- custom visualization |
||||
- dashboard |
||||
- dashboards |
||||
--- |
||||
|
||||
## Introduction |
||||
@ -1,15 +1,14 @@ |
||||
--- |
||||
title: Build an app plugin |
||||
summary: Learn at how to create an app for Grafana. |
||||
description: Learn at how to create an app for Grafana. |
||||
id: build-an-app-plugin |
||||
categories: ['plugins'] |
||||
tags: ['beginner'] |
||||
status: Published |
||||
authors: ['grafana_labs'] |
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new |
||||
weight: 50 |
||||
weight: 700 |
||||
draft: true |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- app |
||||
- app plugin |
||||
--- |
||||
|
||||
## Introduction |
||||
@ -1,14 +1,24 @@ |
||||
--- |
||||
title: Work with data frames |
||||
aliases: |
||||
- ../../../plugins/working-with-data-frames/ |
||||
description: How to work with data frames. |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- data frames |
||||
- dataframes |
||||
weight: 900 |
||||
--- |
||||
|
||||
# Work with data frames |
||||
|
||||
The [data frame]({{< relref "data-frames" >}}) is a columnar data structure that allows for efficient querying of large amounts of data. Since data frames are a central concept when developing plugins for Grafana, in this guide we'll look at some ways you can use them. |
||||
The [data frame]({{< relref "../../introduction-to-plugin-development/data-frames" >}}) is a columnar data structure that allows for efficient querying of large amounts of data. Since data frames are a central concept when developing plugins for Grafana, in this guide we'll look at some ways you can use them. |
||||
|
||||
The `DataFrame` interface contains a `name` and an array of `fields` where each field contains the name, type, and the values for the field. |
||||
|
||||
> **Note:** If you want to migrate an existing plugin to use the data frame format, refer to [Migrate to data frames]({{< relref "migration-guide/#migrate-to-data-frames" >}}). |
||||
> **Note:** If you want to migrate an existing plugin to use the data frame format, refer to [Migrate to data frames]({{< relref "../../migration-guide/v6.x-v7.x#migrate-to-data-frames" >}}). |
||||
|
||||
## Create a data frame |
||||
|
||||
@ -0,0 +1,34 @@ |
||||
--- |
||||
title: Extend a Grafana plugin |
||||
menuTitle: Extend a plugin |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- development |
||||
- extension |
||||
- documentation |
||||
description: An index of how-to topics for extending or enhancing Grafana plugins. |
||||
weight: 200 |
||||
--- |
||||
|
||||
# Extend a Grafana plugin |
||||
|
||||
This section contains how-to topics for extending or enhancing Grafana plugins: |
||||
|
||||
- [Enable annotations]({{< relref "./add-support-for-annotations.md" >}}) |
||||
- [Add anonymous usage reporting]({{< relref "./add-anonymous-usage-reporting.md" >}}) |
||||
- [Add authentication for a data source plugin]({{< relref "./add-authentication-for-data-source-plugins.md" >}}) |
||||
- [Add distributed tracing for backend plugins]({{< relref "./add-distributed-tracing-for-backend-plugins.md" >}}) |
||||
- [Add features to Explore queries]({{< relref "./add-support-for-explore-queries.md" >}}) |
||||
- [Add query editor help]({{< relref "./add-query-editor-help.md" >}}) |
||||
- [Add support for variables]({{< relref "./add-support-for-variables.md" >}}) |
||||
- [Build a custom panel option editor]({{< relref "./custom-panel-option-editors.md" >}}) |
||||
- [Use extensions to add links to app plugins]({{< relref "./extend-the-grafana-ui-with-links.md" >}}) |
||||
- [Work with cross-plugin links]({{< relref "./cross-plugin-linking.md" >}}) |
||||
|
||||
Additional resources: |
||||
|
||||
- [Automate development with CI](https://grafana.github.io/plugin-tools/docs/ci) |
||||
- [Create nested plugins](https://grafana.github.io/plugin-tools/docs/nested-plugins) |
||||
- [Extend configurations](https://grafana.github.io/plugin-tools/docs/advanced-configuration) |
||||
@ -1,10 +1,20 @@ |
||||
--- |
||||
title: Add anonymous usage reporting |
||||
aliases: |
||||
- ../../../plugins/add-anonymous-usage-reporting/ |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- anonymous usage |
||||
- reporting |
||||
description: How to add anonymous usage tracking to your Grafana plugin. |
||||
weight: 200 |
||||
--- |
||||
|
||||
# Add anonymous usage reporting |
||||
|
||||
Add anonymous usage tracking to your plugin to send [reporting events]({{< relref "../../setup-grafana/configure-grafana/#reporting_enabled" >}}) that describe how your plugin is being used to a tracking system configured by your Grafana server administrator. |
||||
Add anonymous usage tracking to your plugin to send [reporting events]({{< relref "../../../../setup-grafana/configure-grafana#reporting_enabled" >}}) that describe how your plugin is being used to a tracking system configured by your Grafana server administrator. |
||||
|
||||
## Event reporting |
||||
|
||||
@ -1,5 +1,16 @@ |
||||
--- |
||||
title: Add query editor help |
||||
aliases: |
||||
- ../../../plugins/add-query-editor-help/ |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- queries |
||||
- query editor |
||||
- query editor help |
||||
description: How to add a help component to query editors in Grafana. |
||||
weight: 500 |
||||
--- |
||||
|
||||
# Add query editor help |
||||
@ -1,16 +1,26 @@ |
||||
--- |
||||
title: Add support for annotations |
||||
title: Enable annotations |
||||
menuTitle: Enable annotations |
||||
aliases: |
||||
- ../../../plugins/add-support-for-annotations/ |
||||
description: Add support for annotations in your plugin. |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- annotations |
||||
weight: 100 |
||||
--- |
||||
|
||||
# Add support for annotations |
||||
# Enable annotations |
||||
|
||||
You can add support to your plugin for annotations that will insert information into Grafana alerts. This guide explains how to add support for [annotations]({{< relref "../../dashboards/build-dashboards/annotate-visualizations/#querying-other-data-sources " >}}) to a data source plugin. |
||||
You can add support to your plugin for annotations that will insert information into Grafana alerts. This guide explains how to add support for [annotations]({{< relref "../../../../dashboards/build-dashboards/annotate-visualizations#querying-other-data-sources" >}}) to a data source plugin. |
||||
|
||||
## Support annotations in your data source plugin |
||||
|
||||
To enable annotations, simply add two lines of code to your plugin. Grafana uses your default query editor for editing annotation queries. |
||||
|
||||
1. Add `"annotations": true` to the [plugin.json]({{< relref "metadata/" >}}) file to let Grafana know that your plugin supports annotations. |
||||
1. Add `"annotations": true` to the [plugin.json]({{< relref "../../metadata.md" >}}) file to let Grafana know that your plugin supports annotations. |
||||
|
||||
**In `plugin.json`:** |
||||
|
||||
@ -1,10 +1,21 @@ |
||||
--- |
||||
title: Add features to Explore queries |
||||
aliases: |
||||
- ../../../plugins/add-support-for-explore-queries/ |
||||
description: Add features to Explore queries. |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- queries |
||||
- explore queries |
||||
- explore |
||||
weight: 400 |
||||
--- |
||||
|
||||
# Add features for Explore queries |
||||
# Add features to Explore queries |
||||
|
||||
[Explore]({{< relref "../../explore/" >}}) allows users can make ad-hoc queries without the use of a dashboard. This is useful when they want to troubleshoot or learn more about the data. |
||||
[Explore]({{< relref "../../../../explore" >}}) allows users can make ad-hoc queries without the use of a dashboard. This is useful when they want to troubleshoot or learn more about the data. |
||||
|
||||
Your data source supports Explore by default and uses the existing query editor for the data source. This guide explains how to extend functionality for Explore queries in a data source plugin. |
||||
|
||||
@ -1,6 +1,17 @@ |
||||
--- |
||||
title: Work with cross-plugin links |
||||
description: Learn how to add plugin links to a Grafana app plugin |
||||
aliases: |
||||
- ../../../plugins/cross-plugin-linking/ |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- links |
||||
- cross-plugin links |
||||
- extensions |
||||
- extensions api |
||||
description: Learn how to add plugin links to a Grafana app plugin. |
||||
weight: 800 |
||||
--- |
||||
|
||||
# Work with cross-plugin links |
||||
@ -1,5 +1,16 @@ |
||||
--- |
||||
title: Build a custom panel option editor |
||||
aliases: |
||||
- ../../../plugins/custom-panel-option-editors/ |
||||
description: How to build a custom panel option editor. |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- custom panel option editor |
||||
- customizing panel options |
||||
- panel options |
||||
weight: 700 |
||||
--- |
||||
|
||||
# Build a custom panel option editor |
||||
@ -1,12 +1,23 @@ |
||||
--- |
||||
description: Get started guide |
||||
title: Get started with plugins |
||||
title: Get started with Grafana plugin development |
||||
menuTitle: Get started with plugins |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- documentation |
||||
description: Get started with Grafana plugin development. |
||||
weight: 200 |
||||
--- |
||||
|
||||
# Get started with Grafana plugins |
||||
# Get started with Grafana plugin development |
||||
|
||||
This section contains guidance for building plugins. |
||||
This section contains guidance for building plugins: |
||||
|
||||
- [Develop with local Grafana]({{< relref "./development-with-local-grafana.md" >}}) |
||||
|
||||
Additional resources: |
||||
|
||||
- [Get started with creating a plugin](https://grafana.github.io/plugin-tools/docs/getting-started) |
||||
- [Types of Grafana plugins](https://grafana.com/docs/grafana/latest/administration/plugin-management/) |
||||
- [Types of Grafana plugins](/docs/grafana/latest/administration/plugin-management/) |
||||
- [Set up your development environment](https://grafana.github.io/plugin-tools/docs/docker) |
||||
|
||||
@ -1,5 +1,15 @@ |
||||
--- |
||||
title: Develop with a local environment |
||||
aliases: |
||||
- ../../plugins/development-with-local-grafana/ |
||||
description: How to develop with a local Grafana environment. |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- development environment |
||||
- local environment |
||||
weight: 400 |
||||
--- |
||||
|
||||
# Develop with a local environment |
||||
@ -1,13 +1,21 @@ |
||||
--- |
||||
description: Conceptual topics for plugin development |
||||
title: Introduction to plugin development |
||||
title: Introduction to Grafana plugin development |
||||
menuTitle: Introduction to plugin development |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- documentation |
||||
description: Conceptual topics for Grafana plugin development. |
||||
weight: 100 |
||||
--- |
||||
|
||||
# Introduction to Grafana plugin development |
||||
|
||||
This section contains topics related to the key concepts for Grafana plugin development. |
||||
This section contains documentation related to the key concepts for Grafana plugin development. |
||||
|
||||
- [Backend plugins]({{< relref "../backend/" >}}) |
||||
- [Grafana plugin SDK for Go]({{< relref "../backend/grafana-plugin-sdk-for-go.md" >}}) |
||||
- [Plugin protocol]({{< relref "../backend/plugin-protocol.md" >}}) |
||||
- [Data frames]({{< relref "data-frames.md">}}) |
||||
- [Backend plugins]({{< relref "./backend" >}}) |
||||
- [Grafana plugin SDK for Go]({{< relref "./backend/grafana-plugin-sdk-for-go.md" >}}) |
||||
- [Plugin protocol]({{< relref "./backend/plugin-protocol.md" >}}) |
||||
- [Data frames]({{< relref "./data-frames.md" >}}) |
||||
- [Error handling]({{< relref "./error-handling.md" >}}) |
||||
|
||||
@ -1,11 +1,21 @@ |
||||
--- |
||||
description: Topics related to plugin publishing |
||||
title: Publish a plugin |
||||
title: Publish or sign a plugin |
||||
menuTitle: Publish a plugin |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- publish |
||||
- publishing |
||||
description: An index to documentation related to plugin publishing and signing. |
||||
weight: 400 |
||||
--- |
||||
|
||||
# Publish a plugin |
||||
# Publish or sign a plugin |
||||
|
||||
This section contains topics related to publishing Grafana plugins. |
||||
This section contains topics related to publishing and signing Grafana plugins. |
||||
|
||||
- [Publishing and signing criteria]({{< relref "../publishing-and-signing-criteria.md">}}) |
||||
- [Publish or update a plugin]({{< relref "../publish-or-update-a-plugin.md">}}) |
||||
- [Package a plugin]({{< relref "./package-a-plugin.md" >}}) |
||||
- [Publishing and signing criteria]({{< relref "./publishing-and-signing-criteria.md" >}}) |
||||
- [Publish or update a plugin]({{< relref "./publish-or-update-a-plugin.md" >}}) |
||||
- [Sign a plugin]({{< relref "./sign-a-plugin.md" >}}) |
||||
|
||||
@ -1,10 +1,22 @@ |
||||
--- |
||||
title: Plugin publishing and signing criteria |
||||
description: Acceptance criteria for publishing and signing Grafana plugins. |
||||
aliases: |
||||
- ../../plugins/publishing-and-signing-criteria/ |
||||
keywords: |
||||
- grafana |
||||
- plugins |
||||
- plugin |
||||
- publish plugin |
||||
- sign plugin |
||||
- publishing |
||||
- signing |
||||
weight: 200 |
||||
--- |
||||
|
||||
# Plugin publishing and signing criteria |
||||
|
||||
Grafana plugins must adhere to the Grafana Labs [Plugin Policy](https://grafana.com/legal/plugins/). Our review process for publishing and signing will examine your compliance with this policy. |
||||
Grafana plugins must adhere to the Grafana Labs [Plugin Policy](/legal/plugins/). Our review process for publishing and signing will examine your compliance with this policy. |
||||
|
||||
> **Important:** Grafana Labs reserves the right to decline or remove any plugin at its discretion. Failure to comply with publishing and signing criteria may result in immediate removal from the Grafana plugin catalog. |
||||
|
||||
@ -1,164 +0,0 @@ |
||||
--- |
||||
title: Build a streaming data source backend plugin |
||||
summary: Create a backend for your data source plugin with streaming capabilities. |
||||
description: Create a backend for your data source plugin with streaming capabilities. |
||||
id: build-a-streaming-data-source-backend-plugin |
||||
categories: ['plugins'] |
||||
tags: ['beginner'] |
||||
status: Published |
||||
authors: ['grafana_labs'] |
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new |
||||
weight: 75 |
||||
--- |
||||
|
||||
## Introduction |
||||
|
||||
Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. In previous tutorials we have shown how to extend Grafana capabilities to query custom data sources by [building a backend datasource plugin](/tutorials/build-a-data-source-backend-plugin/). In this tutorial we take a step further and add streaming capabilities to the backend datasource plugin. Streaming allows plugins to push data to Grafana panels as soon as data appears (without periodic polling from UI side). |
||||
|
||||
For more information about backend plugins, refer to the documentation on [Backend plugins](/docs/grafana/latest/developers/plugins/backend/). |
||||
|
||||
In this tutorial, you'll: |
||||
|
||||
- Extend a backend plugin with streaming capabilities |
||||
|
||||
{{% class "prerequisite-section" %}} |
||||
|
||||
#### Prerequisites |
||||
|
||||
- Knowledge about how data sources are implemented in the frontend. |
||||
- Knowledge about [backend datasource anatomy](/tutorials/build-a-data-source-backend-plugin/) |
||||
- Grafana 8.0+ |
||||
- Go ([Version](https://github.com/grafana/plugin-tools/blob/main/packages/create-plugin/templates/backend/go.mod#L3)) |
||||
- [Mage](https://magefile.org/) |
||||
- NodeJS ([Version](https://github.com/grafana/plugin-tools/blob/main/packages/create-plugin/templates/common/package.json#L66)) |
||||
- yarn |
||||
{{% /class %}} |
||||
|
||||
## Set up your environment |
||||
|
||||
{{< docs/shared lookup="tutorials/set-up-environment.md" source="grafana" version="latest" >}} |
||||
|
||||
## Create a new plugin |
||||
|
||||
To build a backend for your data source plugin, Grafana requires a binary that it can execute when it loads the plugin during start-up. In this guide, we will build a binary using the [Grafana plugin SDK for Go](/docs/grafana/latest/developers/plugins/backend/grafana-plugin-sdk-for-go/). |
||||
|
||||
The easiest way to get started is to use the Grafana [create-plugin tool](https://www.npmjs.com/package/@grafana/create-plugin). Navigate to the plugin folder that you configured in step 1 and enter: |
||||
|
||||
``` |
||||
npx @grafana/create-plugin@latest |
||||
``` |
||||
|
||||
Follow the steps and select **datasource** as your plugin type and answer **yes** when prompted to create a backend for your plugin. |
||||
|
||||
```bash |
||||
cd my-plugin |
||||
``` |
||||
|
||||
Install frontend dependencies and build frontend parts of the plugin to _dist_ directory: |
||||
|
||||
```bash |
||||
yarn install |
||||
yarn build |
||||
``` |
||||
|
||||
Run the following to update [Grafana plugin SDK for Go](/docs/grafana/latest/developers/plugins/backend/grafana-plugin-sdk-for-go/) dependency to the latest minor version: |
||||
|
||||
```bash |
||||
go get -u github.com/grafana/grafana-plugin-sdk-go |
||||
go mod tidy |
||||
``` |
||||
|
||||
Build backend plugin binaries for Linux, Windows and Darwin to _dist_ directory: |
||||
|
||||
```bash |
||||
mage -v |
||||
``` |
||||
|
||||
Now, let's verify that the plugin you've built can be used in Grafana when creating a new data source: |
||||
|
||||
1. Restart your Grafana instance. |
||||
1. Open Grafana in your web browser. |
||||
1. Navigate via the side-menu to **Configuration** -> **Data Sources**. |
||||
1. Click **Add data source**. |
||||
1. Find your newly created plugin and select it. |
||||
1. Enter a name and then click **Save & Test** (ignore any errors reported for now). |
||||
|
||||
You now have a new data source instance of your plugin that is ready to use in a dashboard. To confirm, follow these steps: |
||||
|
||||
1. Navigate via the side-menu to **Create** -> **Dashboard**. |
||||
1. Click **Add new panel**. |
||||
1. In the query tab, select the data source you just created. |
||||
1. A line graph is rendered with one series consisting of two data points. |
||||
1. Save the dashboard. |
||||
|
||||
### Troubleshooting |
||||
|
||||
#### Grafana doesn't load my plugin |
||||
|
||||
By default, Grafana requires backend plugins to be signed. To load unsigned backend plugins, you need to |
||||
configure Grafana to [allow unsigned plugins](/docs/grafana/latest/plugins/plugin-signature-verification/#allow-unsigned-plugins). |
||||
For more information, refer to [Plugin signature verification](/docs/grafana/latest/plugins/plugin-signature-verification/#backend-plugins). |
||||
|
||||
## Anatomy of a backend plugin |
||||
|
||||
As you may notice till this moment we did the same steps described in [build a backend datasource plugin tutorial](/tutorials/build-a-data-source-backend-plugin/). At this point, you should be familiar with backend plugin structure and a way how data querying and health check capabilities could be implemented. Let's take the next step and discuss how datasource plugin can handle data streaming. |
||||
|
||||
## Add streaming capabilities |
||||
|
||||
What we want to achieve here is to issue a query to load initial data from a datasource plugin and then switching to data streaming mode where the plugin will push data frames to Grafana time-series panel. |
||||
|
||||
In short – implementing a streaming plugin means implementing a `backend.StreamHandler` interface which contains `SubscribeStream`, `RunStream`, and `PublishStream` methods. |
||||
|
||||
`SubscribeStream` is a method where the plugin has a chance to authorize user subscription requests to a channel. Users on the frontend side subscribe to different channels to consume real-time data. |
||||
|
||||
When returning a `data.Frame` with initial data we can return a special field `Channel` to let the frontend know that we are going to stream data frames after initial data load. When the frontend receives a frame with a `Channel` set it automatically issues a subscription request to that channel. |
||||
|
||||
Channel is a string identifier of topic to which clients can subscribe in Grafana Live. See a documentation of Grafana Live for [details about channel structure](/docs/grafana/latest/live/live-channel/). |
||||
|
||||
As said in docs in Grafana Live channel consists of 3 parts delimited by `/`: |
||||
|
||||
- Scope |
||||
- Namespace |
||||
- Path |
||||
|
||||
For datasource plugin channels Grafana uses `ds` scope. Namespace in the case of datasource channels is a datasource unique ID (UID) which is issued by Grafana at the moment of datasource creation. The path is a custom string that plugin authors free to choose themselves (just make sure it consists of allowed symbols). I.e. datasource channel looks like `ds/<DATASOURCE_UID>/<CUSTOM_PATH>`. |
||||
|
||||
So to let the frontend know that we are going to stream data we set a `Channel` field into frame metadata inside `QueryData` implementation. In our tutorial it's a `ds/<DATASOURCE_UID>/stream`. The frontend will issue a subscription request to this channel. |
||||
|
||||
Inside `SubscribeStream` implementation we check whether a user allowed to subscribe on a channel path. If yes – we return an OK status code to tell Grafana user can join a channel: |
||||
|
||||
```go |
||||
status := backend.SubscribeStreamStatusPermissionDenied |
||||
if req.Path == "stream" { |
||||
// Allow subscribing only on expected path. |
||||
status = backend.SubscribeStreamStatusOK |
||||
} |
||||
return &backend.SubscribeStreamResponse{ |
||||
Status: status, |
||||
}, nil |
||||
``` |
||||
|
||||
As soon as the first subscriber joins a channel Grafana opens a unidirectional stream to consume streaming frames from a plugin. To handle this and to push data towards clients we implement a `RunStream` method which provides a way to push JSON data into a channel. So we can push data frame like this (error handling skipped): |
||||
|
||||
```go |
||||
// Send frame to stream including both frame schema and data frame parts. |
||||
_ = sender.SendFrame(frame, data.IncludeAll) |
||||
``` |
||||
|
||||
Open example datasource query editor and make sure `With Streaming` toggle is on. After doing this you should see data displayed and then periodically updated by streaming frames coming periodically from `RunStream` method. |
||||
|
||||
The important thing to note is that Grafana opens a unidirectional stream only once per channel upon the first subscriber joined. Every other subscription request will be still authorized by `SubscribeStream` method but the new `RunStream` won't be issued. I.e. you can have many active subscribers but only one running stream. At this moment this guarantee works for a single Grafana instance, we are planning to support this for highly-available Grafana setup (many Grafana instances behind load-balancer) in future releases. |
||||
|
||||
The stream will be automatically closed as soon as all subscriber users left. |
||||
|
||||
For the tutorial use case, we only need to properly implement `SubscribeStream` and `RunStream` - we don't need to handle publications to a channel from users. But we still need to write `PublishStream` method to fully implement `backend.StreamHandler` interface. Inside `PublishStream` we just do not allow any publications from users since we are pushing data from a backend: |
||||
|
||||
```go |
||||
return &backend.PublishStreamResponse{ |
||||
Status: backend.PublishStreamStatusPermissionDenied, |
||||
}, nil |
||||
``` |
||||
|
||||
## Summary |
||||
|
||||
In this tutorial you created a backend for your data source plugin with streaming capabilities. |
||||
Loading…
Reference in new issue