diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 01ed327c9cf..24596686f02 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -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 diff --git a/docs/sources/administration/data-source-management/index.md b/docs/sources/administration/data-source-management/index.md index 1910a75cf40..8a15b01309e 100644 --- a/docs/sources/administration/data-source-management/index.md +++ b/docs/sources/administration/data-source-management/index.md @@ -85,7 +85,14 @@ You can assign data source permissions to users, teams, and roles which will all When query caching is enabled, Grafana temporarily stores the results of data source queries. When you or another user submit the exact same query again, the results will come back from the cache instead of from the data source (like Splunk or ServiceNow) itself. +<<<<<<< HEAD Query caching works for all backend data sources. You can enable the cache globally and configure the cache duration (also called Time to Live, or TTL). +======= +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. + +> > > > > > > f9df1f3051 (Docs: Plugins doc reorganization, part 1 (#69864)) {{% admonition type="note" %}} Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/). @@ -121,11 +128,18 @@ Query caching works for all [Enterprise data sources](/grafana/plugins/?type=dat - Postgres - Tempo +<<<<<<< HEAD Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana query caching does not improve performance. Query caching also works for all data sources that include a backend. More specifically, caching works with data sources that extend the `DataSourceWithBackend` class in the plugins SDK. -To tell if a data source works with query caching, follow the instructions below 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. +# To tell if a data source works with query caching, follow the instructions below 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/introduction-to-plugin-development/backend/#resources" >}}) for details. +{{% /admonition %}} + +> > > > > > > f9df1f3051 (Docs: Plugins doc reorganization, part 1 (#69864)) ### Enable and configure query caching diff --git a/docs/sources/administration/plugin-management/index.md b/docs/sources/administration/plugin-management/index.md index d1422630e44..2ae610d07cf 100644 --- a/docs/sources/administration/plugin-management/index.md +++ b/docs/sources/administration/plugin-management/index.md @@ -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 '' is unsigned, plugin '' 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 | | ------------------ | ------------------------------------------------------------------------------- | diff --git a/docs/sources/datasources/mssql/query-editor/index.md b/docs/sources/datasources/mssql/query-editor/index.md index a50c05944db..da09501004e 100644 --- a/docs/sources/datasources/mssql/query-editor/index.md +++ b/docs/sources/datasources/mssql/query-editor/index.md @@ -220,7 +220,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. diff --git a/docs/sources/datasources/mysql/_index.md b/docs/sources/datasources/mysql/_index.md index 7318d2c561a..f9ff4470510 100644 --- a/docs/sources/datasources/mysql/_index.md +++ b/docs/sources/datasources/mysql/_index.md @@ -275,7 +275,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. diff --git a/docs/sources/datasources/postgres/_index.md b/docs/sources/datasources/postgres/_index.md index 3f004d1ec4e..e49288d709d 100644 --- a/docs/sources/datasources/postgres/_index.md +++ b/docs/sources/datasources/postgres/_index.md @@ -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. diff --git a/docs/sources/developers/plugins/_index.md b/docs/sources/developers/plugins/_index.md index c6ead0c7599..0ae1d2b88b1 100644 --- a/docs/sources/developers/plugins/_index.md +++ b/docs/sources/developers/plugins/_index.md @@ -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" >}}). diff --git a/docs/sources/developers/plugins/create-a-grafana-plugin/_index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/_index.md index 7fb41d0d4e6..19d026c60a8 100644 --- a/docs/sources/developers/plugins/create-a-grafana-plugin/_index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/_index.md @@ -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" >}}) diff --git a/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/_index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/_index.md new file mode 100644 index 00000000000..49797918462 --- /dev/null +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/_index.md @@ -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) diff --git a/docs/sources/tutorials/build-a-data-source-backend-plugin/index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-backend-plugin.md similarity index 91% rename from docs/sources/tutorials/build-a-data-source-backend-plugin/index.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-backend-plugin.md index 88bfdd39a69..ab067335aee 100644 --- a/docs/sources/tutorials/build-a-data-source-backend-plugin/index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-backend-plugin.md @@ -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 diff --git a/docs/sources/tutorials/build-a-data-source-plugin/index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-plugin.md similarity index 95% rename from docs/sources/tutorials/build-a-data-source-plugin/index.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-plugin.md index f6a68a867ab..679aa007f14 100644 --- a/docs/sources/tutorials/build-a-data-source-plugin/index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-data-source-plugin.md @@ -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`. diff --git a/docs/sources/developers/plugins/build-a-logs-data-source-plugin.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-logs-data-source-plugin.md similarity index 82% rename from docs/sources/developers/plugins/build-a-logs-data-source-plugin.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-logs-data-source-plugin.md index 027521dbad8..f1f607c2708 100644 --- a/docs/sources/developers/plugins/build-a-logs-data-source-plugin.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-logs-data-source-plugin.md @@ -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`. diff --git a/docs/sources/tutorials/build-a-panel-plugin-with-d3/index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin-with-d3.md similarity index 96% rename from docs/sources/tutorials/build-a-panel-plugin-with-d3/index.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin-with-d3.md index 4e77ee6d93b..c728790de4a 100644 --- a/docs/sources/tutorials/build-a-panel-plugin-with-d3/index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin-with-d3.md @@ -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 diff --git a/docs/sources/tutorials/build-a-panel-plugin/index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin.md similarity index 96% rename from docs/sources/tutorials/build-a-panel-plugin/index.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin.md index cc488a8d7cd..cd441fa9788 100644 --- a/docs/sources/tutorials/build-a-panel-plugin/index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-panel-plugin.md @@ -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 diff --git a/docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-streaming-data-source-plugin.md similarity index 93% rename from docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-streaming-data-source-plugin.md index ecfe9aff478..8b1dca863c0 100644 --- a/docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-a-streaming-data-source-plugin.md @@ -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. diff --git a/docs/sources/tutorials/build-an-app-plugin/index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-an-app-plugin.md similarity index 96% rename from docs/sources/tutorials/build-an-app-plugin/index.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-an-app-plugin.md index 7a8bc2a6e86..cc36621dbed 100644 --- a/docs/sources/tutorials/build-an-app-plugin/index.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/build-an-app-plugin.md @@ -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 diff --git a/docs/sources/developers/plugins/working-with-data-frames.md b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/working-with-data-frames.md similarity index 88% rename from docs/sources/developers/plugins/working-with-data-frames.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/working-with-data-frames.md index 8a5df83c1ab..189068ccebf 100644 --- a/docs/sources/developers/plugins/working-with-data-frames.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/develop-a-plugin/working-with-data-frames.md @@ -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 diff --git a/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/_index.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/_index.md new file mode 100644 index 00000000000..b918779dcf5 --- /dev/null +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/_index.md @@ -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) diff --git a/docs/sources/developers/plugins/add-anonymous-usage-reporting.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-anonymous-usage-reporting.md similarity index 91% rename from docs/sources/developers/plugins/add-anonymous-usage-reporting.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-anonymous-usage-reporting.md index 25838afbe45..eef9f3b1694 100644 --- a/docs/sources/developers/plugins/add-anonymous-usage-reporting.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-anonymous-usage-reporting.md @@ -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 diff --git a/docs/sources/developers/plugins/add-authentication-for-data-source-plugins.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md similarity index 91% rename from docs/sources/developers/plugins/add-authentication-for-data-source-plugins.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md index 853f5b5eab2..53af41fc973 100644 --- a/docs/sources/developers/plugins/add-authentication-for-data-source-plugins.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md @@ -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`** diff --git a/docs/sources/developers/plugins/add-distributed-tracing-for-backend-plugins.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-distributed-tracing-for-backend-plugins.md similarity index 93% rename from docs/sources/developers/plugins/add-distributed-tracing-for-backend-plugins.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-distributed-tracing-for-backend-plugins.md index 9a3668c9fee..506fe3e8891 100644 --- a/docs/sources/developers/plugins/add-distributed-tracing-for-backend-plugins.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-distributed-tracing-for-backend-plugins.md @@ -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. diff --git a/docs/sources/developers/plugins/add-query-editor-help.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-query-editor-help.md similarity index 90% rename from docs/sources/developers/plugins/add-query-editor-help.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-query-editor-help.md index 815240966a4..a5bfe2f3dd0 100644 --- a/docs/sources/developers/plugins/add-query-editor-help.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-query-editor-help.md @@ -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 diff --git a/docs/sources/developers/plugins/add-support-for-annotations.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-annotations.md similarity index 53% rename from docs/sources/developers/plugins/add-support-for-annotations.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-annotations.md index 1d52491878a..85c6a24daa9 100644 --- a/docs/sources/developers/plugins/add-support-for-annotations.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-annotations.md @@ -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`:** diff --git a/docs/sources/developers/plugins/add-support-for-explore-queries.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-explore-queries.md similarity index 83% rename from docs/sources/developers/plugins/add-support-for-explore-queries.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-explore-queries.md index a19da47b388..a54e20e61f3 100644 --- a/docs/sources/developers/plugins/add-support-for-explore-queries.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-explore-queries.md @@ -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. diff --git a/docs/sources/developers/plugins/add-support-for-variables.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-variables.md similarity index 86% rename from docs/sources/developers/plugins/add-support-for-variables.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-variables.md index 2cf6e8dcfa9..502052307ec 100644 --- a/docs/sources/developers/plugins/add-support-for-variables.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/add-support-for-variables.md @@ -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. diff --git a/docs/sources/developers/plugins/cross-plugin-linking.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/cross-plugin-linking.md similarity index 94% rename from docs/sources/developers/plugins/cross-plugin-linking.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/cross-plugin-linking.md index 1772e2816e6..5a71acff2e8 100644 --- a/docs/sources/developers/plugins/cross-plugin-linking.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/cross-plugin-linking.md @@ -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 diff --git a/docs/sources/developers/plugins/custom-panel-option-editors.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/custom-panel-option-editors.md similarity index 93% rename from docs/sources/developers/plugins/custom-panel-option-editors.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/custom-panel-option-editors.md index 8d6de45c9cd..9175397c3b1 100644 --- a/docs/sources/developers/plugins/custom-panel-option-editors.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/custom-panel-option-editors.md @@ -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 diff --git a/docs/sources/developers/plugins/extend-the-grafana-ui-with-links.md b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/extend-the-grafana-ui-with-links.md similarity index 96% rename from docs/sources/developers/plugins/extend-the-grafana-ui-with-links.md rename to docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/extend-the-grafana-ui-with-links.md index 83a8775af1b..ec772e50ce1 100644 --- a/docs/sources/developers/plugins/extend-the-grafana-ui-with-links.md +++ b/docs/sources/developers/plugins/create-a-grafana-plugin/extend-a-plugin/extend-the-grafana-ui-with-links.md @@ -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 diff --git a/docs/sources/developers/plugins/get-started-with-plugins/_index.md b/docs/sources/developers/plugins/get-started-with-plugins/_index.md index b12c6afde35..40eb24f608f 100644 --- a/docs/sources/developers/plugins/get-started-with-plugins/_index.md +++ b/docs/sources/developers/plugins/get-started-with-plugins/_index.md @@ -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) diff --git a/docs/sources/developers/plugins/development-with-local-grafana.md b/docs/sources/developers/plugins/get-started-with-plugins/development-with-local-grafana.md similarity index 96% rename from docs/sources/developers/plugins/development-with-local-grafana.md rename to docs/sources/developers/plugins/get-started-with-plugins/development-with-local-grafana.md index 08d1f46dbc6..f18af1362ad 100644 --- a/docs/sources/developers/plugins/development-with-local-grafana.md +++ b/docs/sources/developers/plugins/get-started-with-plugins/development-with-local-grafana.md @@ -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 diff --git a/docs/sources/developers/plugins/introduction-to-plugin-development/_index.md b/docs/sources/developers/plugins/introduction-to-plugin-development/_index.md index 02feda720d8..16727e205a9 100644 --- a/docs/sources/developers/plugins/introduction-to-plugin-development/_index.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/_index.md @@ -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" >}}) diff --git a/docs/sources/developers/plugins/backend/_index.md b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/_index.md similarity index 81% rename from docs/sources/developers/plugins/backend/_index.md rename to docs/sources/developers/plugins/introduction-to-plugin-development/backend/_index.md index 44c228f7ca5..407a0571719 100644 --- a/docs/sources/developers/plugins/backend/_index.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/_index.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//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]({{}}) +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" >}}). diff --git a/docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go.md similarity index 65% rename from docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md rename to docs/sources/developers/plugins/introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go.md index e26860ff2bd..b1717677c4d 100644 --- a/docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/grafana-plugin-sdk-for-go.md @@ -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. diff --git a/docs/sources/developers/plugins/backend/plugin-protocol.md b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/plugin-protocol.md similarity index 85% rename from docs/sources/developers/plugins/backend/plugin-protocol.md rename to docs/sources/developers/plugins/introduction-to-plugin-development/backend/plugin-protocol.md index 822a9234892..1bb45efd86a 100644 --- a/docs/sources/developers/plugins/backend/plugin-protocol.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/backend/plugin-protocol.md @@ -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 diff --git a/docs/sources/developers/plugins/data-frames.md b/docs/sources/developers/plugins/introduction-to-plugin-development/data-frames.md similarity index 92% rename from docs/sources/developers/plugins/data-frames.md rename to docs/sources/developers/plugins/introduction-to-plugin-development/data-frames.md index de02509e221..e91acc82e09 100644 --- a/docs/sources/developers/plugins/data-frames.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/data-frames.md @@ -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 diff --git a/docs/sources/developers/plugins/error-handling.md b/docs/sources/developers/plugins/introduction-to-plugin-development/error-handling.md similarity index 89% rename from docs/sources/developers/plugins/error-handling.md rename to docs/sources/developers/plugins/introduction-to-plugin-development/error-handling.md index 778952f0d3d..ef9268a6c39 100644 --- a/docs/sources/developers/plugins/error-handling.md +++ b/docs/sources/developers/plugins/introduction-to-plugin-development/error-handling.md @@ -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 diff --git a/docs/sources/developers/plugins/legacy/_index.md b/docs/sources/developers/plugins/legacy/_index.md index bbd74cdce84..9dd7ed7f98e 100644 --- a/docs/sources/developers/plugins/legacy/_index.md +++ b/docs/sources/developers/plugins/legacy/_index.md @@ -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" >}}) diff --git a/docs/sources/developers/plugins/legacy/apps.md b/docs/sources/developers/plugins/legacy/apps.md index 15efb55b064..44b8aec0cb5 100644 --- a/docs/sources/developers/plugins/legacy/apps.md +++ b/docs/sources/developers/plugins/legacy/apps.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 diff --git a/docs/sources/developers/plugins/legacy/data-sources.md b/docs/sources/developers/plugins/legacy/data-sources.md index c4e27ef7f0a..137aa1c6f50 100644 --- a/docs/sources/developers/plugins/legacy/data-sources.md +++ b/docs/sources/developers/plugins/legacy/data-sources.md @@ -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 diff --git a/docs/sources/developers/plugins/legacy/defaults-and-editor-mode.md b/docs/sources/developers/plugins/legacy/defaults-and-editor-mode.md index b1634470b37..6bcb503b0f1 100644 --- a/docs/sources/developers/plugins/legacy/defaults-and-editor-mode.md +++ b/docs/sources/developers/plugins/legacy/defaults-and-editor-mode.md @@ -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 diff --git a/docs/sources/developers/plugins/legacy/panels.md b/docs/sources/developers/plugins/legacy/panels.md index 4149bb2fe25..5dcd161a28a 100644 --- a/docs/sources/developers/plugins/legacy/panels.md +++ b/docs/sources/developers/plugins/legacy/panels.md @@ -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 diff --git a/docs/sources/developers/plugins/legacy/review-guidelines.md b/docs/sources/developers/plugins/legacy/review-guidelines.md index dedc5793ea3..b17d02c5b63 100644 --- a/docs/sources/developers/plugins/legacy/review-guidelines.md +++ b/docs/sources/developers/plugins/legacy/review-guidelines.md @@ -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: diff --git a/docs/sources/developers/plugins/legacy/snapshot-mode.md b/docs/sources/developers/plugins/legacy/snapshot-mode.md index 510b9bc4c03..b2901c513cf 100644 --- a/docs/sources/developers/plugins/legacy/snapshot-mode.md +++ b/docs/sources/developers/plugins/legacy/snapshot-mode.md @@ -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 diff --git a/docs/sources/developers/plugins/legacy/style-guide.md b/docs/sources/developers/plugins/legacy/style-guide.md index 590f5487153..18227ac4d30 100644 --- a/docs/sources/developers/plugins/legacy/style-guide.md +++ b/docs/sources/developers/plugins/legacy/style-guide.md @@ -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: diff --git a/docs/sources/developers/plugins/metadata.md b/docs/sources/developers/plugins/metadata.md index 9a6628e4173..6a41947d786 100644 --- a/docs/sources/developers/plugins/metadata.md +++ b/docs/sources/developers/plugins/metadata.md @@ -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 diff --git a/docs/sources/developers/plugins/migration-guide/_index.md b/docs/sources/developers/plugins/migration-guide/_index.md index 1c00ce656ce..b134e362279 100644 --- a/docs/sources/developers/plugins/migration-guide/_index.md +++ b/docs/sources/developers/plugins/migration-guide/_index.md @@ -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 --- -# 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. diff --git a/docs/sources/developers/plugins/migration-guide/angular-react/_index.md b/docs/sources/developers/plugins/migration-guide/angular-react/_index.md index 79d3e052dc1..9c44328ffb0 100644 --- a/docs/sources/developers/plugins/migration-guide/angular-react/_index.md +++ b/docs/sources/developers/plugins/migration-guide/angular-react/_index.md @@ -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 --- diff --git a/docs/sources/developers/plugins/migration-guide/v6.x-v7.x/_index.md b/docs/sources/developers/plugins/migration-guide/v6.x-v7.x/_index.md index 69c1a52aeea..493675d3fec 100644 --- a/docs/sources/developers/plugins/migration-guide/v6.x-v7.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v6.x-v7.x/_index.md @@ -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): Promise { ## 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 diff --git a/docs/sources/developers/plugins/migration-guide/v7.x-v8.x/_index.md b/docs/sources/developers/plugins/migration-guide/v7.x-v8.x/_index.md index 8ee49beb1b4..fcac642a412 100644 --- a/docs/sources/developers/plugins/migration-guide/v7.x-v8.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v7.x-v8.x/_index.md @@ -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`** diff --git a/docs/sources/developers/plugins/migration-guide/v8.3.x-8.4.x/_index.md b/docs/sources/developers/plugins/migration-guide/v8.3.x-8.4.x/_index.md index c741bbaf9cb..94b4d669660 100644 --- a/docs/sources/developers/plugins/migration-guide/v8.3.x-8.4.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v8.3.x-8.4.x/_index.md @@ -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 --- diff --git a/docs/sources/developers/plugins/migration-guide/v8.x-v9.x/_index.md b/docs/sources/developers/plugins/migration-guide/v8.x-v9.x/_index.md index f5c50eb3d88..a608c5091ec 100644 --- a/docs/sources/developers/plugins/migration-guide/v8.x-v9.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v8.x-v9.x/_index.md @@ -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 diff --git a/docs/sources/developers/plugins/migration-guide/v9.1.x-v9.2.x/_index.md b/docs/sources/developers/plugins/migration-guide/v9.1.x-v9.2.x/_index.md index e9bc91902b1..1b0cf590db0 100644 --- a/docs/sources/developers/plugins/migration-guide/v9.1.x-v9.2.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v9.1.x-v9.2.x/_index.md @@ -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 --- diff --git a/docs/sources/developers/plugins/migration-guide/v9.3.x-9.4.x/_index.md b/docs/sources/developers/plugins/migration-guide/v9.3.x-9.4.x/_index.md index 7c856dd5921..f4df05fd026 100644 --- a/docs/sources/developers/plugins/migration-guide/v9.3.x-9.4.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v9.3.x-9.4.x/_index.md @@ -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 `.GetHTTPHeader` or `.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 `.GetHTTPHeader` or `.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 diff --git a/docs/sources/developers/plugins/migration-guide/v9.x-v10.x/_index.md b/docs/sources/developers/plugins/migration-guide/v9.x-v10.x/_index.md index c7349ba8c02..1b71b4fe378 100644 --- a/docs/sources/developers/plugins/migration-guide/v9.x-v10.x/_index.md +++ b/docs/sources/developers/plugins/migration-guide/v9.x-v10.x/_index.md @@ -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 --- diff --git a/docs/sources/developers/plugins/plugin.schema.json b/docs/sources/developers/plugins/plugin.schema.json index b90c6addc15..bff5004d623 100644 --- a/docs/sources/developers/plugins/plugin.schema.json +++ b/docs/sources/developers/plugins/plugin.schema.json @@ -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": { diff --git a/docs/sources/developers/plugins/publish-a-plugin/_index.md b/docs/sources/developers/plugins/publish-a-plugin/_index.md index 1566e5eef76..9d227e66064 100644 --- a/docs/sources/developers/plugins/publish-a-plugin/_index.md +++ b/docs/sources/developers/plugins/publish-a-plugin/_index.md @@ -1,11 +1,21 @@ --- -description: Topics related to plugin publishing -title: Publish a plugin +title: Publish or sign a plugin +menuTitle: Publish a plugin +keywords: + - grafana + - plugins + - plugin + - publish + - publishing +description: An index to documentation related to plugin publishing and signing. +weight: 400 --- -# Publish a plugin +# Publish or sign a plugin -This section contains topics related to publishing Grafana plugins. +This section contains topics related to publishing and signing Grafana plugins. -- [Publishing and signing criteria]({{< relref "../publishing-and-signing-criteria.md">}}) -- [Publish or update a plugin]({{< relref "../publish-or-update-a-plugin.md">}}) +- [Package a plugin]({{< relref "./package-a-plugin.md" >}}) +- [Publishing and signing criteria]({{< relref "./publishing-and-signing-criteria.md" >}}) +- [Publish or update a plugin]({{< relref "./publish-or-update-a-plugin.md" >}}) +- [Sign a plugin]({{< relref "./sign-a-plugin.md" >}}) diff --git a/docs/sources/developers/plugins/package-a-plugin.md b/docs/sources/developers/plugins/publish-a-plugin/package-a-plugin.md similarity index 84% rename from docs/sources/developers/plugins/package-a-plugin.md rename to docs/sources/developers/plugins/publish-a-plugin/package-a-plugin.md index 6fff59f4c20..6c07ee181be 100644 --- a/docs/sources/developers/plugins/package-a-plugin.md +++ b/docs/sources/developers/plugins/publish-a-plugin/package-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). diff --git a/docs/sources/developers/plugins/publish-or-update-a-plugin.md b/docs/sources/developers/plugins/publish-a-plugin/publish-or-update-a-plugin.md similarity index 94% rename from docs/sources/developers/plugins/publish-or-update-a-plugin.md rename to docs/sources/developers/plugins/publish-a-plugin/publish-or-update-a-plugin.md index 03d1436be1a..53b204f10e9 100644 --- a/docs/sources/developers/plugins/publish-or-update-a-plugin.md +++ b/docs/sources/developers/plugins/publish-a-plugin/publish-or-update-a-plugin.md @@ -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? diff --git a/docs/sources/developers/plugins/publishing-and-signing-criteria.md b/docs/sources/developers/plugins/publish-a-plugin/publishing-and-signing-criteria.md similarity index 65% rename from docs/sources/developers/plugins/publishing-and-signing-criteria.md rename to docs/sources/developers/plugins/publish-a-plugin/publishing-and-signing-criteria.md index 38325a0d31f..b4beb276509 100644 --- a/docs/sources/developers/plugins/publishing-and-signing-criteria.md +++ b/docs/sources/developers/plugins/publish-a-plugin/publishing-and-signing-criteria.md @@ -1,10 +1,22 @@ --- title: Plugin publishing and signing criteria +description: Acceptance criteria for publishing and signing Grafana plugins. +aliases: + - ../../plugins/publishing-and-signing-criteria/ +keywords: + - grafana + - plugins + - plugin + - publish plugin + - sign plugin + - publishing + - signing +weight: 200 --- # Plugin publishing and signing criteria -Grafana plugins must adhere to the Grafana Labs [Plugin Policy](https://grafana.com/legal/plugins/). Our review process for publishing and signing will examine your compliance with this policy. +Grafana plugins must adhere to the Grafana Labs [Plugin Policy](/legal/plugins/). Our review process for publishing and signing will examine your compliance with this policy. > **Important:** Grafana Labs reserves the right to decline or remove any plugin at its discretion. Failure to comply with publishing and signing criteria may result in immediate removal from the Grafana plugin catalog. diff --git a/docs/sources/developers/plugins/sign-a-plugin.md b/docs/sources/developers/plugins/publish-a-plugin/sign-a-plugin.md similarity index 88% rename from docs/sources/developers/plugins/sign-a-plugin.md rename to docs/sources/developers/plugins/publish-a-plugin/sign-a-plugin.md index 0797650bab2..66db8b3c838 100644 --- a/docs/sources/developers/plugins/sign-a-plugin.md +++ b/docs/sources/developers/plugins/publish-a-plugin/sign-a-plugin.md @@ -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. diff --git a/docs/sources/fundamentals/dashboards-overview/index.md b/docs/sources/fundamentals/dashboards-overview/index.md index 61efa0040bb..0ff6b70d634 100644 --- a/docs/sources/fundamentals/dashboards-overview/index.md +++ b/docs/sources/fundamentals/dashboards-overview/index.md @@ -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//developers/plugins/data-frames" -[data-frames]: "/docs/grafana-cloud/ -> /docs/grafana//developers/plugins/data-frames" +[data-frames]: "/docs/grafana/ -> /docs/grafana//developers/plugins/introduction-to-plugin-development/data-frames" +[data-frames]: "/docs/grafana-cloud/ -> /docs/grafana//developers/plugins/introduction-to-plugin-development/data-frames" [transform-data]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data/transform-data" [transform-data]: "/docs/grafana-cloud/ -> /docs/grafana//panels-visualizations/query-transform-data/transform-data" diff --git a/docs/sources/fundamentals/timeseries-dimensions/index.md b/docs/sources/fundamentals/timeseries-dimensions/index.md index 865d8df30e7..35c4a5438d7 100644 --- a/docs/sources/fundamentals/timeseries-dimensions/index.md +++ b/docs/sources/fundamentals/timeseries-dimensions/index.md @@ -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//alerting/alerting-rules/create-grafana-managed-rule#single-and-multi-dimensional-rule" [create-grafana-managed-rule]: "/docs/grafana-cloud/ -> /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule#single-and-multi-dimensional-rule" -[data-frames-as-time-series]: "/docs/grafana/ -> docs/grafana//developers/plugins/data-frames#data-frames-as-time-series" -[data-frames-as-time-series]: "/docs/grafana-cloud/ -> docs/grafana//developers/plugins/data-frames#data-frames-as-time-series" +[data-frames-as-time-series]: "/docs/grafana/ -> docs/grafana//developers/plugins//introduction-to-plugin-development/data-frames#data-frames-as-time-series" +[data-frames-as-time-series]: "/docs/grafana-cloud/ -> docs/grafana//developers/plugins//introduction-to-plugin-development/data-frames#data-frames-as-time-series" [time-series-databases]: "/docs/grafana/ -> /docs/grafana//fundamentals/timeseries#time-series-databases" [time-series-databases]: "/docs/grafana-cloud/ -> /docs/grafana//fundamentals/timeseries#time-series-databases" {{% /docs/reference %}} + +> > > > > > > main diff --git a/docs/sources/panels-visualizations/configure-standard-options/index.md b/docs/sources/panels-visualizations/configure-standard-options/index.md index 35315aff6dc..6d5d81b6395 100644 --- a/docs/sources/panels-visualizations/configure-standard-options/index.md +++ b/docs/sources/panels-visualizations/configure-standard-options/index.md @@ -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. diff --git a/docs/sources/panels-visualizations/query-transform-data/transform-data/index.md b/docs/sources/panels-visualizations/query-transform-data/transform-data/index.md index a685a57a756..5089d78e76d 100644 --- a/docs/sources/panels-visualizations/query-transform-data/transform-data/index.md +++ b/docs/sources/panels-visualizations/query-transform-data/transform-data/index.md @@ -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. diff --git a/docs/sources/setup-grafana/set-up-grafana-monitoring.md b/docs/sources/setup-grafana/set-up-grafana-monitoring.md index c16a91c267f..690c3db996e 100644 --- a/docs/sources/setup-grafana/set-up-grafana-monitoring.md +++ b/docs/sources/setup-grafana/set-up-grafana-monitoring.md @@ -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. diff --git a/docs/sources/shared/tutorials/plugin-anatomy.md b/docs/sources/shared/tutorials/plugin-anatomy.md index ba297e20637..18f148d4696 100644 --- a/docs/sources/shared/tutorials/plugin-anatomy.md +++ b/docs/sources/shared/tutorials/plugin-anatomy.md @@ -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/). diff --git a/docs/sources/tutorials/build-a-streaming-data-source-plugin/index.md b/docs/sources/tutorials/build-a-streaming-data-source-plugin/index.md deleted file mode 100644 index 7260287ca25..00000000000 --- a/docs/sources/tutorials/build-a-streaming-data-source-plugin/index.md +++ /dev/null @@ -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//`. - -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//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. diff --git a/docs/sources/upgrade-guide/upgrade-v8.0/index.md b/docs/sources/upgrade-guide/upgrade-v8.0/index.md index b01636e54e3..3dba540e715 100644 --- a/docs/sources/upgrade-guide/upgrade-v8.0/index.md +++ b/docs/sources/upgrade-guide/upgrade-v8.0/index.md @@ -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. diff --git a/docs/sources/whatsnew/whats-new-in-v7-0.md b/docs/sources/whatsnew/whats-new-in-v7-0.md index 450c64036d2..40e44864cd8 100644 --- a/docs/sources/whatsnew/whats-new-in-v7-0.md +++ b/docs/sources/whatsnew/whats-new-in-v7-0.md @@ -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 diff --git a/docs/sources/whatsnew/whats-new-in-v7-4.md b/docs/sources/whatsnew/whats-new-in-v7-4.md index ca5498473bb..35eefb4a08a 100644 --- a/docs/sources/whatsnew/whats-new-in-v7-4.md +++ b/docs/sources/whatsnew/whats-new-in-v7-4.md @@ -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