mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
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>
This commit is contained in:
Joseph Perez
GitHub
parent
bdf60d69de
commit
f9df1f3051
2
.github/CODEOWNERS
vendored
2
.github/CODEOWNERS
vendored
@ -50,7 +50,7 @@
|
||||
/docs/sources/upgrade-guide/ @chri2547 @imatwawana
|
||||
/docs/sources/whatsnew/ @chri2547 @imatwawana
|
||||
/docs/sources/developers/plugins/ @Eve832 @josmperez @grafana/plugins-platform-frontend @grafana/plugins-platform-backend
|
||||
/docs/sources/developers/plugins/backend/ @Eve832 @grafana/plugins-platform-backend
|
||||
/docs/sources/developers/plugins/introduction-to-plugin-development/backend/ @Eve832 @grafana/plugins-platform-backend
|
||||
|
||||
# Backend code
|
||||
/go.mod @grafana/backend-platform
|
||||
|
||||
@ -85,7 +85,7 @@ You can assign data source permissions to users, teams, and roles which will all
|
||||
|
||||
When you enable query and resource caching, Grafana temporarily stores the results of data source queries and resource requests. When you or another user submit the same query or resource request again, the results will come back from the cache instead of from the data source.
|
||||
|
||||
When using Grafana, a query pertains to a request for data frames to be modified or displayed. A resource relates to any HTTP requests made by a plugin, such as the Amazon Timestream plugin requesting a list of available databases from AWS. For more information on data source queries and resources, please see the developers page on [backend plugins]({{< relref "../../developers/plugins/backend/" >}}).
|
||||
When using Grafana, a query pertains to a request for data frames to be modified or displayed. A resource relates to any HTTP requests made by a plugin, such as the Amazon Timestream plugin requesting a list of available databases from AWS. For more information on data source queries and resources, please see the developers page on [backend plugins]({{< relref "../../developers/plugins/introduction-to-plugin-development/backend/" >}}).
|
||||
|
||||
The caching feature works for **all** backend data sources. You can enable the cache globally in Grafana's [configuration]({{< relref "../../setup-grafana/configure-grafana/enterprise-configuration/#caching" >}}), and configure a cache duration (also called Time to Live, or TTL) for each data source individually.
|
||||
|
||||
@ -120,7 +120,7 @@ Query caching works for Grafana's [built-in data sources]({{< relref "../../data
|
||||
To verify that a data source works with query caching, follow the [instructions below](#enable-and-configure-query-caching) to **Enable and Configure query caching**. If caching is enabled in Grafana but the Caching tab is not visible for the given data source, then query caching is not available for that data source.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana _query_ caching does not significantly improve performance. However, _resource_ caching may help. See the developers page on [plugin resources]({{< relref "../../developers/plugins/backend/#resources" >}}) for details.
|
||||
Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana _query_ caching does not significantly improve performance. However, _resource_ caching may help. See the developers page on [plugin resources]({{< relref "../../developers/plugins/introduction-to-plugin-development/backend/#resources" >}}) for details.
|
||||
{{% /admonition %}}
|
||||
|
||||
### Enable and configure query caching
|
||||
|
||||
@ -167,7 +167,7 @@ Grafana also writes an error message to the server log:
|
||||
WARN[05-26|12:00:00] Some plugin scanning errors were found errors="plugin '<plugin id>' is unsigned, plugin '<plugin id>' has an invalid signature"
|
||||
```
|
||||
|
||||
If you are a plugin developer and want to know how to sign your plugin, refer to [Sign a plugin]({{< relref "../../developers/plugins/sign-a-plugin/" >}}).
|
||||
If you are a plugin developer and want to know how to sign your plugin, refer to [Sign a plugin]({{< relref "../../developers/plugins/publish-a-plugin/sign-a-plugin.md" >}}).
|
||||
|
||||
| Signature status | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------- |
|
||||
|
||||
@ -222,7 +222,7 @@ The resulting table panel:
|
||||
If you set the **Format** setting in the query editor to **Time series**, then the query must have a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds.
|
||||
Result sets of time series queries must also be sorted by time for panels to properly visualize the result.
|
||||
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../../developers/plugins/data-frames#wide-format" >}}).
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../../developers/plugins/introduction-to-plugin-development/data-frames#wide-format" >}}).
|
||||
Any column except time or of type string transforms into value fields in the data frame query result.
|
||||
Any string column transforms into field labels in the data frame query result.
|
||||
|
||||
|
||||
@ -278,7 +278,7 @@ The resulting table panel:
|
||||
|
||||
If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result.
|
||||
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../developers/plugins/data-frames#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
|
||||
|
||||
> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below.
|
||||
|
||||
|
||||
@ -227,7 +227,7 @@ The resulting table panel:
|
||||
|
||||
If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result.
|
||||
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../developers/plugins/data-frames#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
|
||||
A time series query result is returned in a [wide data frame format]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
|
||||
|
||||
> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below.
|
||||
|
||||
|
||||
@ -1,8 +1,9 @@
|
||||
---
|
||||
title: Grafana plugin developer's guide
|
||||
menuTitle: Plugin developer's guide
|
||||
aliases:
|
||||
- ../plugins/developing/
|
||||
description: Resources for creating Grafana plugins
|
||||
title: Plugin developer's guide
|
||||
weight: 200
|
||||
---
|
||||
|
||||
@ -10,7 +11,7 @@ weight: 200
|
||||
|
||||
You can extend Grafana's built-in capabilities with plugins. Plugins enable Grafana to accomplish specialized tasks, custom-tailored to your requirements. By making a plugin for your organization, you can connect Grafana to other data sources, ticketing tools, and CI/CD tooling.
|
||||
|
||||
You can create plugins for private use or contribute them to the open source community by publishing to the [Grafana plugin catalog](https://grafana.com/grafana/plugins/). This catalog has hundreds of other community and commercial plugins.
|
||||
You can create plugins for private use or contribute them to the open source community by publishing to the [Grafana plugin catalog](/grafana/plugins/). This catalog has hundreds of other community and commercial plugins.
|
||||
|
||||
If you are a Grafana plugin developer or want to become one, this plugin developer's guide contains the tutorials and reference materials to help you get started.
|
||||
|
||||
@ -28,12 +29,13 @@ You can create several types of plugins, including:
|
||||
|
||||
The following topics are covered in this guide:
|
||||
|
||||
- **[Get started with plugins]({{< relref "./get-started-with-plugins" >}})** - Start developing Grafana plugins with the [Create-plugin](https://www.npmjs.com/package/@grafana/create-plugin) tool.
|
||||
- **[Introduction to plugin development]({{< relref "./introduction-to-plugin-development" >}})** - Learn the fundamentals of Grafana plugin development: frontend and backend development processes, data frames, error handling, and more.
|
||||
- **[Create a Grafana plugin]({{< relref "./create-a-grafana-plugin" >}})** - If you're familiar with plugin creation, use the tutorials for creating panel plugins, data source plugins, and more to deepen your knowledge.
|
||||
- **[Migrate a plugin]({{< relref "./migration-guide" >}})** - Learn how to upgrade from a previous version of a Grafana plugin, rewrite an old Angular plugin in React, or update to a newer version.
|
||||
- **[Introduction to plugin development]({{< relref "./introduction-to-plugin-development" >}})** - Learn the fundamentals of Grafana plugin development: backend development, data frames, error handling, and more.
|
||||
- **[Get started with plugins]({{< relref "./get-started-with-plugins" >}})** - Start developing Grafana plugins with the [create-plugin](https://www.npmjs.com/package/@grafana/create-plugin) tool.
|
||||
- **[Create a Grafana plugin]({{< relref "./create-a-grafana-plugin/_index.md" >}})** - If you're familiar with plugin creation, use the tutorials for creating panel plugins, data source plugins, and more to deepen your knowledge.
|
||||
- **[Publish a Grafana plugin]({{< relref "./publish-a-plugin" >}})** - Learn about publishing a plugin to the Grafana plugin catalog, including publishing criteria, packaging, and deployment.
|
||||
- **[Reference]({{< relref "metadata.md" >}})** - Description of the `plugin.json` schema and plugin metadata.
|
||||
- **[Work with legacy plugins]({{< relref "./legacy" >}})** - Learn how to upgrade from a previous version of a Grafana plugin, rewrite an old Angular plugin in React, or update to a newer version.
|
||||
- **[Migrate a plugin]({{< relref "./migration-guide" >}})** - Consult these documents if you need to work with a plugin written in deprecated technology.
|
||||
- **[Reference]({{< relref "./metadata.md" >}})** - Description of the `plugin.json` schema and plugin metadata.
|
||||
|
||||
## Go further
|
||||
|
||||
@ -49,4 +51,4 @@ Grafana Labs provides a number of best practice example plugins for different us
|
||||
|
||||
### SDK
|
||||
|
||||
Learn more about [Grafana Plugin SDK for Go]({{< relref "./backend/grafana-plugin-sdk-for-go" >}}).
|
||||
Learn more about [Grafana Plugin SDK for Go]({{< relref "./introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go" >}}).
|
||||
|
||||
@ -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,14 @@
|
||||
---
|
||||
title: Build a data source backend plugin
|
||||
summary: Create a backend for your data source plugin.
|
||||
description: Create a backend for your data source plugin.
|
||||
id: build-a-data-source-backend-plugin
|
||||
categories: ['plugins']
|
||||
tags: ['beginner']
|
||||
status: Published
|
||||
authors: ['grafana_labs']
|
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new
|
||||
weight: 75
|
||||
weight: 400
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- backend
|
||||
- backend data source
|
||||
- datasource
|
||||
---
|
||||
|
||||
## Introduction
|
||||
@ -41,7 +41,7 @@ In this tutorial, you'll:
|
||||
|
||||
## 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/).
|
||||
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]({{< relref "../../introduction-to-plugin-development/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 type:
|
||||
|
||||
@ -62,7 +62,7 @@ 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:
|
||||
Run the following to update [Grafana plugin SDK for Go]({{< relref "../../introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go" >}}) dependency to the latest minor version:
|
||||
|
||||
```bash
|
||||
go get -u github.com/grafana/grafana-plugin-sdk-go
|
||||
@ -147,7 +147,7 @@ Open `/pkg/plugin/plugin.go`. In this file you'll see that the `SampleDatasource
|
||||
|
||||
## Add authentication
|
||||
|
||||
Implementing authentication allows your plugin to access protected resources like databases or APIs. You can read more about how to [authenticate using a backend plugin in our docs](/docs/grafana/latest/developers/plugins/add-authentication-for-data-source-plugins/#authenticate-using-a-backend-plugin).
|
||||
Implementing authentication allows your plugin to access protected resources like databases or APIs. To learn more about how to authenticate using a backend plugin, refer to [our documentation]({{< relref "../extend-a-plugin/add-authentication-for-data-source-plugins/#authenticate-using-a-backend-plugin" >}}).
|
||||
|
||||
## Enable Grafana Alerting
|
||||
|
||||
@ -1,14 +1,13 @@
|
||||
---
|
||||
title: Build a data source plugin
|
||||
summary: Create a plugin to add support for your own data sources.
|
||||
description: Create a plugin to add support for your own data sources.
|
||||
id: build-a-data-source-plugin
|
||||
categories: ['plugins']
|
||||
tags: ['beginner']
|
||||
status: Published
|
||||
authors: ['grafana_labs']
|
||||
Feedback Link: https://github.com/grafana/tutorials/issues/new
|
||||
weight: 70
|
||||
weight: 300
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- data source
|
||||
- datasource
|
||||
---
|
||||
|
||||
## Introduction
|
||||
@ -38,7 +37,7 @@ In this tutorial, you'll:
|
||||
|
||||
{{< docs/shared lookup="tutorials/create-plugin.md" source="grafana" version="latest" >}}
|
||||
|
||||
To learn how to create a backend data source plugin, see [Build a data source backend plugin](/docs/grafana/latest/tutorials/build-a-data-source-backend-plugin).
|
||||
To learn how to create a backend data source plugin, see [Build a data source backend plugin]({{< relref "./build-a-data-source-backend-plugin.md" >}})
|
||||
|
||||
## Anatomy of a plugin
|
||||
|
||||
@ -311,9 +310,9 @@ Just like query editor, the form field in the config editor calls the registered
|
||||
|
||||
So far, you've generated the data returned by the data source. A more realistic use case would be to fetch data from an external API.
|
||||
|
||||
While you can use something like [axios](https://github.com/axios/axios) or the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make requests, we recommend using the [`getBackendSrv`](/docs/grafana/latest/packages_api/runtime/getbackendsrv/) function from the [grafana/runtime](/docs/grafana/latest/packages_api/runtime/) package.
|
||||
While you can use something like [axios](https://github.com/axios/axios) or the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make requests, we recommend using the [`getBackendSrv` function](https://github.com/grafana/grafana/blob/main/packages/grafana-runtime/src/services/backendSrv.ts) from the [`grafana-runtime` package](https://github.com/grafana/grafana/tree/main/packages/grafana-runtime).
|
||||
|
||||
The main advantage of `getBackendSrv` is that it proxies requests through the Grafana server rather making the request from the browser. This is strongly recommended when making authenticated requests to an external API. For more information on authenticating external requests, refer to [Add authentication for data source plugins](/docs/grafana/latest/developers/plugins/add-authentication-for-data-source-plugins/).
|
||||
The main advantage of `getBackendSrv` is that it proxies requests through the Grafana server rather making the request from the browser. This is strongly recommended when making authenticated requests to an external API. For more information on authenticating external requests, refer to [Add authentication for data source plugins]({{< relref "../extend-a-plugin/add-authentication-for-data-source-plugins.md" >}}).
|
||||
|
||||
1. Import `getBackendSrv`.
|
||||
|
||||
@ -1,5 +1,16 @@
|
||||
---
|
||||
title: Build a logs data source plugin
|
||||
description: How to build a logs data source plugin.
|
||||
aliases:
|
||||
- ../../../plugins/build-a-logs-data-source-plugin/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- logs
|
||||
- logs data source
|
||||
- datasource
|
||||
weight: 500
|
||||
---
|
||||
|
||||
# Build a logs data source plugin
|
||||
@ -8,7 +19,7 @@ Grafana data source plugins support metrics, logs, and other data types. The ste
|
||||
|
||||
## Before you begin
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/) for metrics. We recommend that you review this material before continuing.
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "./build-a-data-source-plugin" >}}) for metrics. We recommend that you review this material before continuing.
|
||||
|
||||
## Add logs support to your data source
|
||||
|
||||
@ -21,7 +32,7 @@ When these steps are done, then you can improve the user experience with one or
|
||||
|
||||
### Step 1: Enable logs support
|
||||
|
||||
Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "metadata/" >}}) file.
|
||||
Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "../../metadata.md" >}}) file.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -31,7 +42,7 @@ Tell Grafana that your data source plugin can return log data, by adding `"logs"
|
||||
|
||||
### Step 2: Construct the log data
|
||||
|
||||
As it does with metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames/" >}}).
|
||||
As it does with metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "../../introduction-to-plugin-development/data-frames.md" >}}).
|
||||
|
||||
To return log data, return a data frame with at least one time field and one text field from the data source's `query` method.
|
||||
|
||||
@ -50,7 +61,7 @@ frame.add({ time: 1589189388597, content: 'user registered' });
|
||||
frame.add({ time: 1589189406480, content: 'user logged in' });
|
||||
```
|
||||
|
||||
That's all you need to start returning log data from your data source. Go ahead and try it out in [Explore]({{< relref "../../explore/" >}}) or by adding a [Logs panel]({{< relref "../../panels-visualizations/visualizations/logs/" >}}).
|
||||
That's all you need to start returning log data from your data source. Go ahead and try it out in [Explore]({{< relref "../../../../explore" >}}) or by adding a [Logs panel]({{< relref "../../../../panels-visualizations/visualizations/logs" >}}).
|
||||
|
||||
Congratulations, you just wrote your first logs data source plugin! Next, let's look at a couple of features that can further improve the experience for the user.
|
||||
|
||||
@ -60,7 +71,7 @@ Add visualization type hints, labels, and other optional features to logs.
|
||||
|
||||
### Add a preferred visualization type hint to the data frame
|
||||
|
||||
To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore, set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries/#selecting-preferred-visualisation" >}})
|
||||
To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore, set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualization section]({{< relref "../extend-a-plugin/add-support-for-explore-queries#select-a-preferred-visualization-type" >}})
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -102,7 +113,7 @@ frame.add({ time: 1589189406480, content: 'user logged in' });
|
||||
|
||||
Add additional information about each log line by supplying more data frame fields.
|
||||
|
||||
If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Grafana treats subsequent text fields as [detected fields]({{< relref "../../explore/#labels-and-detected-fields" >}}).
|
||||
If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Grafana treats subsequent text fields as detected fields.
|
||||
|
||||
Any number of custom fields can be added to your data frame; Grafana comes with two dedicated fields: `levels` and `id`.
|
||||
|
||||
@ -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,5 +1,16 @@
|
||||
---
|
||||
title: Build a streaming data source plugin
|
||||
aliases:
|
||||
- ../../../plugins/build-a-streaming-data-source-plugin/
|
||||
description: How to build a streaming data source plugin.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- streaming
|
||||
- streaming data source
|
||||
- datasource
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Build a streaming data source plugin
|
||||
@ -8,7 +19,7 @@ In Grafana, you can set your dashboards to automatically refresh at a certain in
|
||||
|
||||
## Before you begin
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/).
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "./build-a-data-source-plugin" >}})
|
||||
|
||||
Grafana uses [RxJS](https://rxjs.dev/) to continuously send data from a data source to a panel visualization.
|
||||
|
||||
@ -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,8 +1,19 @@
|
||||
---
|
||||
title: Add authentication for data source plugins
|
||||
aliases:
|
||||
- ../../../plugins/add-authentication-for-data-source-plugins/
|
||||
description: How to add authentication for data source plugins.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- authentication
|
||||
- data source
|
||||
- datasource
|
||||
aliases:
|
||||
- ../../plugins/developing/auth-for-datasources/
|
||||
- /docs/grafana/next/developers/plugins/authentication/
|
||||
title: Add authentication for data source plugins
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# Add authentication for data source plugins
|
||||
@ -30,7 +41,7 @@ Data source plugins have two ways of storing custom configuration: `jsonData` an
|
||||
|
||||
Users with the Viewer role can access data source configuration such as the contents of `jsonData` in cleartext. If you've enabled anonymous access, anyone who can access Grafana in their browser can see the contents of `jsonData`.
|
||||
|
||||
Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions).
|
||||
Users of [Grafana Enterprise](/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](/docs/grafana/latest/enterprise/datasource_permissions).
|
||||
|
||||
> **Important:** Do not use `jsonData` with sensitive data such as password, tokens, and API keys. If you need to store sensitive information, use `secureJsonData` instead.
|
||||
|
||||
@ -115,11 +126,11 @@ Once the user has saved the configuration for a data source, the secret data sou
|
||||
|
||||
The Grafana server comes with a proxy that lets you define templates for your requests: _proxy routes_. Grafana sends the proxy route to the server, decrypts the secrets along with other configuration, and adds them to the request before sending it.
|
||||
|
||||
> **Note:** Be sure not to confuse the data source proxy with the [auth proxy]({{< relref "../../setup-grafana/configure-security/configure-authentication/auth-proxy/" >}}). The data source proxy is used to authenticate a data source, while the auth proxy is used to log into Grafana itself.
|
||||
> **Note:** Be sure not to confuse the data source proxy with the [auth proxy]({{< relref "../../../../setup-grafana/configure-security/configure-authentication/auth-proxy/index.md" >}}). The data source proxy is used to authenticate a data source, while the auth proxy is used to log into Grafana itself.
|
||||
|
||||
### Add a proxy route to your plugin
|
||||
|
||||
To forward requests through the Grafana proxy, you need to configure one or more _proxy routes_. A proxy route is a template for any outgoing request that is handled by the proxy. You can configure proxy routes in the [plugin.json](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/) file.
|
||||
To forward requests through the Grafana proxy, you need to configure one or more _proxy routes_. A proxy route is a template for any outgoing request that is handled by the proxy. You can configure proxy routes in the [plugin.json]({{< relref "../../metadata.md" >}}) file.
|
||||
|
||||
1. Add the route to `plugin.json`:
|
||||
|
||||
@ -284,7 +295,7 @@ While the data source proxy supports the most common authentication methods for
|
||||
- Proxy routes only support HTTP or HTTPS.
|
||||
- Proxy routes don't support custom token authentication.
|
||||
|
||||
If any of these limitations apply to your plugin, you need to add a [backend plugin]({{< relref "backend/" >}}). Because backend plugins run on the server, they can access decrypted secrets, which makes it easier to implement custom authentication methods.
|
||||
If any of these limitations apply to your plugin, you need to add a [backend plugin]({{< relref "../../introduction-to-plugin-development/backend" >}}). Because backend plugins run on the server, they can access decrypted secrets, which makes it easier to implement custom authentication methods.
|
||||
|
||||
The decrypted secrets are available from the `DecryptedSecureJSONData` field in the instance settings.
|
||||
|
||||
@ -302,7 +313,7 @@ func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataReque
|
||||
|
||||
## Forward OAuth identity for the logged-in user
|
||||
|
||||
If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../setup-grafana/configure-security/configure-authentication/generic-oauth/" >}}), then your data source plugin can reuse the access token for the logged-in Grafana user.
|
||||
If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../../../setup-grafana/configure-security/configure-authentication/generic-oauth" >}}), then your data source plugin can reuse the access token for the logged-in Grafana user.
|
||||
|
||||
To allow Grafana to pass the access token to the plugin, update the data source configuration and set the `jsonData.oauthPassThru` property to `true`. The [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) settings provide a toggle, the **Forward OAuth Identity** option, for this. You can also build an appropriate toggle to set `jsonData.oauthPassThru` in your data source configuration page UI.
|
||||
|
||||
@ -426,7 +437,7 @@ func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthR
|
||||
|
||||
## Forward user header for the logged-in user
|
||||
|
||||
When [send_user_header]({{< relref "../../setup-grafana/configure-grafana/_index.md#send_user_header" >}}) is enabled, Grafana passes the user header to the plugin using the `X-Grafana-User` header. You can forward this header as well as [authorization headers](#forward-oauth-identity-for-the-logged-in-user) or [configured cookies](#forward-cookies-for-the-logged-in-user).
|
||||
When `send_user_header` is enabled, Grafana passes the user header to the plugin using the `X-Grafana-User` header. You can forward this header as well as [authorization headers](#forward-oauth-identity-for-the-logged-in-user) or [configured cookies](#forward-cookies-for-the-logged-in-user).
|
||||
|
||||
**`QueryData`**
|
||||
|
||||
@ -1,5 +1,17 @@
|
||||
---
|
||||
title: Add distributed tracing for backend plugins
|
||||
aliases:
|
||||
- ../../../plugins/add-distributed-tracing-for-backend-plugins/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- distributed tracing
|
||||
- tracing
|
||||
- backend
|
||||
- back-end
|
||||
description: How to add distributed tracing for backend plugins.
|
||||
weight: 350
|
||||
---
|
||||
|
||||
# Add distributed tracing for backend plugins
|
||||
@ -22,7 +34,7 @@ tracing = true
|
||||
Grafana supports [OpenTelemetry](https://opentelemetry.io/) for distributed tracing. If Grafana is configured to use a deprecated tracing system (Jaeger or OpenTracing), then tracing is disabled in the plugin provided by the SDK and configured when calling `datasource.Manage | app.Manage`.
|
||||
|
||||
OpenTelemetry must be enabled and configured for the Grafana instance. Please refer to the [Grafana configuration documentation](
|
||||
{{< relref "../../setup-grafana/configure-grafana/#tracingopentelemetry" >}}) for more information.
|
||||
{{< relref "../../../../setup-grafana/configure-grafana#tracingopentelemetry" >}}) for more information.
|
||||
|
||||
Refer to the [OpenTelemetry Go SDK](https://pkg.go.dev/go.opentelemetry.io/otel) for in-depth documentation about all the features provided by OpenTelemetry.
|
||||
|
||||
@ -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,10 +1,20 @@
|
||||
---
|
||||
title: Add support for variables in plugins
|
||||
title: Add support for variables
|
||||
aliases:
|
||||
- ../../../plugins/add-support-for-variables/
|
||||
description: Add support for variables.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- queries
|
||||
- variables
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Add support for variables in plugins
|
||||
# Add support for variables
|
||||
|
||||
Variables are placeholders for values, and you can use them to create templated queries, and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
|
||||
Variables are placeholders for values, and you can use them to create templated queries, and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../../../dashboards/variables" >}}).
|
||||
|
||||
In this guide, you'll see how you can turn a query string like this:
|
||||
|
||||
@ -58,7 +68,7 @@ For data sources, you need to use the `getTemplateSrv`, which returns an instanc
|
||||
|
||||
## Format multi-value variables
|
||||
|
||||
When a user selects multiple values for a variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
|
||||
When a user selects multiple values for a variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../../../dashboards/variables/variable-syntax#advanced-variable-format-options" >}}).
|
||||
|
||||
A data source plugin can define the default format option when no format is specified by adding a third argument to the interpolation function.
|
||||
|
||||
@ -74,7 +84,7 @@ Now, when users write `$service`, the query looks like this:
|
||||
SELECT * FROM services WHERE id IN (admin,auth,billing)
|
||||
```
|
||||
|
||||
For more information on the available variable formats, refer to [Advanced variable format options]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
|
||||
For more information on the available variable formats, refer to [Advanced variable format options]({{< relref "../../../../dashboards/variables/variable-syntax/index.md#advanced-variable-format-options" >}}).
|
||||
|
||||
## Set a variable from your plugin
|
||||
|
||||
@ -97,7 +107,7 @@ locationService.partial({ 'var-service': 'billing' }, true);
|
||||
|
||||
## Add support for query variables to your data source
|
||||
|
||||
A [query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
|
||||
A [query variable]({{< relref "../../../../dashboards/variables/add-template-variables#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
|
||||
|
||||
Let's start by defining a query model for the variable query:
|
||||
|
||||
@ -195,4 +205,4 @@ Let's create a custom query editor to allow the user to edit the query model.
|
||||
.setVariableQueryEditor(VariableQueryEditor);
|
||||
```
|
||||
|
||||
That's it! You can now try out the plugin by adding a [query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) to your dashboard.
|
||||
That's it! You can now try out the plugin by adding a [query variable]({{< relref "../../../../dashboards/variables/add-template-variables#add-a-query-variable" >}}) to your dashboard.
|
||||
@ -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,6 +1,16 @@
|
||||
---
|
||||
title: Use extensions to add links to app plugins
|
||||
aliases:
|
||||
- ../../../plugins/extend-the-grafana-ui-with-links/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- links
|
||||
- extensions
|
||||
- app plugins
|
||||
description: Learn how to add links to the Grafana user interface from an app plugin
|
||||
weight: 760
|
||||
---
|
||||
|
||||
# Use extensions to add links to app plugins
|
||||
@ -12,7 +22,7 @@ You can use the Plugin extensions API with your Grafana app plugins to add links
|
||||
Be sure your plugin meets the following requirements before proceeding:
|
||||
|
||||
- It must be an app plugin.
|
||||
- It must be preloaded (by setting the [preload property]({{< relref "./metadata" >}}) to `true` in the `plugin.json`
|
||||
- It must be preloaded (by setting the [preload property]({{< relref "../../metadata.md" >}}) to `true` in the `plugin.json`
|
||||
- It must be installed and enabled.
|
||||
|
||||
## Available extension points within Grafana
|
||||
@ -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,6 +1,8 @@
|
||||
---
|
||||
title: Backend plugins
|
||||
aliases:
|
||||
- ../../plugins/developing/backend-plugins-guide/
|
||||
- ../../plugins/backend/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
@ -8,7 +10,7 @@ keywords:
|
||||
- plugin
|
||||
- backend-plugins
|
||||
- documentation
|
||||
title: Backend plugins
|
||||
description: Learn about the Grafana plugin system for backend development of Grafana integrations.
|
||||
---
|
||||
|
||||
# Backend plugins
|
||||
@ -27,7 +29,7 @@ Since Grafana v7.0, we have supported server-side plugins that remove this limit
|
||||
|
||||
The following examples give some common use cases for backend plugins:
|
||||
|
||||
- Enable [Grafana Alerting]({{< relref "../../../alerting/" >}}) for data sources.
|
||||
- Enable [Grafana Alerting]({{< relref "../../../../alerting" >}}) for data sources.
|
||||
- Connect to SQL database servers and other non-HTTP services that normally can't be connected to from a browser.
|
||||
- Keep state between users, for example, by query caching for data sources.
|
||||
- Use custom authentication methods and/or authorization checks that aren't supported in Grafana.
|
||||
@ -57,7 +59,7 @@ Grafana's backend plugin system exposes several key capabilities, or building bl
|
||||
|
||||
#### Query data
|
||||
|
||||
The query data capability allows a backend plugin to handle data source queries that are submitted from a [dashboard]({{< relref "../../../dashboards/" >}}), [Explore]({{< relref "../../../explore/" >}}) or [Grafana Alerting]({{< relref "../../../alerting/" >}}). The response contains [data frames]({{< relref "../data-frames/" >}}), which are used to visualize metrics, logs, and traces.
|
||||
The query data capability allows a backend plugin to handle data source queries that are submitted from a [dashboard]({{< relref "../../../../dashboards" >}}), [Explore]({{< relref "../../../../explore" >}}) or [Grafana Alerting]({{< relref "../../../../alerting" >}}). The response contains [data frames]({{< relref "../data-frames.md" >}}), which are used to visualize metrics, logs, and traces.
|
||||
|
||||
{{% admonition type="note" %}} Backend data source plugins are required to implement the query data capability.{{%
|
||||
/admonition %}}
|
||||
@ -72,7 +74,7 @@ Compared to the query data capability, where the response contains data frames,
|
||||
|
||||
Examples of use cases for implementing resources:
|
||||
|
||||
- Implement a custom data source proxy to provide certain authentication, authorization, or other requirements that are not supported in Grafana's [built-in data proxy]({{< relref "../../http_api/data_source/#data-source-proxy-calls" >}}).
|
||||
- Implement a custom data source proxy to provide certain authentication, authorization, or other requirements that are not supported in Grafana's [built-in data proxy]({{< relref "../../../http_api/data_source#data-source-proxy-calls" >}}).
|
||||
- Return data or information in a format suitable for use within a data source query editor to provide auto-complete functionality.
|
||||
- Return static resources such as images or files.
|
||||
- Send a command to a device, such as a microcontroller or IoT device.
|
||||
@ -88,10 +90,10 @@ A plugin's health check endpoint is exposed in the Grafana HTTP API and allows e
|
||||
|
||||
#### Collect metrics
|
||||
|
||||
A backend plugin can collect and return runtime, process, and custom metrics using the text-based Prometheus [exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). If you're using the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in. This SDK gives you Go runtime metrics and process metrics out of the box. You can use the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) to add custom metrics to instrument your backend plugin.
|
||||
A backend plugin can collect and return runtime, process, and custom metrics using the text-based Prometheus [exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). If you're using the [Grafana Plugin SDK for Go]({{< relref "./grafana-plugin-sdk-for-go.md" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in. This SDK gives you Go runtime metrics and process metrics out of the box. You can use the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) to add custom metrics to instrument your backend plugin.
|
||||
|
||||
The Grafana HTTP API offers an endpoint (`/api/plugins/<plugin id>/metrics`) that allows you to configure a Prometheus instance to scrape the metrics.
|
||||
|
||||
#### Streaming
|
||||
|
||||
The streaming capability allows a backend plugin to handle data source queries that are streaming. For more information, refer to [Build a streaming data source plugin]({{<relref "../build-a-streaming-data-source-plugin.md">}})
|
||||
The streaming capability allows a backend plugin to handle data source queries that are streaming. For more information, refer to [Build a streaming data source plugin]({{< relref "../../create-a-grafana-plugin/develop-a-plugin/build-a-streaming-data-source-plugin" >}}).
|
||||
@ -1,4 +1,7 @@
|
||||
---
|
||||
title: Grafana plugin SDK for Go
|
||||
aliases:
|
||||
- ../../plugins/backend/grafana-plugin-sdk-for-go/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
@ -7,18 +10,18 @@ keywords:
|
||||
- backend-plugins
|
||||
- sdk
|
||||
- documentation
|
||||
title: Grafana Plugin SDK for Go
|
||||
description: Learn about the Grafana plugin SDK for Go, a Go module with packages for implementing a Grafana backend plugin.
|
||||
---
|
||||
|
||||
# Grafana plugin SDK for Go
|
||||
|
||||
The [Grafana plugin SDK for Go](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=overview) is a [Go](https://golang.org/) module that provides a set of [packages](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=packages) that you can use to implement a backend plugin.
|
||||
|
||||
The plugin SDK provides a high-level framework with APIs, utilities, and tooling. By using the SDK, you can avoid the need to learn the details of the [plugin protocol]({{< relref "plugin-protocol/" >}}) and RPC communication protocol, so you don't have to manage either one.
|
||||
The plugin SDK provides a high-level framework with APIs, utilities, and tooling. By using the SDK, you can avoid the need to learn the details of the [plugin protocol]({{< relref "./plugin-protocol.md" >}}) and RPC communication protocol, so you don't have to manage either one.
|
||||
|
||||
## Versioning
|
||||
|
||||
The Grafana plugin Go SDK is still in development. It is based on the [plugin protocol]({{< relref "plugin-protocol/" >}}), which is versioned separately and is considered stable. However, from time to time, we might introduce breaking changes in the SDK.
|
||||
The Grafana plugin Go SDK is still in development. It is based on the [plugin protocol]({{< relref "./plugin-protocol" >}}), which is versioned separately and is considered stable. However, from time to time, we might introduce breaking changes in the SDK.
|
||||
|
||||
When we update the plugin SDK, those plugins that use an older version of the SDK should still work with Grafana. However, these older plugins may be unable to use the new features and capabilities we introduce in updated SDK versions.
|
||||
|
||||
@ -1,4 +1,7 @@
|
||||
---
|
||||
title: Plugin protocol
|
||||
aliases:
|
||||
- ../../plugins/backend/plugin-protocol/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
@ -6,7 +9,7 @@ keywords:
|
||||
- plugin
|
||||
- backend-plugins
|
||||
- documentation
|
||||
title: Plugin protocol
|
||||
description: Learn about the Grafana wire protocol used for communication between the Grafana server and backend plugins.
|
||||
---
|
||||
|
||||
# Plugin protocol
|
||||
@ -15,7 +18,7 @@ The Grafana server uses a physical wire protocol to communicate with backend plu
|
||||
|
||||
## Developing with the plugin protocol
|
||||
|
||||
{{% admonition type="caution" %}} We strongly recommend that backend plugin development not be implemented directly against the protocol. Instead, we prefer that you use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher-level APIs. {{%
|
||||
{{% admonition type="caution" %}} We strongly recommend that backend plugin development not be implemented directly against the protocol. Instead, we prefer that you use the [Grafana Plugin SDK for Go]({{< relref "./grafana-plugin-sdk-for-go" >}}) that implements this protocol and provides higher-level APIs. {{%
|
||||
/admonition %}}
|
||||
|
||||
If you choose to develop against the plugin protocol directly, you can do so using [Protocol Buffers](https://developers.google.com/protocol-buffers) (that is, protobufs) with [gRPC](https://grpc.io/).
|
||||
@ -23,7 +26,7 @@ If you choose to develop against the plugin protocol directly, you can do so usi
|
||||
Grafana's plugin protocol protobufs are available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) because Grafana itself uses parts of the SDK as a dependency.
|
||||
The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "./grafana-plugin-sdk-for-go.md" >}}) because Grafana itself uses parts of the SDK as a dependency.
|
||||
{{% /admonition %}}
|
||||
|
||||
## Versioning
|
||||
@ -1,5 +1,14 @@
|
||||
---
|
||||
title: Data frames
|
||||
aliases:
|
||||
- ../../plugins/data-frames/
|
||||
description: Learn about data frames and how they work in plugins.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- data frames
|
||||
- dataframes
|
||||
---
|
||||
|
||||
# Data frames
|
||||
@ -8,11 +17,11 @@ Grafana supports a variety of different data sources, each with its own data mod
|
||||
|
||||
The data frame structure is a concept that's borrowed from data analysis tools like the [R programming language](https://www.r-project.org) and [Pandas](https://pandas.pydata.org/).
|
||||
|
||||
> Data frames are available in Grafana 7.0+, and replaced the Time series and Table structures with a more generic data structure that can support a wider range of data types.
|
||||
> **Note:** Data frames are available in Grafana 7.0+, and replaced the Time series and Table structures with a more generic data structure that can support a wider range of data types.
|
||||
|
||||
This document gives an overview of the data frame structure, and of how data is handled within Grafana.
|
||||
|
||||
### Data frame fields
|
||||
## Data frame fields
|
||||
|
||||
A data frame is a collection of _fields_, where each field corresponds to a column. Each field, in turn, consists of a collection of values and metadata, such as the data type of those values.
|
||||
|
||||
@ -76,7 +85,7 @@ Each field has three values, and each value in a field must share the same type.
|
||||
|
||||
One restriction on data frames is that all fields in the frame must be of the same length to be a valid data frame.
|
||||
|
||||
### Field configurations
|
||||
## Field configurations
|
||||
|
||||
Each field in a data frame contains optional information about the values in the field, such as units, scaling, and so on.
|
||||
|
||||
@ -88,13 +97,13 @@ We have seen how field configs contain type information, and they also have anot
|
||||
|
||||
A data transformation is any function that accepts a data frame as input, and returns another data frame as output. By using data frames in your plugin, you get a range of transformations for free.
|
||||
|
||||
To learn more about data transformations in Grafana, refer to [Transform data](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/).
|
||||
To learn more about data transformations in Grafana, refer to [Transform data]({{< relref "../../../panels-visualizations/query-transform-data/transform-data" >}}).
|
||||
|
||||
## Data frames as time series
|
||||
|
||||
A data frame with at least one time field is considered a _time series_.
|
||||
|
||||
For more information on time series, refer to our [Introduction to time series]({{< relref "../../fundamentals/timeseries/" >}}).
|
||||
For more information on time series, refer to our [Introduction to time series]({{< relref "../../../fundamentals/timeseries" >}}).
|
||||
|
||||
### Wide format
|
||||
|
||||
@ -183,7 +192,7 @@ Dimensions: 5 fields by 2 rows
|
||||
+---------------------+------------------+------------------+------------------+------------------+
|
||||
```
|
||||
|
||||
> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility Grafana has introduced a transformation that you can use to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../panels-visualizations/query-transform-data/transform-data/#prepare-time-series" >}}).
|
||||
> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility Grafana has introduced a transformation that you can use to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../../panels-visualizations/query-transform-data/transform-data#prepare-time-series" >}}).
|
||||
|
||||
## Technical references
|
||||
|
||||
@ -1,5 +1,14 @@
|
||||
---
|
||||
title: Work with error handling
|
||||
aliases:
|
||||
- ../../plugins/error-handling/
|
||||
description: How to handle errors in plugins.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- errors
|
||||
- error handling
|
||||
---
|
||||
|
||||
# Work with error handling
|
||||
@ -44,7 +53,7 @@ try {
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Grafana displays the exception message in the UI as written, so use grammatically correct sentences. For more information, refer to the [Documentation style guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-style-guide.md).
|
||||
> **Note:** Grafana displays the exception message in the UI as written, so use grammatically correct sentences. For more information, refer to the [Documentation style guide](/docs/writers-toolkit/).
|
||||
|
||||
## Common error scenarios
|
||||
|
||||
@ -1,18 +1,20 @@
|
||||
---
|
||||
title: Work with legacy plugins
|
||||
aliases:
|
||||
- ../../plugins/development/
|
||||
- /docs/grafana/next/plugins/apps/
|
||||
- /docs/grafana/next/plugins/datasources/
|
||||
- /docs/grafana/next/plugins/developing/development/
|
||||
- /docs/grafana/next/plugins/panels/
|
||||
title: Legacy plugins
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Legacy plugins
|
||||
# Work with legacy plugins
|
||||
|
||||
> **Note:** Since Grafana 7.0, writing plugins using Angular is no longer recommended. If you're looking to build a new plugin, refer to [Plugins]({{< relref "../" >}}).
|
||||
> **Note:** Since Grafana 7.0, writing plugins using Angular is no longer recommended. If you're looking to build a new plugin, refer to our [Plugins]({{< relref "../../plugins" >}}) documentation.
|
||||
|
||||
You can extend Grafana by writing your own plugins and then share them with other users in [our plugin repository](https://grafana.com/plugins).
|
||||
You can extend Grafana by writing your own plugins and then share them with other users in [our plugin repository](/plugins/).
|
||||
|
||||
Grafana already has a strong community of contributors and plugin developers. By making it easier to develop and install plugins with resources such as this guide, we hope that the community can grow even stronger and develop new plugins that we would never think about.
|
||||
|
||||
@ -32,7 +34,7 @@ Example plugins
|
||||
|
||||
You might also be interested in the available tutorials around authoring a plugin.
|
||||
|
||||
- [Grafana Tutorials](https://grafana.com/tutorials/)
|
||||
- [Grafana Tutorials]({{< relref "../create-a-grafana-plugin/develop-a-plugin" >}})
|
||||
|
||||
## What languages?
|
||||
|
||||
@ -40,29 +42,29 @@ Since everything turns into JavaScript, it's up to you to choose which language
|
||||
|
||||
## Buildscript
|
||||
|
||||
You can use any build system that supports systemjs. All the built content should end up in a folder named `dist` and be committed to the repository. By committing the dist folder, the person who installs your plugin does not have to run any build script. All of our example plugins have a build script configured.
|
||||
You can use any build system that supports `systemjs`. All the built content should end up in a folder named `dist` and be committed to the repository. By committing the dist folder, the person who installs your plugin does not have to run any build script. All of our example plugins have a build script configured.
|
||||
|
||||
## Keep your plugin up to date
|
||||
|
||||
New versions of Grafana can sometimes cause plugins to break. See our [documentation](https://grafana.com/docs/grafana/latest/developers/plugins/migration-guide/) for changes in
|
||||
New versions of Grafana can sometimes cause plugins to break. See our [documentation]({{< relref "../migration-guide" >}}) for changes in
|
||||
Grafana that can impact your plugin.
|
||||
|
||||
## Metadata
|
||||
|
||||
See the [coding styleguide]({{< relref "style-guide/" >}}) for details on the metadata.
|
||||
See the [coding styleguide]({{< relref "./style-guide.md" >}}) for details on the metadata.
|
||||
|
||||
## module.(js|ts)
|
||||
|
||||
This is the entry point for every plugin. This is the place where you should export
|
||||
your plugin implementation. Depending on what kind of plugin you are developing you
|
||||
will be expected to export different things. You can find what's expected for [datasource]({{< relref "data-sources/" >}}), [panels]({{< relref "panels/" >}})
|
||||
and [apps]({{< relref "apps/" >}}) plugins in the documentation.
|
||||
will be expected to export different things. You can find what's expected for [datasource]({{< relref "./data-sources.md" >}}), [panels]({{< relref "./panels.md" >}})
|
||||
and [apps]({{< relref "./apps.md" >}}) plugins in the documentation.
|
||||
|
||||
The Grafana SDK is quite small so far and can be found here:
|
||||
|
||||
- [SDK file in Grafana](https://github.com/grafana/grafana/blob/main/public/app/plugins/sdk.ts)
|
||||
|
||||
The SDK contains three different plugin classes: PanelCtrl, MetricsPanelCtrl and QueryCtrl. For plugins of the panel type, the module.js file should export one of these. There are some extra classes for [data sources]({{< relref "data-sources/" >}}).
|
||||
The SDK contains three different plugin classes: PanelCtrl, MetricsPanelCtrl and QueryCtrl. For plugins of the panel type, the module.js file should export one of these. There are some extra classes for [data sources]({{< relref "./data-sources.md" >}}).
|
||||
|
||||
Example:
|
||||
|
||||
@ -91,7 +93,7 @@ export { WorldmapCtrl as PanelCtrl };
|
||||
There are three ways that you can start developing a Grafana plugin.
|
||||
|
||||
1. Set up a Grafana development environment. [(described here)](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md) and place your plugin in the `data/plugins` folder.
|
||||
1. Install Grafana and place your plugin in the plugins directory which is set in your [config file](/administration/configuration). By default this is `/var/lib/grafana/plugins` on Linux systems.
|
||||
1. Install Grafana and place your plugin in the plugins directory which is set in your config file. By default this is `/var/lib/grafana/plugins` on Linux systems.
|
||||
1. Place your plugin directory anywhere you like and specify it grafana.ini.
|
||||
|
||||
We encourage people to set up the full Grafana environment so that you can get inspiration from the rest of the Grafana code base.
|
||||
@ -110,7 +112,7 @@ There are a number of Grafana events that a plugin can hook into:
|
||||
- `data-snapshot-load` is an event triggered to load data when in snapshot mode.
|
||||
- `data-error` is used to handle errors on dashboard refresh.
|
||||
|
||||
If a panel receives data and hooks into the `data-received` event then it should handle snapshot mode too. Otherwise the panel will not work if saved as a snapshot. [Getting Plugins to work in Snapshot Mode]({{< relref "snapshot-mode/" >}}) describes how to add support for this.
|
||||
If a panel receives data and hooks into the `data-received` event then it should handle snapshot mode too. Otherwise the panel will not work if saved as a snapshot. [Getting Plugins to work in Snapshot Mode]({{< relref "./snapshot-mode" >}}) describes how to add support for this.
|
||||
|
||||
## Examples
|
||||
|
||||
@ -124,9 +126,9 @@ We have three different examples that you can fork/download to get started devel
|
||||
|
||||
## Other Articles
|
||||
|
||||
- [Getting Plugins to work in Snapshot Mode]({{< relref "snapshot-mode/" >}})
|
||||
- [Plugin Defaults and Editor Mode]({{< relref "defaults-and-editor-mode/" >}})
|
||||
- [Grafana Plugin Code Styleguide]({{< relref "style-guide/" >}})
|
||||
- [Grafana Apps]({{< relref "apps/" >}})
|
||||
- [Grafana Data Sources]({{< relref "data-sources/" >}})
|
||||
- [plugin.json Schema]({{< relref "../metadata/" >}})
|
||||
- [Getting Plugins to work in Snapshot Mode]({{< relref "./snapshot-mode.md" >}})
|
||||
- [Plugin Defaults and Editor Mode]({{< relref "./defaults-and-editor-mode.md" >}})
|
||||
- [Grafana Plugin Code Styleguide]({{< relref "./style-guide.md" >}})
|
||||
- [Grafana Apps]({{< relref "./apps.md" >}})
|
||||
- [Grafana Data Sources]({{< relref "./data-sources.md" >}})
|
||||
- [plugin.json Schema]({{< relref "../metadata.md" >}})
|
||||
|
||||
@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Legacy app plugins
|
||||
aliases:
|
||||
- ../../../plugins/developing/apps/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- documentation
|
||||
title: Legacy app plugins
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy app plugins
|
||||
|
||||
@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Legacy data source plugins
|
||||
aliases:
|
||||
- ../../../plugins/developing/datasources/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- documentation
|
||||
title: Legacy data source plugins
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy data source plugins
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Legacy defaults and editor mode
|
||||
aliases:
|
||||
- ../../../plugins/developing/defaults-and-editor-mode/
|
||||
title: Legacy defaults and editor mode
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy defaults and editor mode
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
---
|
||||
title: Legacy panel plugins
|
||||
aliases:
|
||||
- ../../../plugins/developing/panels/
|
||||
keywords:
|
||||
@ -6,7 +7,7 @@ keywords:
|
||||
- plugins
|
||||
- panel
|
||||
- documentation
|
||||
title: Legacy panel plugins
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy panel plugins
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Legacy review guidelines
|
||||
aliases:
|
||||
- ../../../plugins/developing/plugin-review-guidelines/
|
||||
title: Legacy review guidelines
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy review guidelines
|
||||
@ -10,7 +11,7 @@ The Grafana team reviews all plugins that are published on Grafana.com. There ar
|
||||
|
||||
## Metadata
|
||||
|
||||
The plugin metadata consists of a `plugin.json` file and the README.md file. The `plugin.json` file is used by Grafana to load the plugin, and the README.md file is shown in the plugins section of Grafana and the plugins section of https://grafana.com.
|
||||
The plugin metadata consists of a `plugin.json` file and the README.md file. The `plugin.json` file is used by Grafana to load the plugin, and the README.md file is shown in the [plugins catalog](/plugins).
|
||||
|
||||
### README.md
|
||||
|
||||
@ -161,7 +162,7 @@ For more information about data sources, refer to the [basic guide for data sour
|
||||
|
||||
If possible, any passwords or secrets should be saved in the `secureJsonData` blob. To encrypt sensitive data, the Grafana server's proxy feature must be used. The Grafana server has support for token authentication (OAuth) and HTTP Header authentication. If the calls have to be sent directly from the browser to a third-party API, this will not be possible and sensitive data will not be encrypted.
|
||||
|
||||
Read more here about how [authentication for data sources]({{< relref "../add-authentication-for-data-source-plugins/" >}}) works.
|
||||
Read more here about how [authentication for data sources]({{< relref "../create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins" >}}) works.
|
||||
|
||||
If using the proxy feature, the Configuration page should use the `secureJsonData` blob like this:
|
||||
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Legacy snapshot mode
|
||||
aliases:
|
||||
- ../../../plugins/developing/snapshot-mode/
|
||||
title: Legacy snapshot mode
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy snapshot mode
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Legacy code style guide
|
||||
aliases:
|
||||
- ../../../plugins/developing/code-styleguide/
|
||||
title: Legacy code style guide
|
||||
description: Deprecated guide for Angular plugin development.
|
||||
---
|
||||
|
||||
# Legacy code style guide
|
||||
@ -27,7 +28,7 @@ grafana-piechart-panel
|
||||
mtanda-histogram-panel
|
||||
```
|
||||
|
||||
For more information about the file format for `plugin.json` file, refer to [metadata]({{< relref "../metadata/" >}}).
|
||||
For more information about the file format for `plugin.json` file, refer to [metadata]({{< relref "../metadata.md" >}}).
|
||||
|
||||
Minimal plugin.json:
|
||||
|
||||
|
||||
@ -5,7 +5,10 @@ keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- documentation
|
||||
description: Reference for the plugin.json metadata file.
|
||||
title: plugin.json
|
||||
menuTitle: Reference (plugin.json)
|
||||
weight: 700
|
||||
---
|
||||
|
||||
# plugin.json
|
||||
@ -34,7 +37,7 @@ The plugin.json file is required for all plugins. When Grafana starts, it scans
|
||||
| `metrics` | boolean | No | For data source plugins, if the plugin supports metric queries. Used to enable the plugin in the panel editor. |
|
||||
| `preload` | boolean | No | Initialize plugin on startup. By default, the plugin initializes on first use. Useful for app plugins that should load without user interaction. |
|
||||
| `queryOptions` | [object](#queryoptions) | No | For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed. |
|
||||
| `routes` | [object](#routes)[] | No | For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/). |
|
||||
| `routes` | [object](#routes)[] | No | For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins]({{< relref "./create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins" >}}). |
|
||||
| `skipDataQuery` | boolean | No | For panel plugins. Hides the query editor. |
|
||||
| `state` | string | No | Marks a plugin as a pre-release. Possible values are: `alpha`, `beta`. |
|
||||
| `streaming` | boolean | No | For data source plugins, if the plugin supports streaming. Used in Explore to start live streaming. |
|
||||
@ -179,7 +182,7 @@ For data source plugins. There is a query options section in the plugin's query
|
||||
|
||||
## routes
|
||||
|
||||
For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).
|
||||
For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins]({{< relref "./create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins" >}}).
|
||||
|
||||
### Properties
|
||||
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
---
|
||||
title: Migrate a plugin
|
||||
aliases:
|
||||
- ../../plugins/developing/migration-guide
|
||||
description: A guide for migrating and updating a Grafana plugin.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migration guides
|
||||
weight: 500
|
||||
---
|
||||
|
||||
<script>
|
||||
@ -34,7 +36,7 @@ title: Migration guides
|
||||
})();
|
||||
</script>
|
||||
|
||||
# Plugin migration guide
|
||||
# Migrate a plugin
|
||||
|
||||
The following guides help you identify the steps required to update a plugin following changes between versions of Grafana.
|
||||
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
description: Guide for migrating plugins from AngularJS to React
|
||||
title: Migrate a plugin from AngularJS to React
|
||||
menuTitle: Angular to React
|
||||
description: Guide for migrating plugins from AngularJS to React.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from AngularJS to React
|
||||
menutitle: Angular to React
|
||||
weight: 1000
|
||||
---
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana version 6.x to 7.0
|
||||
menuTitle: v6.x to v7.x
|
||||
description: Guide for migrating plugins from Grafana v6.x to v7.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana version 6.x to 7.x
|
||||
menutitle: v6.x to v7.x
|
||||
weight: 2500
|
||||
---
|
||||
|
||||
@ -23,7 +23,7 @@ Plugins built using Angular still work in the near term, but we strongly encoura
|
||||
|
||||
### New data format
|
||||
|
||||
Along with the move to React, the new plugin platform introduced a new internal data format called [data frames](data-frames.md).
|
||||
Along with the move to React, the new plugin platform introduced a new internal data format called [data frames]({{< relref "../../introduction-to-plugin-development/data-frames" >}}).
|
||||
|
||||
Previously, data source plugins could send data either as time series or tables. With data frames, data sources can send any data in a table-like structure. This gives you more flexibility to visualize your data in Grafana.
|
||||
|
||||
@ -78,7 +78,7 @@ async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
|
||||
|
||||
## Troubleshoot plugin migration
|
||||
|
||||
As of Grafana 7.0, backend plugins can now be cryptographically signed to verify their origin. By default, Grafana ignores unsigned plugins. For more information, refer to [Allow unsigned plugins]({{< relref "../../../../administration/plugin-management/#allow-unsigned-plugins" >}}).
|
||||
As of Grafana 7.0, backend plugins can now be cryptographically signed to verify their origin. By default, Grafana ignores unsigned plugins. For more information, refer to [Allow unsigned plugins]({{< relref "../../../../administration/plugin-management#allow-unsigned-plugins" >}}).
|
||||
|
||||
## From version 6.5.x to 7.3.0
|
||||
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
description: Guide for migrating plugins from Grafana v7.x to v8.x
|
||||
title: Migrate plugins from Grafana version 7.x.x to 8.x.x
|
||||
menuTitle: v7.x to v8.x
|
||||
description: Guide for migrating plugins from Grafana v7.x to v8.x.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana version 7.x to 8.x
|
||||
menutitle: v7.x to v8.x
|
||||
weight: 2400
|
||||
---
|
||||
|
||||
@ -154,9 +154,9 @@ func (d *SampleDatasource) CheckHealth(_ context.Context, req *backend.CheckHeal
|
||||
|
||||
We strongly recommend that you not allow unsigned plugins in your Grafana installation. By allowing unsigned plugins, we can't guarantee the authenticity of the plugin, which could compromise the security of your Grafana installation.
|
||||
|
||||
To sign your plugin, see [Sign a plugin](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/#sign-a-plugin).
|
||||
To sign your plugin, see [Sign a plugin]({{< relref "../../publish-a-plugin/sign-a-plugin.md" >}}).
|
||||
|
||||
You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](https://grafana.com/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use the [allow_loading_unsigned_plugins]({{< relref "../../../../setup-grafana/configure-grafana/#allow_loading_unsigned_plugins" >}}) configuration setting.
|
||||
You can still run and develop an unsigned plugin by running your Grafana instance in [development mode](/docs/grafana/latest/administration/configuration/#app_mode). Alternatively, you can use the [allow_loading_unsigned_plugins]({{< relref "../../../../setup-grafana/configure-grafana#allow_loading_unsigned_plugins" >}}) configuration setting.
|
||||
|
||||
## Update react-hook-form from v6 to v7
|
||||
|
||||
@ -198,7 +198,7 @@ import { cx, css } from '@emotion/css';
|
||||
|
||||
## Update needed for app plugins using dashboards
|
||||
|
||||
To make side navigation work properly - app plugins targeting Grafana `8.+` and integrating into the side menu via [addToNav]({{< relref "../../metadata/#properties-4" >}}) property need to adjust their `plugin.json` and all dashboard json files to have a matching `uid`.
|
||||
To make side navigation work properly - app plugins targeting Grafana `8.+` and integrating into the side menu via [addToNav]({{< relref "../../metadata#properties-4" >}}) property need to adjust their `plugin.json` and all dashboard json files to have a matching `uid`.
|
||||
|
||||
**`plugin.json`**
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana version 8.3.x to 8.4.x
|
||||
menuTitle: v8.3.x to v8.4.x
|
||||
description: Guide for migrating plugins from Grafana v8.3.x to v8.4.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana version 8.3.x to 8.4.x
|
||||
menutitle: v8.3.x to v8.4.x
|
||||
weight: 2200
|
||||
---
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana version 8.x to 9.x
|
||||
menuTitle: v8.x to v9.x
|
||||
description: Guide for migrating plugins from Grafana v8.x to v9.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana version 8.x to 9.x
|
||||
menutitle: v8.x to v9.x
|
||||
weight: 2300
|
||||
---
|
||||
|
||||
@ -73,7 +73,7 @@ We have removed the deprecated `getFormStyles` function from [grafana-ui](https:
|
||||
|
||||
### `/api/ds/query` replaces `/api/tsdb/query`
|
||||
|
||||
We have removed the deprecated `/api/tsdb/query` metrics endpoint. Use [/api/ds/query]({{< relref "../../../http_api/data_source/#query-a-data-source" >}}) instead.
|
||||
We have removed the deprecated `/api/tsdb/query` metrics endpoint. Use [/api/ds/query]({{< relref "../../../http_api/data_source#query-a-data-source" >}}) instead.
|
||||
|
||||
### `selectOptionInTest` has been removed
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana version 9.1.x to 9.2.x
|
||||
menuTitle: v9.1.x to v9.2.x
|
||||
description: Guide for migrating plugins from Grafana v9.1.x to v9.2.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana 9.1.x to 9.2.x
|
||||
menutitle: v9.1.x to v9.2.x
|
||||
weight: 2100
|
||||
---
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana 9.3.x to 9.4.x
|
||||
menuTitle: v9.3.x to v9.4.x
|
||||
description: Guide for migrating plugins from Grafana v9.3.x to v9.4.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana 9.3.x to 9.4.x
|
||||
menutitle: v9.3.x to v9.4.x
|
||||
weight: 2000
|
||||
---
|
||||
|
||||
@ -144,8 +144,8 @@ useEffect(() => {
|
||||
|
||||
## Forwarded HTTP headers in the plugin SDK for Go
|
||||
|
||||
We recommended to use the `<request>.GetHTTPHeader` or `<request>.GetHTTPHeaders` methods when retrieving forwarded HTTP headers. See [Forward OAuth identity for the logged-in user]({{< relref "add-authentication-for-data-source-plugins.md#forward-oauth-identity-for-the-logged-in-user" >}}), [Forward cookies for the logged-in user
|
||||
]({{< relref "add-authentication-for-data-source-plugins.md#forward-cookies-for-the-logged-in-user" >}}) or [Forward user header for the logged-in user]({{< relref "add-authentication-for-data-source-plugins.md#forward-user-header-for-the-logged-in-user" >}}) for example usages.
|
||||
We recommended to use the `<request>.GetHTTPHeader` or `<request>.GetHTTPHeaders` methods when retrieving forwarded HTTP headers. See [Forward OAuth identity for the logged-in user]({{< relref "../../create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md#forward-oauth-identity-for-the-logged-in-user" >}}), [Forward cookies for the logged-in user
|
||||
]({{< relref "../../create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md#forward-user-header-for-the-logged-in-user" >}}) or [Forward user header for the logged-in user]({{< relref "../../create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md#forward-user-header-for-the-logged-in-user" >}}) for example usages.
|
||||
|
||||
### Technical details
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
---
|
||||
title: Migrate plugins from Grafana version 9.x to 10.x
|
||||
menuTitle: v9.x to v10.x
|
||||
description: Guide for migrating plugins from Grafana v9.x to v10.x
|
||||
keywords:
|
||||
- grafana
|
||||
@ -6,8 +8,6 @@ keywords:
|
||||
- migration
|
||||
- plugin
|
||||
- documentation
|
||||
title: Migrate plugins from Grafana 9.x to 10.x
|
||||
menutitle: v9.x to v10.x
|
||||
weight: 1900
|
||||
---
|
||||
|
||||
|
||||
@ -329,10 +329,10 @@
|
||||
},
|
||||
"routes": {
|
||||
"type": "array",
|
||||
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).",
|
||||
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](/docs/grafana/latest/developers/plugins/authentication/).",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/).",
|
||||
"description": "For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](/docs/grafana/latest/developers/plugins/authentication/).",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"path": {
|
||||
|
||||
@ -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,11 +1,20 @@
|
||||
---
|
||||
description: How to package a plugin
|
||||
title: Package a plugin
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- links
|
||||
- package
|
||||
- packaging
|
||||
- packages
|
||||
description: How to package a plugin
|
||||
weight: 100
|
||||
---
|
||||
|
||||
By packaging a plugin, you can organize the plugin code and make it ready for use in your organization.
|
||||
# Package a plugin
|
||||
|
||||
## Package a plugin for distribution
|
||||
Package a plugin to organize the plugin code and make it ready for use in your organization. Follow these steps to package the plugin in a ZIP file.
|
||||
|
||||
1. Build the plugin
|
||||
|
||||
@ -22,7 +31,7 @@ By packaging a plugin, you can organize the plugin code and make it ready for us
|
||||
|
||||
Make sure that all the binaries are executable and have a `0755` (`-rwxr-xr-x`) permission.
|
||||
|
||||
1. Sign the plugin. To learn more, refer to [Sign the plugin]({{< relref "./sign-a-plugin" >}}).
|
||||
1. Sign the plugin. To learn more, refer to [Sign a plugin]({{< relref "./sign-a-plugin" >}}).
|
||||
|
||||
1. Rename the `dist` directory to match your plugin ID, and then create a ZIP archive.
|
||||
|
||||
@ -64,4 +73,4 @@ drwxr-xr-x 0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/img/
|
||||
22 files, 92516655 bytes uncompressed, 34319591 bytes compressed: 62.9%
|
||||
```
|
||||
|
||||
When you've packaged your plugin, you can proceed to [publishing a plugin]({{< relref "publish-a-plugin.md" >}}) or [installing a packaged plugin](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-packaged-plugin).
|
||||
When you've packaged your plugin, you can proceed to [publishing a plugin]({{< relref "./publish-or-update-a-plugin.md" >}}) or [installing a packaged plugin](/docs/grafana/latest/administration/plugin-management/#install-a-packaged-plugin).
|
||||
@ -1,9 +1,17 @@
|
||||
---
|
||||
aliases:
|
||||
- share-a-plugin/
|
||||
description: Learn how to package and share your plugin.
|
||||
title: Publish or update a plugin
|
||||
aliases:
|
||||
- ../../plugins/publish-a-plugin/
|
||||
- share-a-plugin/
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- publish plugin
|
||||
- update plugin
|
||||
description: Learn how to package and share your plugin.
|
||||
type: docs
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# Publish or update a plugin
|
||||
@ -19,7 +27,7 @@ By having your plugin published on Grafana.com, more users will be able to disco
|
||||
|
||||
When you build a plugin from source, a `dist` folder is created. This folder contains the production build or _plugin assets_ for your plugin.
|
||||
|
||||
To package a plugin, refer to [Package a plugin]{{< relref "package-a-plugin.md" >}}).
|
||||
To package a plugin, refer to [Package a plugin]({{< relref "./package-a-plugin.md" >}}).
|
||||
|
||||
### Follow our guidelines
|
||||
|
||||
@ -111,11 +119,11 @@ To submit an **update** for an already published plugin:
|
||||
|
||||
### Can I distribute my plugin somewhere else other than the Grafana plugin catalog?
|
||||
|
||||
- The official method for distributing Grafana plugins is through our catalog. Alternative methods, such as installing private or development plugins on local Grafana instances, are available as per the guidelines provided in [this guide]({{< relref "../../administration/plugin-management#install-plugin-on-local-grafana" >}}).
|
||||
- The official method for distributing Grafana plugins is through our catalog. Alternative methods, such as installing private or development plugins on local Grafana instances, are available as per the guidelines provided in [this guide]({{< relref "../../../administration/plugin-management#install-plugin-on-local-grafana" >}}).
|
||||
|
||||
### Can I still use Angular for my plugin?
|
||||
|
||||
- No. We will not accept any new plugin submissions written in Angular. For more information, refer to our [Angular support deprecation documentation]({{< relref "../angular_deprecation" >}}).
|
||||
- No. We will not accept any new plugin submissions written in Angular. For more information, refer to our [Angular support deprecation documentation]({{< relref "../../angular_deprecation" >}}).
|
||||
|
||||
### Do plugin signatures expire?
|
||||
|
||||
@ -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,16 +1,27 @@
|
||||
---
|
||||
title: Sign a plugin
|
||||
aliases:
|
||||
- ../../sign-a-plugin
|
||||
- ../../sign-a-plugin/
|
||||
description: How to sign a Grafana plugin.
|
||||
keywords:
|
||||
- grafana
|
||||
- plugins
|
||||
- plugin
|
||||
- sign plugin
|
||||
- signing plugin
|
||||
weight: 400
|
||||
---
|
||||
|
||||
# Sign a plugin
|
||||
|
||||
Grafana requires all plugins to be signed so that we can verify their authenticity with [signature verification]({{< relref "../../administration/plugin-management#plugin-signatures" >}}).
|
||||
Grafana requires all plugins to be signed so that we can verify their authenticity with [signature verification]({{< relref "../../../administration/plugin-management#plugin-signatures" >}}).
|
||||
|
||||
All Grafana Labs-authored backend plugins, including Enterprise plugins, are signed. By [default]({{< relref "../../administration/plugin-management#allow-unsigned-plugins" >}}), Grafana **requires** all plugins to be signed in order for them to be loaded.
|
||||
All Grafana Labs-authored backend plugins, including Enterprise plugins, are signed. By [default]({{< relref "../../../administration/plugin-management#allow-unsigned-plugins" >}}), Grafana **requires** all plugins to be signed in order for them to be loaded.
|
||||
|
||||
Before you can sign your plugin, you need to decide whether you want to sign it as a _public_ or a _private_ plugin.
|
||||
|
||||
To make your plugin publicly available outside of your organization, sign your plugin under a _community_ or _commercial_ [signature level](#plugin-signature-levels). Public plugins are available from the [Grafana plugin catalog](https://grafana.com/plugins) and can be installed by anyone.
|
||||
To make your plugin publicly available outside of your organization, sign your plugin under a _community_ or _commercial_ [signature level](#plugin-signature-levels). Public plugins are available from the [Grafana plugin catalog](/plugins) and can be installed by anyone.
|
||||
|
||||
If you intend to only use the plugin within your organization, sign it under a _private_ [signature level](#plugin-signature-levels).
|
||||
|
||||
@ -18,19 +29,19 @@ If you intend to only use the plugin within your organization, sign it under a _
|
||||
|
||||
To verify ownership of your plugin, generate an API key that you'll use every time you need to sign a new version of your plugin.
|
||||
|
||||
1. [Create a Grafana Cloud account](https://grafana.com/signup).
|
||||
1. [Create a Grafana Cloud account](/signup).
|
||||
|
||||
1. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
|
||||
|
||||
You can find the plugin ID in the `plugin.json` file inside your plugin directory. For example, if your account slug is `acmecorp`, you need to prefix the plugin ID with `acmecorp-`.
|
||||
|
||||
1. [Create a Grafana Cloud API key](https://grafana.com/docs/grafana-cloud/reference/create-api-key/) with the **PluginPublisher** role.
|
||||
1. [Create a Grafana Cloud API key](/docs/grafana-cloud/reference/create-api-key/) with the **PluginPublisher** role.
|
||||
|
||||
## Sign a public plugin
|
||||
|
||||
Public plugins need to be reviewed by the Grafana team before you can sign them.
|
||||
|
||||
1. Submit your plugin for [review]({{< relref "publish-a-plugin/#publishing-your-plugin-for-the-first-time" >}})
|
||||
1. Submit your plugin for [review]({{< relref "./publish-or-update-a-plugin.md#publish-your-plugin" >}}).
|
||||
1. If we approve your plugin, you're granted a plugin signature level. You need this signature level to proceed.
|
||||
1. In your plugin directory, sign the plugin with the API key you just created. Grafana Sign Plugin creates a [MANIFEST.txt](#plugin-manifest) file in the `dist` directory of your plugin:
|
||||
|
||||
@ -121,6 +132,6 @@ With a **public** plugin, your plugin doesn't have a plugin signature level assi
|
||||
|
||||
### Why do I get a "Field is required: `rootUrls`" error for my private plugin?
|
||||
|
||||
With a **private** plugin, you need to add a `rootUrls` flag to the `plugin:sign` command. The `rootUrls` must match the [root_url]({{< relref "../../setup-grafana/configure-grafana/#root_url" >}}) configuration. For more information, refer to [Sign a private plugin](#sign-a-private-plugin).
|
||||
With a **private** plugin, you need to add a `rootUrls` flag to the `plugin:sign` command. The `rootUrls` must match the [root_url]({{< relref "../../../setup-grafana/configure-grafana#root_url" >}}) configuration. For more information, refer to [Sign a private plugin](#sign-a-private-plugin).
|
||||
|
||||
If you still get this error, make sure that the API key was generated by a Grafana Cloud account that matches the first part of the plugin ID.
|
||||
@ -38,7 +38,7 @@ A Grafana plugin is software that adds new capabilities to Grafana. They come in
|
||||
|
||||
The data coming into the plugin from the data source might be in many different formats (such as JSON, rows and columns, or CSV), but when it leaves the plugin and moves through the rest of the gates toward a visualization, it's always in data frames.
|
||||
|
||||
Currently, Grafana offers a diverse range of 155 data sources that you can use. The most commonly used options are already pre-installed and accessible. Before exploring other options, look for an existing data source that matches your requirements. Grafana constantly updates the list, but if you don't find a suitable data source, you can browse through the [plugin catalog](/grafana/plugins/?type=datasource) or [create a plugin](/tutorials/build-a-data-source-plugin/).
|
||||
Currently, Grafana offers a diverse range of 155 data sources that you can use. The most commonly used options are already pre-installed and accessible. Before exploring other options, look for an existing data source that matches your requirements. Grafana constantly updates the list, but if you don't find a suitable data source, you can browse through the [plugin catalog](/grafana/plugins/?type=datasource) or [create a plugin]({{< relref "../../developers/plugins/create-a-grafana-plugin" >}}).
|
||||
|
||||
## Queries
|
||||
|
||||
@ -90,8 +90,8 @@ And with the data source identified and the plugin installed, you can write your
|
||||
This component architecture is part of what makes Grafana so powerful and general. Given the data source plugin and data frame abstraction, any data source you can access can work with the same general approach.
|
||||
|
||||
{{% docs/reference %}}
|
||||
[data-frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/data-frames"
|
||||
[data-frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/data-frames"
|
||||
[data-frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
[data-frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
|
||||
[transform-data]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data/transform-data"
|
||||
[transform-data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data/transform-data"
|
||||
|
||||
@ -96,15 +96,17 @@ For more information, see the documentation on [creating alerts with multiple se
|
||||
|
||||
In the case of SQL-like data sources, more than one numeric column can be selected, with or without additional string columns to be used as dimensions. For example, `AVG(Temperature) AS AvgTemp, MAX(Temperature) AS MaxTemp`. This, if combined with multiple dimensions, can result in a lot of series. Selecting multiple values is currently only designed to be used with visualization.
|
||||
|
||||
Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series][data-frames-as-time-series].
|
||||
Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames#data-frames-as-time-series" >}}).
|
||||
|
||||
{{% docs/reference %}}
|
||||
[create-grafana-managed-rule]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/alerting/alerting-rules/create-grafana-managed-rule#single-and-multi-dimensional-rule"
|
||||
[create-grafana-managed-rule]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/alerting/alerting-rules/create-grafana-managed-rule#single-and-multi-dimensional-rule"
|
||||
|
||||
[data-frames-as-time-series]: "/docs/grafana/ -> docs/grafana/<GRAFANA VERSION>/developers/plugins/data-frames#data-frames-as-time-series"
|
||||
[data-frames-as-time-series]: "/docs/grafana-cloud/ -> docs/grafana/<GRAFANA VERSION>/developers/plugins/data-frames#data-frames-as-time-series"
|
||||
[data-frames-as-time-series]: "/docs/grafana/ -> docs/grafana/<GRAFANA VERSION>/developers/plugins//introduction-to-plugin-development/data-frames#data-frames-as-time-series"
|
||||
[data-frames-as-time-series]: "/docs/grafana-cloud/ -> docs/grafana/<GRAFANA VERSION>/developers/plugins//introduction-to-plugin-development/data-frames#data-frames-as-time-series"
|
||||
|
||||
[time-series-databases]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries#time-series-databases"
|
||||
[time-series-databases]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries#time-series-databases"
|
||||
{{% /docs/reference %}}
|
||||
|
||||
> > > > > > > main
|
||||
|
||||
@ -9,7 +9,7 @@ aliases:
|
||||
- ../panels/working-with-panels/format-standard-fields/
|
||||
keywords:
|
||||
- panel
|
||||
- dasboard
|
||||
- dashboard
|
||||
- standard
|
||||
- option
|
||||
menuTitle: Configure standard options
|
||||
@ -19,7 +19,7 @@ weight: 2
|
||||
|
||||
# Configure standard options
|
||||
|
||||
The data model used in Grafana, namely the [data frame]({{< relref "../../developers/plugins/data-frames/" >}}), is a columnar-oriented table structure that unifies both time series and table query results. Each column within this structure is called a _field_. A field can represent a single time series or table column.
|
||||
The data model used in Grafana, namely the [data frame]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames/" >}}), is a columnar-oriented table structure that unifies both time series and table query results. Each column within this structure is called a _field_. A field can represent a single time series or table column.
|
||||
|
||||
Field options allow you to change how the data is displayed in your visualizations. Options and overrides that you apply do not change the data, they change how Grafana displays the data. When you change an option, it is applied to all fields, meaning all series or columns. For example, if you change the unit to percentage, then all fields with numeric values are displayed in percentages.
|
||||
|
||||
|
||||
@ -669,7 +669,7 @@ As you can see each row in the source data becomes a separate field. Each field
|
||||
This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
|
||||
{{% /admonition %}}
|
||||
|
||||
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames]({{< relref "../../../developers/plugins/data-frames/" >}}).
|
||||
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames]({{< relref "../../../developers/plugins/introduction-to-plugin-development/data-frames/" >}}).
|
||||
|
||||
This transformation helps you resolve this issue by converting the time series data from either the wide format to the long format or the other way around.
|
||||
|
||||
|
||||
@ -111,7 +111,7 @@ These instructions assume you have already added Graphite as a data source in Gr
|
||||
|
||||
### Pull metrics from Grafana backend plugin into Prometheus
|
||||
|
||||
Any installed [backend plugin]({{< relref "../developers/plugins/backend" >}}) exposes a metrics endpoint through Grafana that you can configure Prometheus to scrape.
|
||||
Any installed [backend plugin]({{< relref "../developers/plugins/introduction-to-plugin-development/backend" >}}) exposes a metrics endpoint through Grafana that you can configure Prometheus to scrape.
|
||||
|
||||
These instructions assume you have already added Prometheus as a data source in Grafana.
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ While certain plugin types can have specific configuration options, let's look a
|
||||
|
||||
- `type` tells Grafana what type of plugin to expect. Grafana supports three types of plugins: `panel`, `datasource`, and `app`.
|
||||
- `name` is what users will see in the list of plugins. If you're creating a data source, this is typically the name of the database it connects to, such as Prometheus, PostgreSQL, or Stackdriver.
|
||||
- `id` uniquely identifies your plugin, and should start with your Grafana username, to avoid clashing with other plugins. [Sign up for a Grafana account](/signup/) to claim your username.
|
||||
- `id` uniquely identifies your plugin, and should start with your Grafana username, to avoid clashing with other plugins. [Sign up for a Grafana account](https://grafana.com/signup/) to claim your username.
|
||||
|
||||
To see all the available configuration settings for the `plugin.json`, refer to the [plugin.json Schema](/docs/grafana/latest/plugins/developing/plugin.json/).
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -34,7 +34,7 @@ Refer to [Grafana Live configuration]({{< relref "../../setup-grafana/set-up-gra
|
||||
|
||||
### Postgres, MySQL, Microsoft SQL Server data sources
|
||||
|
||||
Grafana v8.0 changes the underlying data structure to [data frames]({{< relref "../../developers/plugins/data-frames" >}}) for the Postgres, MySQL, Microsoft SQL Server data sources. As a result, a _Time series_ query result gets returned in a [wide format]({{< relref "../../developers/plugins/data-frames#wide-format" >}}). To make the visualizations work as they did before, you might have to do some manual migrations.
|
||||
Grafana v8.0 changes the underlying data structure to [data frames]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames" >}}) for the Postgres, MySQL, Microsoft SQL Server data sources. As a result, a _Time series_ query result gets returned in a [wide format]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames#wide-format" >}}). To make the visualizations work as they did before, you might have to do some manual migrations.
|
||||
|
||||
For any existing panels/visualizations using a _Time series_ query, where the time column is only needed for filtering the time range, for example, using the bar gauge or pie chart panel, we recommend that you use a _Table query_ instead and exclude the time column as a field in the response.
|
||||
Refer to this [issue comment](https://github.com/grafana/grafana/issues/35534#issuecomment-861519658) for detailed instructions and workarounds.
|
||||
|
||||
@ -72,7 +72,7 @@ For users with large dashboards or with heavy queries, being able to reuse the q
|
||||
|
||||
The [Google Sheets data source](/grafana/plugins/grafana-googlesheets-datasource) that was published a few weeks ago works really well together with the transformations feature.
|
||||
|
||||
We are also introducing a new shared data model for both time series and table data that we call [DataFrame]({{< relref "../developers/plugins/data-frames#data-frames" >}}). A DataFrame is like a table with columns but we refer to columns as fields. A time series is a DataFrame with two fields (time & value).
|
||||
We are also introducing a new shared data model for both time series and table data that we call [DataFrame]({{< relref "../developers/plugins/introduction-to-plugin-development/data-frames#data-frames" >}}). A DataFrame is like a table with columns but we refer to columns as fields. A time series is a DataFrame with two fields (time & value).
|
||||
|
||||
**Transformations shipping in 7.0**
|
||||
|
||||
@ -142,13 +142,13 @@ With [@grafana/toolkit](https://www.npmjs.com/package/@grafana/toolkit) we are d
|
||||
|
||||
### Support for backend plugins
|
||||
|
||||
Grafana now officially supports [backend plugins]({{< relref "../developers/plugins/backend" >}}) and the first type of plugin to be introduced is a backend component for data source plugins. You can optionally add a backend component to your data source plugin and implement the query logic there to automatically enable alerting in Grafana for your plugin. In the 7.0 release, we introduce the [Grafana Plugin SDK for Go]({{< relref "../developers/plugins/backend/grafana-plugin-sdk-for-go" >}}) that enables and simplifies building a backend plugin in [Go](https://golang.org/).
|
||||
Grafana now officially supports [backend plugins]({{< relref "../developers/plugins/introduction-to-plugin-development/backend" >}}) and the first type of plugin to be introduced is a backend component for data source plugins. You can optionally add a backend component to your data source plugin and implement the query logic there to automatically enable alerting in Grafana for your plugin. In the 7.0 release, we introduce the [Grafana Plugin SDK for Go]({{< relref "../developers/plugins/introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go" >}}) that enables and simplifies building a backend plugin in [Go](https://golang.org/).
|
||||
|
||||
Plugins can be monitored with the new metrics and health check capabilities. The new Resources capability means backend components can return non-time series data like JSON or static resources like images and opens up Grafana for new use cases.
|
||||
|
||||
With this release, we are deprecating the unofficial first version of backend plugins which will be removed in a future release.
|
||||
|
||||
To learn more, start with the [overview]({{< relref "../developers/plugins/backend" >}}). Next, in this [tutorial](/tutorials/build-a-data-source-backend-plugin/) you'll learn how to build a backend for a data source plugin and enable it for use with [Grafana Alerting]({{< relref "../alerting" >}}). Make sure to keep an eye out for additional documentation and tutorials that will be published after the Grafana v7.0 release.
|
||||
To learn more, start with the [overview]({{< relref "../developers/plugins/introduction-to-plugin-development/backend" >}}). Next, in this [tutorial](/tutorials/build-a-data-source-backend-plugin/) you'll learn how to build a backend for a data source plugin and enable it for use with [Grafana Alerting]({{< relref "../alerting" >}}). Make sure to keep an eye out for additional documentation and tutorials that will be published after the Grafana v7.0 release.
|
||||
|
||||
## New tutorials
|
||||
|
||||
|
||||
@ -176,7 +176,7 @@ The feature previously referred to as DataSource Start Pages or Cheat Sheets has
|
||||
|
||||
[Queries]({{< relref "../panels-visualizations/query-transform-data#manage-queries" >}}) was updated as a result of this feature.
|
||||
|
||||
For more information on adding a query editor help component to your plugin, refer to [Add a query editor help component]({{< relref "../developers/plugins/add-query-editor-help" >}}).
|
||||
For more information on adding a query editor help component to your plugin, refer to [Add a query editor help component]({{< relref "../developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-query-editor-help" >}}).
|
||||
|
||||
### Variable inspector
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user