mirror of
https://github.com/grafana/grafana.git
synced 2025-09-17 05:03:03 +08:00
Docs: Setup refactor (#49739)
* builds out refactored setup topics * Automatically fix some relrefs with mv-manager Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Use refs for tutorials content which is outside of this repository Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Manually fix complicated relrefs Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * consolidates team sync and db encryption topics * Fix relrefs Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * updates setup index file * Convert TOML to YAML Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Add current alias for new alerting content Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Add current aliases to new setup-grafana and configure-security pages Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update docs/sources/setup-grafana/configure-grafana/_index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * moves saml docs, updates order in TOC * Manually fix relrefs Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * added usage insights topics, adjusted weights * corrected relrefs * Fix relrefs broken in rebase Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Torkel Ödegaard <torkel@grafana.com>
This commit is contained in:
Christopher Moyer
committed by
GitHub
GitHub
parent
104c4a7630
commit
a568d421f8
@ -8,13 +8,13 @@ weight: 200
|
||||
|
||||
# Build a plugin
|
||||
|
||||
For more information on the types of plugins you can build, refer to the [Plugin Overview]({{< relref "../../plugins/_index.md" >}}).
|
||||
For more information on the types of plugins you can build, refer to the [Plugin Overview]({{< relref "../../plugins/" >}}).
|
||||
|
||||
## Get started
|
||||
|
||||
The easiest way to start developing Grafana plugins is to use the [Grafana Toolkit](https://www.npmjs.com/package/@grafana/toolkit).
|
||||
|
||||
Open the terminal, and run the following command in your [plugin directory]({{< relref "../../administration/configuration.md#plugins" >}}):
|
||||
Open the terminal, and run the following command in your [plugin directory]({{< relref "../../setup-grafana/configure-grafana/#plugins" >}}):
|
||||
|
||||
```bash
|
||||
npx @grafana/toolkit plugin:create my-grafana-plugin
|
||||
@ -24,8 +24,8 @@ npx @grafana/toolkit plugin:create my-grafana-plugin
|
||||
|
||||
If you want a more guided introduction to plugin development, check out our tutorials:
|
||||
|
||||
- [Build a panel plugin]({{< relref "tutorials/build-a-panel-plugin.md" >}})
|
||||
- [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}})
|
||||
- [Build a panel plugin]({{< ref "/tutorials/build-a-panel-plugin/" >}})
|
||||
- [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}})
|
||||
|
||||
## Go further
|
||||
|
||||
@ -35,34 +35,34 @@ Learn more about specific areas of plugin development.
|
||||
|
||||
If you're looking to build your first plugin, check out these introductory tutorials:
|
||||
|
||||
- [Build a panel plugin]({{< relref "tutorials/build-a-panel-plugin.md" >}})
|
||||
- [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}})
|
||||
- [Build a data source backend plugin]({{< relref "tutorials/build-a-data-source-backend-plugin.md" >}})
|
||||
- [Build a panel plugin]({{< ref "/tutorials/build-a-panel-plugin/" >}})
|
||||
- [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}})
|
||||
- [Build a data source backend plugin]({{< ref "/tutorials/build-a-data-source-backend-plugin/" >}})
|
||||
|
||||
Ready to learn more? Check out our other tutorials:
|
||||
|
||||
- [Build a panel plugin with D3.js]({{< relref "tutorials/build-a-panel-plugin-with-d3.md" >}})
|
||||
- [Build a panel plugin with D3.js]({{< ref "/tutorials/build-a-panel-plugin-with-d3/" >}})
|
||||
|
||||
### Guides
|
||||
|
||||
Improve an existing plugin with one of our guides:
|
||||
|
||||
- [Add authentication for data source plugins]({{< relref "add-authentication-for-data-source-plugins/" >}})
|
||||
- [Add support for annotations]({{< relref "add-support-for-annotations.md" >}})
|
||||
- [Add support for Explore queries]({{< relref "add-support-for-explore-queries.md" >}})
|
||||
- [Add support for variables]({{< relref "add-support-for-variables.md" >}})
|
||||
- [Add a query editor help component]({{< relref "add-query-editor-help.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" >}})
|
||||
- [Error handling]({{< relref "error-handling.md" >}})
|
||||
- [Working with data frames]({{< relref "working-with-data-frames.md" >}})
|
||||
- [Development with local Grafana]({{< relref "development-with-local-grafana.md" >}})
|
||||
- [Add support for annotations]({{< relref "add-support-for-annotations/" >}})
|
||||
- [Add support for Explore queries]({{< relref "add-support-for-explore-queries/" >}})
|
||||
- [Add support for variables]({{< relref "add-support-for-variables/" >}})
|
||||
- [Add a query editor help component]({{< relref "add-query-editor-help/" >}})
|
||||
- [Build a logs data source plugin]({{< relref "build-a-logs-data-source-plugin/" >}})
|
||||
- [Build a streaming data source plugin]({{< relref "build-a-streaming-data-source-plugin/" >}})
|
||||
- [Error handling]({{< relref "error-handling/" >}})
|
||||
- [Working with data frames]({{< relref "working-with-data-frames/" >}})
|
||||
- [Development with local Grafana]({{< relref "development-with-local-grafana/" >}})
|
||||
|
||||
### Concepts
|
||||
|
||||
Deepen your knowledge through a series of high-level overviews of plugin concepts:
|
||||
|
||||
- [Data frames]({{< relref "data-frames.md" >}})
|
||||
- [Data frames]({{< relref "data-frames/" >}})
|
||||
|
||||
### UI library
|
||||
|
||||
@ -78,7 +78,7 @@ Learn more about Grafana options and packages.
|
||||
|
||||
#### Metadata
|
||||
|
||||
- [Plugin metadata]({{< relref "metadata.md" >}})
|
||||
- [Plugin metadata]({{< relref "metadata/" >}})
|
||||
|
||||
#### Typescript
|
||||
|
||||
|
||||
@ -107,7 +107,7 @@ Once the user has saved the configuration for a data source, any secret data sou
|
||||
|
||||
The Grafana server comes with a proxy that lets you define templates for your requests. We call them _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 off.
|
||||
|
||||
> **Note:** Be sure not to confuse the data source proxy with the [auth proxy]({{< relref "../../auth/auth-proxy.md" >}}). 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/" >}}). 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
|
||||
|
||||
@ -268,7 +268,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/_index.md" >}}). Since 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 "backend/" >}}). Since 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.
|
||||
|
||||
@ -286,7 +286,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 "../../auth/generic-oauth.md" >}}), 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/" >}}), 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) provides 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.
|
||||
|
||||
|
||||
@ -6,9 +6,9 @@ title: Add support for annotations
|
||||
|
||||
# Add support for annotations
|
||||
|
||||
This guide explains how to add support for [annotations]({{< relref "../../dashboards/annotations.md" >}}) to an existing data source plugin.
|
||||
This guide explains how to add support for [annotations]({{< relref "../../dashboards/annotations/" >}}) to an existing data source plugin.
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}}).
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}}).
|
||||
|
||||
> **Note:** Annotation support for React plugins was released in Grafana 7.2. To support earlier versions, refer to the [Add support for annotation for Grafana 7.1](https://grafana.com/docs/grafana/v7.1/developers/plugins/add-support-for-annotations/).
|
||||
|
||||
@ -16,7 +16,7 @@ This guide assumes that you're already familiar with how to [Build a data source
|
||||
|
||||
To enable annotation support for your data source, add the following two lines of code. Grafana uses your default query editor for editing annotation queries.
|
||||
|
||||
1. Add `"annotations": true` to the [plugin.json]({{< relref "metadata.md" >}}) file to let Grafana know that your plugin supports annotations.
|
||||
1. Add `"annotations": true` to the [plugin.json]({{< relref "metadata/" >}}) file to let Grafana know that your plugin supports annotations.
|
||||
|
||||
**plugin.json**
|
||||
|
||||
|
||||
@ -6,9 +6,9 @@ title: Add support for Explore queries
|
||||
|
||||
# Add support for Explore queries
|
||||
|
||||
This guide explains how to improve support for [Explore]({{< relref "../../explore/_index.md" >}}) in an existing data source plugin.
|
||||
This guide explains how to improve support for [Explore]({{< relref "../../explore/" >}}) in an existing data source plugin.
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}}).
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}}).
|
||||
|
||||
With Explore, users can make ad-hoc queries without the use of a dashboard. This is useful when users want to troubleshoot or to learn more about the data.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ title: Add support for variables in plugins
|
||||
|
||||
# Add support for variables in plugins
|
||||
|
||||
Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../variables/_index.md" >}}).
|
||||
Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../variables/" >}}).
|
||||
|
||||
This guide explains how to leverage template variables in your panel plugins and data source plugins.
|
||||
|
||||
@ -78,7 +78,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 "../../variables/advanced-variable-format-options.md" >}}).
|
||||
For more information on the available variable formats, refer to [Advanced variable format options]({{< relref "../../variables/advanced-variable-format-options/" >}}).
|
||||
|
||||
## Set a variable from your plugin
|
||||
|
||||
@ -101,7 +101,7 @@ locationService.partial({ 'var-service': 'billing' }, true);
|
||||
|
||||
## Add support for query variables to your data source
|
||||
|
||||
[Query variables]({{< relref "../../variables/variable-types/add-query-variable.md" >}}) 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.
|
||||
[Query variables]({{< relref "../../variables/variable-types/add-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.
|
||||
|
||||
@ -199,4 +199,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 "../../variables/variable-types/add-query-variable.md" >}}) to your dashboard.
|
||||
That's it! You can now try out the plugin by adding a [query variable]({{< relref "../../variables/variable-types/add-query-variable/" >}}) to your dashboard.
|
||||
|
||||
@ -20,7 +20,7 @@ However, one limitation with these plugins are that they execute on the client-s
|
||||
|
||||
We use the term _backend plugin_ to denote that a plugin has a backend component. Still, normally a backend plugin requires frontend components as well. This is for example true for backend data source plugins which normally need configuration and query editor components implemented for the frontend.
|
||||
|
||||
Data source plugins can be extended with a backend component. In the future we plan to support additional types and possibly new kinds of plugins, such as [notifiers for Grafana alerting]({{< relref "../../../alerting/notifications/_index.md" >}}) and custom authentication to name a few.
|
||||
Data source plugins can be extended with a backend component. In the future we plan to support additional types and possibly new kinds of plugins, such as [notifiers for Grafana alerting]({{< relref "../../../alerting/notifications/" >}}) and custom authentication to name a few.
|
||||
|
||||
## Use cases for implementing a backend plugin
|
||||
|
||||
@ -49,7 +49,7 @@ Grafana's backend plugin system exposes a couple of different capabilities, or b
|
||||
|
||||
### Query data
|
||||
|
||||
The query data capability allows a backend plugin to handle data source queries that are submitted from a [dashboard]({{< relref "../../../dashboards/_index.md" >}}), [Explore]({{< relref "../../../explore/_index.md" >}}) or [Grafana Alerting]({{< relref "../../../alerting/" >}}). The response contains [data frames]({{< relref "../data-frames.md" >}}), which are used to visualize metrics, logs, and traces. The query data capability is required to implement for a backend data source plugin.
|
||||
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 is required to implement for a backend data source plugin.
|
||||
|
||||
### Resources
|
||||
|
||||
@ -57,7 +57,7 @@ The resources capability allows a backend plugin to handle custom HTTP requests
|
||||
|
||||
Examples of use cases for implementing resources:
|
||||
|
||||
- Implement a custom data source proxy in case certain authentication/authorization or other requirements are required/needed that are not supported in Grafana's [built-in data proxy]({{< relref "../../http_api/data_source.md#data-source-proxy-calls" >}}).
|
||||
- Implement a custom data source proxy in case certain authentication/authorization or other requirements are required/needed 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 to 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 micro controller or IOT device.
|
||||
@ -71,6 +71,6 @@ The health checks capability allows a backend plugin to return the status of the
|
||||
|
||||
### 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.md" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in, and gives you Go runtime metrics and process metrics out of the box. By using the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) you can 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/" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in, and gives you Go runtime metrics and process metrics out of the box. By using the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) you can add custom metrics to instrument your backend plugin.
|
||||
|
||||
A metrics endpoint (`/api/plugins/<plugin id>/metrics`) for a plugin is available in the Grafana HTTP API and allows a Prometheus instance to be configured to scrape the metrics.
|
||||
|
||||
@ -14,13 +14,13 @@ title: Grafana Plugin SDK for Go
|
||||
|
||||
# Grafana plugin SDK for Go
|
||||
|
||||
The Grafana plugin SDK for Go enables building Grafana backend plugins using [Go](https://golang.org/). The SDK provides a high-level framework with APIs, utilities and tooling that abstract away the details of the [plugin protocol]({{< relref "plugin-protocol.md" >}}) and RPC communication so plugin developers do not need to manage either.
|
||||
The Grafana plugin SDK for Go enables building Grafana backend plugins using [Go](https://golang.org/). The SDK provides a high-level framework with APIs, utilities and tooling that abstract away the details of the [plugin protocol]({{< relref "plugin-protocol/" >}}) and RPC communication so plugin developers do not need to manage either.
|
||||
|
||||
The [github.com/grafana/grafana-plugin-sdk-go](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=overview) is a Go module that provides a set of [Go packages](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=packages) that can be used to implement a backend plugin.
|
||||
|
||||
## Versioning
|
||||
|
||||
The SDK is still in development. The [plugin protocol]({{< relref "plugin-protocol.md" >}}) between Grafana and the plugin SDK is versioned separately and considered stable. However, there might be breaking changes introduced in the SDK. This means that plugins using an older version of the SDK should still work with Grafana, but might lose out on new features and capabilities introduced in the SDK.
|
||||
The SDK is still in development. The [plugin protocol]({{< relref "plugin-protocol/" >}}) between Grafana and the plugin SDK is versioned separately and considered stable. However, there might be breaking changes introduced in the SDK. This means that plugins using an older version of the SDK should still work with Grafana, but might lose out on new features and capabilities introduced in the SDK.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@ -15,9 +15,9 @@ title: Plugin protocol
|
||||
|
||||
There’s a physical wire protocol that Grafana server uses to communicate with backend plugins. This is the contract between Grafana and backend plugins, that must be agreed upon for Grafana and a backend plugin to be able to communicate with each other. The plugin protocol is built on [gRPC](https://grpc.io/) and is defined in [Protocol Buffers (a.k.a., protobuf)](https://developers.google.com/protocol-buffers).
|
||||
|
||||
We advise for backend plugins to not be implemented directly against this protocol. Instead, prefer to use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go.md" >}}) that implements this protocol and provides higher level APIs.
|
||||
We advise for backend plugins to not be implemented directly against this protocol. Instead, prefer to use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher level APIs.
|
||||
|
||||
The plugin protocol is available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto). The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go.md" >}}) since Grafana itself uses parts of the SDK as a dependency.
|
||||
The plugin protocol is available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto). The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) since Grafana itself uses parts of the SDK as a dependency.
|
||||
|
||||
## Versioning
|
||||
|
||||
@ -29,7 +29,7 @@ Because Grafana maintains the plugin protocol, the plugin protocol attempts to f
|
||||
|
||||
If you want to write a backend plugin in another language than Go, then it’s possible as long as the language supports [gRPC](https://grpc.io/). However, writing a plugin in Go is recommended and has several advantages that should be carefully taken into account before proceeding:
|
||||
|
||||
- There's an official [SDK]({{< relref "grafana-plugin-sdk-for-go.md" >}}) available.
|
||||
- There's an official [SDK]({{< relref "grafana-plugin-sdk-for-go/" >}}) available.
|
||||
- Single binary as the compiled output.
|
||||
- Building and compiling for multiple platforms is easy.
|
||||
- A statically compiled binary (in most cases) doesn't require any additional dependencies installed on the target platform enabling it to run “everywhere”.
|
||||
|
||||
@ -8,7 +8,7 @@ title: Build a logs data source plugin
|
||||
|
||||
This guide explains how to build a logs data source plugin.
|
||||
|
||||
Data sources in Grafana supports both metrics and log data. The steps to build a logs data source plugin are largely the same as for a metrics data source. This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}}) for metrics.
|
||||
Data sources in Grafana supports both metrics and log data. The steps to build a logs data source plugin are largely the same as for a metrics data source. This guide assumes that you're already familiar with how to [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}}) for metrics.
|
||||
|
||||
## Add logs support to your data source
|
||||
|
||||
@ -20,7 +20,7 @@ To add logs support to an existing data source, you need to:
|
||||
|
||||
### Enable logs support
|
||||
|
||||
Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "metadata.md" >}}) file.
|
||||
Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "metadata/" >}}) file.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -30,7 +30,7 @@ Tell Grafana that your data source plugin can return log data, by adding `"logs"
|
||||
|
||||
### Construct the log data
|
||||
|
||||
Just like for metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames.md" >}}).
|
||||
Just like for metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames/" >}}).
|
||||
|
||||
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.
|
||||
|
||||
@ -49,13 +49,13 @@ 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/_index.md" >}}) or by adding a [Logs panel]({{< relref "../../visualizations/logs-panel.md" >}}).
|
||||
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 "../../visualizations/logs-panel/" >}}).
|
||||
|
||||
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.
|
||||
|
||||
### (Optional) Add preferred visualisation type hint to the data frame
|
||||
|
||||
To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore you have do set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries.md#selecting-preferred-visualisation" >}})
|
||||
To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore you have do set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries/#selecting-preferred-visualisation" >}})
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -97,7 +97,7 @@ frame.add({ time: 1589189406480, content: 'user logged in' });
|
||||
|
||||
You can add additional information about each log line by adding 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. Any subsequent text fields are treated as [detected fields]({{< relref "../../explore/_index.md#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. Any subsequent text fields are treated as [detected fields]({{< relref "../../explore/#labels-and-detected-fields" >}}).
|
||||
|
||||
While you can add any number of custom fields to your data frame, Grafana comes with a couple of dedicated fields: `levels` and `id`. Let's have a closer look at each one.
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ title: Build a streaming data source plugin
|
||||
|
||||
This guide explains how to build a streaming data source plugin.
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "tutorials/build-a-data-source-plugin.md" >}}).
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< ref "/tutorials/build-a-data-source-plugin/" >}}).
|
||||
|
||||
When monitoring critical applications, you want your dashboard to refresh as soon as your data does. In Grafana, you can set your dashboards to automatically refresh at a certain interval, no matter what data source you use. Unfortunately, this means that your queries are requesting all the data to be sent again, regardless of whether the data has actually changed.
|
||||
|
||||
|
||||
@ -74,7 +74,7 @@ A data transformation is any function that accepts a data frame as input, and re
|
||||
|
||||
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 "../../basics/timeseries.md" >}}).
|
||||
For more information on time series, refer to our [Introduction to time series]({{< relref "../../basics/timeseries/" >}}).
|
||||
|
||||
### Wide format
|
||||
|
||||
@ -165,7 +165,7 @@ Dimensions: 5 fields by 2 rows
|
||||
+---------------------+------------------+------------------+------------------+------------------+
|
||||
```
|
||||
|
||||
> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility we have introduced a transformation that can be used to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../panels/transform-data/transformation-functions.md#prepare-time-series" >}}).
|
||||
> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility we have introduced a transformation that can be used to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../panels/transform-data/transformation-functions/#prepare-time-series" >}}).
|
||||
|
||||
## Technical references
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ title: Legacy plugins
|
||||
|
||||
# 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 "../_index.md" >}}).
|
||||
> **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 "../" >}}).
|
||||
|
||||
You can extend Grafana by writing your own plugins and then share them with other users in [our plugin repository](https://grafana.com/plugins).
|
||||
|
||||
@ -50,20 +50,20 @@ Grafana that can impact your plugin.
|
||||
|
||||
## Metadata
|
||||
|
||||
See the [coding styleguide]({{< relref "style-guide.md" >}}) for details on the metadata.
|
||||
See the [coding styleguide]({{< relref "style-guide/" >}}) 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.md" >}}), [panels]({{< relref "panels.md" >}})
|
||||
and [apps]({{< relref "apps.md" >}}) plugins in the documentation.
|
||||
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.
|
||||
|
||||
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.md" >}}).
|
||||
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/" >}}).
|
||||
|
||||
Example:
|
||||
|
||||
@ -111,7 +111,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.md" >}}) 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
|
||||
|
||||
@ -125,9 +125,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.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" >}})
|
||||
- [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/" >}})
|
||||
|
||||
@ -162,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.md" >}}) works.
|
||||
Read more here about how [authentication for data sources]({{< relref "../add-authentication-for-data-source-plugins/" >}}) works.
|
||||
|
||||
If using the proxy feature, the Configuration page should use the `secureJsonData` blob like this:
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ title: Legacy snapshot mode
|
||||
|
||||
{{< figure class="float-right" src="/static/img/docs/Grafana-snapshot-example.png" caption="A dashboard using snapshot data and not live data." >}}
|
||||
|
||||
Grafana has this great feature where you can [save a snapshot of your dashboard]({{< relref "../../../dashboards/json-model.md" >}}). Instead of sending a screenshot of a dashboard to someone, you can send them a working, interactive Grafana dashboard with the snapshot data embedded inside it. The snapshot can be saved on your Grafana server and is available to all your co-workers. Raintank also hosts a [snapshot server](https://snapshots.raintank.io) if you want to send the snapshot to someone who does not have access to your Grafana server.
|
||||
Grafana has this great feature where you can [save a snapshot of your dashboard]({{< relref "../../../dashboards/json-model/" >}}). Instead of sending a screenshot of a dashboard to someone, you can send them a working, interactive Grafana dashboard with the snapshot data embedded inside it. The snapshot can be saved on your Grafana server and is available to all your co-workers. Raintank also hosts a [snapshot server](https://snapshots.raintank.io) if you want to send the snapshot to someone who does not have access to your Grafana server.
|
||||
|
||||
{{< figure class="float-right" src="/static/img/docs/animated_gifs/snapshots.gif" caption="Selecting a snapshot" >}}
|
||||
|
||||
|
||||
@ -28,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.md" >}}).
|
||||
For more information about the file format for `plugin.json` file, refer to [metadata]({{< relref "../metadata/" >}}).
|
||||
|
||||
Minimal plugin.json:
|
||||
|
||||
|
||||
@ -323,7 +323,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.md#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`**
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ There are three steps needed to package a plugin:
|
||||
mage
|
||||
```
|
||||
|
||||
1. [Sign the plugin]({{< relref "sign-a-plugin.md" >}}).
|
||||
1. [Sign the plugin]({{< relref "sign-a-plugin/" >}}).
|
||||
|
||||
1. Create a ZIP archive of the `dist` directory.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ title: Sign a plugin
|
||||
|
||||
# Sign a plugin
|
||||
|
||||
Signing a plugin allows Grafana to verify the authenticity of the plugin with [signature verification]({{< relref "../../plugins/plugin-signatures.md" >}}). This gives users a way to make sure plugins haven't been tampered with. All Grafana Labs-authored backend plugins, including Enterprise plugins, are signed.
|
||||
Signing a plugin allows Grafana to verify the authenticity of the plugin with [signature verification]({{< relref "../../plugins/plugin-signatures/" >}}). This gives users a way to make sure plugins haven't been tampered with. All Grafana Labs-authored backend plugins, including Enterprise plugins, are signed.
|
||||
|
||||
> **Important:** Future versions of Grafana will require all plugins to be signed.
|
||||
|
||||
@ -14,7 +14,7 @@ Before you can sign your plugin, you need to decide whether you want to sign it
|
||||
|
||||
If you want to make your plugin publicly available outside of your organization, you need to sign your plugin under a _community_ or _commercial_ [signature level](#plugin-signature-levels). Public plugins are available from [grafana.com/plugins](https://grafana.com/plugins) and can be installed by anyone.
|
||||
|
||||
For more information on how to install public plugin, refer to [Install Grafana plugins]({{< relref "../../plugins/installation.md" >}}).
|
||||
For more information on how to install public plugin, refer to [Install Grafana plugins]({{< relref "../../plugins/installation/" >}}).
|
||||
|
||||
If you intend to only use the plugin within your organization, you can to sign it under a _private_ [signature level](#plugin-signature-levels).
|
||||
|
||||
@ -34,7 +34,7 @@ To verify ownership of your plugin, you need to generate an API key that you'll
|
||||
|
||||
Public plugins need to be reviewed by the Grafana team before you can sign them.
|
||||
|
||||
1. Submit your plugin for [review]({{< relref "package-a-plugin.md#publishing-your-plugin-for-the-first-time" >}})
|
||||
1. Submit your plugin for [review]({{< relref "package-a-plugin/#publishing-your-plugin-for-the-first-time" >}})
|
||||
2. When your plugin is approved, you're granted a plugin signature level. **Without a plugin signature level, you won't be able to sign your plugin**.
|
||||
3. In your plugin directory, sign the plugin with the API key you just created. Grafana Toolkit creates a [MANIFEST.txt](#plugin-manifest) file in the `dist` directory of your plugin.
|
||||
|
||||
@ -125,6 +125,6 @@ Due to an issue when signing the plugin on Windows, grafana-toolkit generates an
|
||||
|
||||
If you're trying to sign a **public** plugin, this means that your plugin doesn't have a plugin signature level assigned to it yet. A Grafana team member will assign a signature level to your plugin once it has been reviewed and approved. For more information, refer to [Sign a public plugin](#sign-a-public-plugin).
|
||||
|
||||
If you're trying to sign a **private** plugin, this means that you need to add a `rootUrls` flag to the `plugin:sign` command. The `rootUrls` must match the [root_url]({{< relref "../../administration/configuration.md#root_url" >}}) configuration. For more information, refer to [Sign a private plugin](#sign-a-private-plugin).
|
||||
If you're trying to sign a **private** plugin, this means that 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.
|
||||
|
||||
@ -10,7 +10,7 @@ The data frame is a columnar data structure which allows efficient querying of l
|
||||
|
||||
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're looking to migrate an existing plugin to use the data frame format, refer to [Migrate to data frames]({{< relref "migration-guide.md#migrate-to-data-frames" >}}).
|
||||
> **Note:** If you're looking to migrate an existing plugin to use the data frame format, refer to [Migrate to data frames]({{< relref "migration-guide/#migrate-to-data-frames" >}}).
|
||||
|
||||
## Create a data frame
|
||||
|
||||
|
||||
Reference in New Issue
Block a user