mirror of
https://github.com/grafana/grafana.git
synced 2025-07-30 21:42:37 +08:00
Docs: Minor edits to the README and several md files (#19238)
* Update README.md Capitalized the G and S in "Getting Started," and moved "guide" to match the section title in the docs. * Fixed sentence structure. Changed "download" to "grafana.com/get" and changed "get" to "download". * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111) * Docs: Replace "datasources" with "data sources" (#19111)
This commit is contained in:
Brenda Harjala
committed by
Marcus Olsson
Marcus Olsson
parent
b20a258b72
commit
c9e566b156
@ -10,15 +10,15 @@ weight = 4
|
||||
|
||||
# Grafana Apps
|
||||
|
||||
App plugins are a new kind of grafana plugin that can bundle datasource and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enable the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
|
||||
App plugins are a new kind of grafana plugin that can bundle data source and panel plugins within one package. It also enable the plugin author to create custom pages within grafana. The custom pages enable the plugin author to include things like documentation, sign up forms or controlling other services using HTTP requests.
|
||||
|
||||
Datasource and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
|
||||
Data source and panel plugins will show up like normal plugins. The app pages will be available in the main menu.
|
||||
|
||||
{{< imgbox img="/img/docs/v3/app-in-main-menu.png" caption="App in Main Menu" >}}
|
||||
|
||||
## Enabling app plugins
|
||||
|
||||
After installing an app, it has to be enabled before it shows up as a datasource or panel. You can do that on the app page in the config tab.
|
||||
After installing an app, it has to be enabled before it shows up as a data source or panel. You can do that on the app page in the config tab.
|
||||
|
||||
## Developing an App Plugin
|
||||
|
||||
|
||||
@ -7,25 +7,25 @@ parent = "developing"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
# Authentication for Datasource Plugins
|
||||
# Authentication for data source plugins
|
||||
|
||||
Grafana has a proxy feature that proxies all data requests through the Grafana backend. This is very useful when your datasource plugin calls an external/thirdy-party API. The Grafana proxy adds CORS headers and can authenticate against the external API. This means that a datasource plugin that proxies all requests via Grafana can enable token authentication and the token will be renewed automatically for the user when it expires.
|
||||
Grafana has a proxy feature that proxies all data requests through the Grafana backend. This is very useful when your data source plugin calls an external/thirdy-party API. The Grafana proxy adds CORS headers and can authenticate against the external API. This means that a data source plugin that proxies all requests via Grafana can enable token authentication and the token will be renewed automatically for the user when it expires.
|
||||
|
||||
The plugin config page should save the API key/password to be encrypted (using the `secureJsonData` feature) and then when a request from the datasource is made, the Grafana Proxy will:
|
||||
The plugin config page should save the API key/password to be encrypted (using the `secureJsonData` feature) and then when a request from the data source is made, the Grafana Proxy will:
|
||||
|
||||
1. decrypt the API key/password on the backend.
|
||||
2. carry out authentication and generate an OAuth token that will be added as an `Authorization` HTTP header to all requests (or it will add a HTTP header with the API key).
|
||||
3. renew the token if it expires.
|
||||
|
||||
This means that users that access the datasource config page cannot access the API key or password after is saved the first time and that no secret keys are sent in plain text through the browser where they can be spied on.
|
||||
This means that users that access the data source config page cannot access the API key or password after is saved the first time and that no secret keys are sent in plain text through the browser where they can be spied on.
|
||||
|
||||
For backend authentication to work, the external/third-party API must either have an OAuth endpoint or that the API accepts an API key as a HTTP header for authentication.
|
||||
|
||||
## Plugin Routes
|
||||
|
||||
You can specify routes in the `plugin.json` file for your datasource plugin. [Here is an example](https://github.com/grafana/azure-monitor-datasource/blob/d74c82145c0a4af07a7e96cc8dde231bfd449bd9/src/plugin.json#L30-L95) with lots of routes (though most plugins will just have one route).
|
||||
You can specify routes in the `plugin.json` file for your data source plugin. [Here is an example](https://github.com/grafana/azure-monitor-datasource/blob/d74c82145c0a4af07a7e96cc8dde231bfd449bd9/src/plugin.json#L30-L95) with lots of routes (though most plugins will just have one route).
|
||||
|
||||
When you build your url to the third-party API in your datasource class, the url should start with the text specified in the path field for a route. The proxy will strip out the path text and replace it with the value in the url field.
|
||||
When you build your url to the third-party API in your data source class, the url should start with the text specified in the path field for a route. The proxy will strip out the path text and replace it with the value in the url field.
|
||||
|
||||
For example, if my code makes a call to url `azuremonitor/foo/bar` with this code:
|
||||
|
||||
@ -53,7 +53,7 @@ The `method` parameter is optional. It can be set to any HTTP verb to provide mo
|
||||
|
||||
### Dynamic Routes
|
||||
|
||||
When using routes, you can also reference a variable stored in JsonData or SecureJsonData which will be interpolated when connecting to the datasource.
|
||||
When using routes, you can also reference a variable stored in JsonData or SecureJsonData which will be interpolated when connecting to the data source.
|
||||
|
||||
With JsonData:
|
||||
```json
|
||||
@ -83,7 +83,7 @@ An app using this feature can be found [here](https://github.com/grafana/kentik-
|
||||
|
||||
## Encrypting Sensitive Data
|
||||
|
||||
When a user saves a password or secret with your datasource plugin's Config page, then you can save data to a column in the datasource table called `secureJsonData` that is an encrypted blob. Any data saved in the blob is encrypted by Grafana and can only be decrypted by the Grafana server on the backend. This means once a password is saved, no sensitive data is sent to the browser. If the password is saved in the `jsonData` blob or the `password` field then it is unencrypted and anyone with Admin access (with the help of Chrome Developer Tools) can read it.
|
||||
When a user saves a password or secret with your data source plugin's Config page, then you can save data to a column in the data source table called `secureJsonData` that is an encrypted blob. Any data saved in the blob is encrypted by Grafana and can only be decrypted by the Grafana server on the backend. This means once a password is saved, no sensitive data is sent to the browser. If the password is saved in the `jsonData` blob or the `password` field then it is unencrypted and anyone with Admin access (with the help of Chrome Developer Tools) can read it.
|
||||
|
||||
This is an example of using the `secureJsonData` blob to save a property called `password`:
|
||||
|
||||
|
||||
@ -10,9 +10,9 @@ weight = 5
|
||||
|
||||
# Backend Plugins
|
||||
|
||||
Grafana added support for plugins in Grafana 3.0 and this enabled the Grafana community to create panel plugins and datasource plugins. It was wildly successful and has made Grafana much more useful as you can integrate it with anything and do any type of custom visualization that you want. However, these plugin hooks are on the frontend only and we also want to provide hooks into the Grafana backend to allow the community to extend and improve Grafana in new ways.
|
||||
Grafana added support for plugins in Grafana 3.0 and this enabled the Grafana community to create panel plugins and data source plugins. It was wildly successful and has made Grafana much more useful as you can integrate it with anything and do any type of custom visualization that you want. However, these plugin hooks are on the frontend only and we also want to provide hooks into the Grafana backend to allow the community to extend and improve Grafana in new ways.
|
||||
|
||||
Once Grafana introduced the alerting feature, external datasource plugins needed a backend component for the Grafana server to execute queries for evaluating alert rules (as the alerting engine cannot call frontend JavaScript code). So the the obvious first backend plugin type is the **Datasource backend plugin** and it is a new component for an existing datasource plugin. This new plugin type will enable alerting for external datasource plugins but can also be used for achieving different goals such as query caching, request proxying, custom authentication methods, and more.
|
||||
Once Grafana introduced the alerting feature, external data source plugins needed a backend component for the Grafana server to execute queries for evaluating alert rules (as the alerting engine cannot call frontend JavaScript code). So the the obvious first backend plugin type is the **Datasource backend plugin** and it is a new component for an existing data source plugin. This new plugin type will enable alerting for external data source plugins but can also be used for achieving different goals such as query caching, request proxying, custom authentication methods, and more.
|
||||
|
||||
## Grafana's Backend Plugin System
|
||||
|
||||
@ -22,7 +22,7 @@ The backend plugin feature is implemented with the [HashiCorp plugin system](htt
|
||||
- Plugins are easy to develop: just write a Go application and `go build` (or use any other language which supports gRPC).
|
||||
- Plugins can be relatively secure: The plugin only has access to the interfaces and args given to it, not to the entire memory space of the process.
|
||||
|
||||
## Datasource Plugin Interface
|
||||
## Data source plugin interface
|
||||
|
||||
The plugin interface is very simple and described as a Go interface type in [Grafana](https://github.com/grafana/grafana/blob/6724aaeff9a332dc73b4ee0f8abe0621f7253142/pkg/tsdb/query_endpoint.go#L10-L12) and as a general [RPC service](https://github.com/grafana/grafana-plugin-model/blob/84176c64269d8060f99e750ee8aba6f062753336/datasource.proto#L96-L98) in the corresponding `.proto` (protocol buffer file):
|
||||
|
||||
@ -42,11 +42,11 @@ Thus, a datasource plugin should only implement the `Query()` method.
|
||||
|
||||
## Introduction to building a backend component for a plugin
|
||||
|
||||
The [Simple JSON backend](https://github.com/grafana/simple-json-backend-datasource) datasource is a good example of writing a simple backend plugin in Go. Let's take a look at some key points.
|
||||
The [Simple JSON backend](https://github.com/grafana/simple-json-backend-datasource) data source is a good example of writing a simple backend plugin in Go. Let's take a look at some key points.
|
||||
|
||||
### Metadata
|
||||
|
||||
The plugin needs to know it has a backend component, this is done in the `plugin.json` file by setting two fields: `backend` and `executable`. If you want to enable alerting for your datasource, set the `alerting` field to `true` as well.
|
||||
The plugin needs to know it has a backend component, this is done in the `plugin.json` file by setting two fields: `backend` and `executable`. If you want to enable alerting for your data source, set the `alerting` field to `true` as well.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -93,11 +93,11 @@ simple-json-backend-datasource/
|
||||
|
||||
A `pkg/` directory contains three `.go` files:
|
||||
|
||||
- `plugin.go` - an entry point of the plugin. This file would be very similar for your datasource - you just need to change some details like the plugin name etc.
|
||||
- `plugin.go` - an entry point of the plugin. This file would be very similar for your data source - you just need to change some details like the plugin name etc.
|
||||
- `datasource.go` - contains `Query()` method implementation and other plugin logic.
|
||||
- `models.go` - types for request and response specific to your datasource.
|
||||
- `models.go` - types for request and response specific to your data source.
|
||||
|
||||
The datasource type is declared in [`datasource.go`](https://github.com/grafana/simple-json-backend-datasource/blob/7927ff0db60c3402dbf954a454f19d7230e18deb/pkg/datasource.go#L21-L24):
|
||||
The data source type is declared in [`datasource.go`](https://github.com/grafana/simple-json-backend-datasource/blob/7927ff0db60c3402dbf954a454f19d7230e18deb/pkg/datasource.go#L21-L24):
|
||||
|
||||
```go
|
||||
package main
|
||||
@ -111,7 +111,7 @@ type JsonDatasource struct {
|
||||
}
|
||||
```
|
||||
|
||||
The only requirement for the plugin type is that it should extend `plugin.NetRPCUnsupportedPlugin`. You can include more fields into your struct if you want to add some datasource-specific features, like logging, cache etc:
|
||||
The only requirement for the plugin type is that it should extend `plugin.NetRPCUnsupportedPlugin`. You can include more fields into your struct if you want to add some data source-specific features, like logging, cache etc:
|
||||
|
||||
```go
|
||||
type JsonDatasource struct {
|
||||
@ -129,7 +129,7 @@ func (t *JsonDatasource) Query(ctx context.Context, tsdbReq *datasource.Datasour
|
||||
|
||||
#### Request format
|
||||
|
||||
In order to call this method from the [frontend part of your datasource](https://github.com/grafana/simple-json-backend-datasource/blob/7927ff0db60c3402dbf954a454f19d7230e18deb/src/datasource.ts#L116), use the `/api/tsdb/query` endpoint:
|
||||
In order to call this method from the [frontend part of your data source](https://github.com/grafana/simple-json-backend-datasource/blob/7927ff0db60c3402dbf954a454f19d7230e18deb/src/datasource.ts#L116), use the `/api/tsdb/query` endpoint:
|
||||
|
||||
```js
|
||||
class SimpleJSONDatasource {
|
||||
|
||||
@ -8,17 +8,17 @@ parent = "developing"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
# Datasources
|
||||
# Data Sources
|
||||
|
||||
Datasource plugins enables people to develop plugins for any database that
|
||||
Data source plugins enables people to develop plugins for any database that
|
||||
communicates over http. Its up to the plugin to transform the data into
|
||||
time series data so that any grafana panel can then show it.
|
||||
|
||||
## Datasource development
|
||||
## Data source development
|
||||
|
||||
> Our goal is not to have a very extensive documentation but rather have actual
|
||||
> code that people can look at. An example implementation of a datasource can be
|
||||
> found in this [example datasource repo](https://github.com/grafana/simple-json-datasource)
|
||||
> code that people can look at. An example implementation of a data source can be
|
||||
> found in this [example data source repo](https://github.com/grafana/simple-json-datasource)
|
||||
|
||||
To interact with the rest of grafana the plugins module file can export 5 different components.
|
||||
|
||||
@ -29,7 +29,7 @@ To interact with the rest of grafana the plugins module file can export 5 differ
|
||||
|
||||
## Plugin json
|
||||
|
||||
There are two datasource specific settings for the plugin.json
|
||||
There are two data source specific settings for the plugin.json
|
||||
|
||||
```javascript
|
||||
"metrics": true,
|
||||
@ -38,15 +38,15 @@ There are two datasource specific settings for the plugin.json
|
||||
|
||||
These settings indicates what kind of data the plugin can deliver. At least one of them have to be true
|
||||
|
||||
## Datasource
|
||||
## Data source
|
||||
|
||||
The javascript object that communicates with the database and transforms data to times series.
|
||||
|
||||
The Datasource should contain the following functions:
|
||||
The Data source should contain the following functions:
|
||||
|
||||
```javascript
|
||||
query(options) //used by panels to get data
|
||||
testDatasource() //used by datasource configuration page to make sure the connection is working
|
||||
testDatasource() //used by data source configuration page to make sure the connection is working
|
||||
annotationQuery(options) // used by dashboards to get annotations
|
||||
metricFindQuery(options) // used by query editor to get metric suggestions.
|
||||
```
|
||||
@ -72,8 +72,8 @@ Request object passed to datasource.query function:
|
||||
}
|
||||
```
|
||||
|
||||
There are two different kinds of results for datasources;
|
||||
time series and table. Time series is the most common format and is supported by all datasources and panels. Table format is only supported by the InfluxDB datasource and table panel. But we might see more of this in the future.
|
||||
There are two different kinds of results for data sources;
|
||||
time series and table. Time series is the most common format and is supported by all data sources and panels. Table format is only supported by the InfluxDB data source and table panel. But we might see more of this in the future.
|
||||
|
||||
Time series response from datasource.query.
|
||||
An array of:
|
||||
@ -178,12 +178,12 @@ Requires a static template or templateUrl variable which will be rendered as the
|
||||
|
||||
## ConfigCtrl
|
||||
|
||||
A JavaScript class that will be instantiated and treated as an Angular controller when a user tries to edit or create a new datasource of this type.
|
||||
A JavaScript class that will be instantiated and treated as an Angular controller when a user tries to edit or create a new data source of this type.
|
||||
|
||||
Requires a static template or templateUrl variable which will be rendered as the view for this controller.
|
||||
|
||||
## AnnotationsQueryCtrl
|
||||
|
||||
A JavaScript class that will be instantiated and treated as an Angular controller when the user choose this type of datasource in the templating menu in the dashboard.
|
||||
A JavaScript class that will be instantiated and treated as an Angular controller when the user choose this type of data source in the templating menu in the dashboard.
|
||||
|
||||
Requires a static template or templateUrl variable which will be rendered as the view for this controller. The fields that are bound to this controller are then sent to the Database objects annotationQuery function.
|
||||
|
||||
@ -120,7 +120,7 @@ If a panel receives data and hooks into the `data-received` event then it should
|
||||
|
||||
We currently have three different examples that you can fork/download to get started developing your grafana plugin.
|
||||
|
||||
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small datasource plugin for querying json data from backends)
|
||||
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small data source plugin for querying json data from backends)
|
||||
- [example-app](https://github.com/grafana/example-app)
|
||||
- [clock-panel](https://github.com/grafana/clock-panel)
|
||||
- [singlestat-panel](https://github.com/grafana/grafana/blob/master/public/app/plugins/panel/singlestat/module.ts)
|
||||
@ -132,5 +132,5 @@ We currently have three different examples that you can fork/download to get sta
|
||||
- [Plugin Defaults and Editor Mode]({{< relref "defaults-and-editor-mode.md" >}})
|
||||
- [Grafana Plugin Code Styleguide]({{< relref "code-styleguide.md" >}})
|
||||
- [Grafana Apps]({{< relref "apps.md" >}})
|
||||
- [Grafana Datasources]({{< relref "datasources.md" >}})
|
||||
- [Grafana Data Sources]({{< relref "datasources.md" >}})
|
||||
- [plugin.json Schema]({{< relref "plugin.json.md" >}})
|
||||
|
||||
@ -155,7 +155,7 @@ A basic guide for data sources can be found [here](http://docs.grafana.org/plugi
|
||||
|
||||
If possible, any passwords or secrets should be 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 then this will not be possible and sensitive data will not be encrypted.
|
||||
|
||||
Read more here about how [Authentication for Datasources]({{< relref "auth-for-datasources.md" >}}) works.
|
||||
Read more here about how [authentication for data sources]({{< relref "auth-for-datasources.md" >}}) works.
|
||||
|
||||
If using the proxy feature then the Config page should use the `secureJsonData` blob like this:
|
||||
|
||||
@ -168,7 +168,7 @@ Each query editor is unique and can have a unique style. It should be adapted to
|
||||
|
||||
- Should use the Grafana CSS `gf-form` classes.
|
||||
- Should be neat and tidy. Labels and fields in columns should be aligned and should be the same width if possible.
|
||||
- The datasource should be able to handle when a user toggles a query (by clicking on the eye icon) and not execute the query. This is done by checking the `hide` property - an [example](https://github.com/grafana/grafana/blob/master/public/app/plugins/datasource/postgres/datasource.ts#L35-L38).
|
||||
- The data source should be able to handle when a user toggles a query (by clicking on the eye icon) and not execute the query. This is done by checking the `hide` property - an [example](https://github.com/grafana/grafana/blob/master/public/app/plugins/datasource/postgres/datasource.ts#L35-L38).
|
||||
- Should not execute queries if fields in the Query Editor are empty and the query will throw an exception (defensive programming).
|
||||
- Should handle errors. There are two main ways to do this:
|
||||
- use the notification system in Grafana to show a toaster popup with the error message. Example [here](https://github.com/alexanderzobnin/grafana-zabbix/blob/fdbbba2fb03f5f2a4b3b0715415e09d5a4cf6cde/src/panel-triggers/triggers_panel_ctrl.js#L467-L471).
|
||||
|
||||
Reference in New Issue
Block a user