Docs: Sync latest master docs with 7.5.x (#33156)
* Docs: Sync latest master docs with 7.5.x * remove some remaining next aliases and links * Docs: Removed v8 doc changes * fixed merge issue
This commit is contained in:
Torkel Ödegaard
GitHub
@@ -1,6 +1,6 @@
|
||||
+++
|
||||
title = "Add authentication for data source plugins"
|
||||
aliases = ["/docs/grafana/latest/plugins/developing/auth-for-datasources/", "/docs/grafana/next/developers/plugins/authentication/"]
|
||||
aliases = ["/docs/grafana/latest/plugins/developing/auth-for-datasources/", "/docs/grafana/latest/developers/plugins/authentication/"]
|
||||
+++
|
||||
|
||||
# Add authentication for data source plugins
|
||||
@@ -131,6 +131,23 @@ To add URL parameters to proxied requests, use the `urlParams` property.
|
||||
]
|
||||
```
|
||||
|
||||
### Set body content
|
||||
|
||||
To set the body content and length of proxied requests, use the `body` property.
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
{
|
||||
"path": "example",
|
||||
"url": "http://api.example.com",
|
||||
"body": {
|
||||
"username": "{{ .JsonData.username }}",
|
||||
"password": "{{ .SecureJsonData.password }}"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Enable token authentication
|
||||
|
||||
To enable token-based authentication for proxied requests, use the `tokenAuth` property.
|
||||
|
||||
@@ -8,140 +8,26 @@ This guide explains how to add support for [annotations]({{< relref "../../dashb
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin]({{< relref "/tutorials/build-a-data-source-plugin.md" >}}).
|
||||
|
||||
Data sources in Grafana can support [Annotations]({{< relref "../../dashboards/annotations.md" >}}) by handling _annotation queries_.
|
||||
|
||||
Handling annotation queries is similar to how you'd handle a metrics query. The difference is that instead of returning [data frames]({{< relref "data-frames.md" >}}), an annotation query returns _annotation events_.
|
||||
> **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/).
|
||||
|
||||
## Add annotations support to your data source
|
||||
|
||||
To add support for annotations to an existing data source, you need to:
|
||||
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.
|
||||
|
||||
- Enable annotations support
|
||||
- Override the `annotationQuery` method
|
||||
- Construct annotation events
|
||||
1. Add `"annotations": true` to the [plugin.json]({{< relref "metadata.md" >}}) file to let Grafana know that your plugin supports annotations.
|
||||
|
||||
### Enable annotations support
|
||||
**plugin.json**
|
||||
|
||||
Tell Grafana that your data source plugin can return annotations events by adding `"annotations": true` to the [plugin.json]({{< relref "metadata.md" >}}) file.
|
||||
|
||||
```json
|
||||
{
|
||||
"annotations": true
|
||||
}
|
||||
```
|
||||
|
||||
### Override the `annotationQuery` method
|
||||
|
||||
In `DataSource.ts`, override the `annotationQuery` method from `DataSourceApi`.
|
||||
|
||||
```ts
|
||||
async annotationQuery(options: AnnotationQueryRequest<MyQuery>): Promise<AnnotationEvent[]> {
|
||||
return [];
|
||||
}
|
||||
```
|
||||
|
||||
### Construct annotation events
|
||||
|
||||
Return an array of [AnnotationEvent]({{< relref "../../packages_api/data/annotationevent.md" >}}).
|
||||
|
||||
```ts
|
||||
async annotationQuery(options: AnnotationQueryRequest<MyQuery>): Promise<AnnotationEvent[]> {
|
||||
const events: AnnotationEvent[] = [];
|
||||
|
||||
const date = new Date();
|
||||
|
||||
const event: AnnotationEvent = {
|
||||
time: date.valueOf(),
|
||||
text: 'foo',
|
||||
tags: ['bar'],
|
||||
};
|
||||
|
||||
events.push(event);
|
||||
|
||||
return events;
|
||||
}
|
||||
```
|
||||
|
||||
## Region annotations
|
||||
|
||||
[Region annotations]({{< relref "../../dashboards/annotations.md#adding-regions-events" >}}) have a start and end time. This can for example be used to annotate maintenance windows or downtime.
|
||||
|
||||
To return a region annotation, set the `timeEnd`, and `isRegion` properties.
|
||||
|
||||
```ts
|
||||
const regionEvent: AnnotationEvent = {
|
||||
time: startDate.valueOf(),
|
||||
timeEnd: endDate.valueOf(),
|
||||
isRegion: true,
|
||||
text: 'foo',
|
||||
tags: ['bar'],
|
||||
};
|
||||
```
|
||||
|
||||
## Build a annotation query editor
|
||||
|
||||
Let users write custom annotation queries to only display the annotation events they care about, by adding a _query editor_. You only need to build a query editor if you want to let users query or filter annotations.
|
||||
|
||||
> **Note:** Annotation query editors have yet to receive support for React. The instructions here are given for Angular. Fortunately, you can run Angular even in a plugin otherwise written using React. This section will be updated once React support for annotation queries editors is available.
|
||||
|
||||
1. Create a file called `AnnotationQueryEditor.ts` in the `src` directory, with the following content.
|
||||
|
||||
```ts
|
||||
export class AnnotationQueryEditor {
|
||||
static templateUrl = 'partials/annotations.editor.html';
|
||||
|
||||
annotation: any;
|
||||
|
||||
constructor() {
|
||||
this.annotation.queryText = this.annotation.queryText || '';
|
||||
}
|
||||
```json
|
||||
{
|
||||
"annotations": true
|
||||
}
|
||||
```
|
||||
|
||||
1. Create a directory called `partials` in the `src` directory.
|
||||
2. In `datasource.ts`, override the `annotations` property from `DataSourceApi`. For the default behavior, you can set `annotations` to an empty object.
|
||||
|
||||
1. Create a file called `annotations.editor.html` in the `partials` directory you just created, with the following content.
|
||||
|
||||
```html
|
||||
<div class="gf-form-group">
|
||||
<div class="gf-form-inline">
|
||||
<div class="gf-form gf-form--grow">
|
||||
<input
|
||||
class="gf-form-input"
|
||||
placeholder="query expression"
|
||||
ng-model="ctrl.annotation.queryText"
|
||||
></input>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
1. In your data source query—the one that extends [DataQuery]({{< relref "../../packages_api/data/dataquery.md" >}})—add the `queryText` property. The name of the property needs to correspond to the text in `ng-model`, e.g. `ctrl.annotation.<propertyName>`.
|
||||
**datasource.ts**
|
||||
|
||||
```ts
|
||||
export interface MyQuery extends DataQuery {
|
||||
// ...
|
||||
queryText?: string;
|
||||
}
|
||||
annotations: {};
|
||||
```
|
||||
|
||||
1. In `module.ts`, add the annotation query editor to the plugin.
|
||||
|
||||
```ts
|
||||
import { AnnotationQueryEditor } from './AnnotationQueryEditor';
|
||||
|
||||
export const plugin = new DataSourcePlugin<DataSource, MyQuery, MyDataSourceOptions>(DataSource)
|
||||
.setConfigEditor(ConfigEditor)
|
||||
.setQueryEditor(QueryEditor)
|
||||
.setAnnotationQueryCtrl(AnnotationQueryEditor);
|
||||
```
|
||||
|
||||
The `queryText` property is now available on the `options` object in the `annotationQuery` method:
|
||||
|
||||
```ts
|
||||
async annotationQuery(options: AnnotationQueryRequest<MyQuery>): Promise<AnnotationEvent[]> {
|
||||
const expression = options.annotation.queryText;
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
@@ -4,7 +4,7 @@ title = "Add support for Explore queries"
|
||||
|
||||
# Add support for Explore queries
|
||||
|
||||
This guide explains how to improve support for [Explore]({{< relref "../../explore/_index.md" >}}) to an existing data source plugin.
|
||||
This guide explains how to improve support for [Explore]({{< relref "../../explore/_index.md" >}}) 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" >}}).
|
||||
|
||||
@@ -85,27 +85,20 @@ The query editor for Explore is similar to the query editor for the data source
|
||||
};
|
||||
```
|
||||
|
||||
## Support multiple Explore modes
|
||||
## Selecting preferred visualisation
|
||||
|
||||
Explore lets you query any data source, regardless of whether it returns metrics or logs. You can change which type of query you want to make, by setting the _Explore mode_.
|
||||
Explore should by default select a reasonable visualization for your data so users do not have to tweak and play with the visualizations and just focus on querying. This usually works fairly well and Explore can figure out whether the returned data is time series data or logs or something else.
|
||||
|
||||
The query modes that the plugin supports are defined in the [plugin.json]({{< relref "metadata.md" >}}) file.
|
||||
|
||||
The query mode is available on the `props` object for both the query editor and the start page. For example, here's how you can change the query editor based on the currently selected mode:
|
||||
If this does not work for you or you want to show some data in a specific visualization, add a hint to your returned data frame using the `preferredVisualisationType` meta attribute.
|
||||
|
||||
You can construct a data frame with specific metadata:
|
||||
```
|
||||
export default (props: Props) => {
|
||||
const { query, exploreMode } = props;
|
||||
|
||||
switch (exploreMode) {
|
||||
case ExploreMode.Metrics:
|
||||
return <MetricsQueryField query={query} />;
|
||||
case ExploreMode.Logs:
|
||||
return <LogsQueryField query={query} />;
|
||||
default:
|
||||
return <p>Unsupported mode</p>;
|
||||
}
|
||||
}
|
||||
const firstResult = new MutableDataFrame({
|
||||
fields: [...],
|
||||
meta: {
|
||||
preferredVisualisationType: 'logs',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
For possible options, refer to [PreferredVisualisationType](https://grafana.com/docs/grafana/latest/packages_api/data/preferredvisualisationtype/).
|
||||
|
||||
@@ -14,6 +14,7 @@ To add logs support to an existing data source, you need to:
|
||||
|
||||
- Enable logs support
|
||||
- Construct the log data
|
||||
- (Optional) Add preferred visualisation type hint to the data frame
|
||||
|
||||
### Enable logs support
|
||||
|
||||
@@ -50,6 +51,25 @@ That's all you need to start returning log data from your data source. Go ahead
|
||||
|
||||
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" >}})
|
||||
|
||||
**Example:**
|
||||
|
||||
```ts
|
||||
const frame = new MutableDataFrame({
|
||||
refId: query.refId,
|
||||
meta: {
|
||||
preferredVisualisationType: 'logs',
|
||||
},
|
||||
fields: [
|
||||
{ name: 'time', type: FieldType.time },
|
||||
{ name: 'content', type: FieldType.string },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Add labels to your logs
|
||||
|
||||
To help filter log lines, many log systems let you query logs based on metadata, or _labels_.
|
||||
|
||||
@@ -72,7 +72,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 "../../getting-started/timeseries.md" >}}).
|
||||
For more information on time series, refer to our [Introduction to time series]({{< relref "../../basics/timeseries.md" >}}).
|
||||
|
||||
### Wide format
|
||||
|
||||
|
||||
@@ -174,6 +174,7 @@ For data source plugins. Proxy routes used for plugin authentication and adding
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|----------------|-------------------------|----------|---------------------------------------------------------------------------------------------------------|
|
||||
| `body` | [object](#body) | No | For data source plugins. Route headers set the body content and length to the proxied request. |
|
||||
| `headers` | array | No | For data source plugins. Route headers adds HTTP headers to the proxied request. |
|
||||
| `jwtTokenAuth` | [object](#jwttokenauth) | No | For data source plugins. Token authentication section used with an JWT OAuth API. |
|
||||
| `method` | string | No | For data source plugins. Route method matches the HTTP verb like GET or POST. |
|
||||
@@ -183,29 +184,37 @@ For data source plugins. Proxy routes used for plugin authentication and adding
|
||||
| `tokenAuth` | [object](#tokenauth) | No | For data source plugins. Token authentication section used with an OAuth API. |
|
||||
| `url` | string | No | For data source plugins. Route URL is where the request is proxied to. |
|
||||
|
||||
### body
|
||||
|
||||
For data source plugins. Route headers set the body content and length to the proxied request.
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
|
||||
### jwtTokenAuth
|
||||
|
||||
For data source plugins. Token authentication section used with an JWT OAuth API.
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|----------|-------------------|----------|---------------------------------------------------------------------------|
|
||||
| `params` | [object](#params) | No | For data source plugins. Parameters for the token authentication request. |
|
||||
| `url` | string | No | For data source plugins. URL to fetch the JWT token. |
|
||||
| Property | Type | Required | Description |
|
||||
|----------|-------------------|----------|------------------------------------------------------|
|
||||
| `params` | [object](#params) | No | Parameters for the JWT token authentication request. |
|
||||
| `scopes` | string | No | |
|
||||
| `url` | string | No | URL to fetch the JWT token. |
|
||||
|
||||
#### params
|
||||
|
||||
For data source plugins. Parameters for the token authentication request.
|
||||
Parameters for the JWT token authentication request.
|
||||
|
||||
##### Properties
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|-----------------|--------|----------|--------------------------------------------------------------------------------------------------------------------|
|
||||
| `client_id` | string | No | For data source plugins. OAuth client id. |
|
||||
| `client_secret` | string | No | For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob. |
|
||||
| `grant_type` | string | No | For data source plugins. OAuth grant type. |
|
||||
| `resource` | string | No | For data source plugins. OAuth resource. |
|
||||
| Property | Type | Required | Description |
|
||||
|----------------|----------|----------|-------------|
|
||||
| `client_email` | string | No | |
|
||||
| `private_key` | string | No | |
|
||||
| `scopes` | string[] | No | |
|
||||
| `token_uri` | string | No | |
|
||||
|
||||
### tokenAuth
|
||||
|
||||
@@ -213,22 +222,23 @@ For data source plugins. Token authentication section used with an OAuth API.
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|----------|-------------------|----------|---------------------------------------------------------------------------|
|
||||
| `params` | [object](#params) | No | For data source plugins. Parameters for the token authentication request. |
|
||||
| `url` | string | No | For data source plugins. URL to fetch the authentication token. |
|
||||
| Property | Type | Required | Description |
|
||||
|----------|-------------------|----------|--------------------------------------------------|
|
||||
| `params` | [object](#params) | No | Parameters for the token authentication request. |
|
||||
| `scopes` | string | No | |
|
||||
| `url` | string | No | URL to fetch the authentication token. |
|
||||
|
||||
#### params
|
||||
|
||||
For data source plugins. Parameters for the token authentication request.
|
||||
Parameters for the token authentication request.
|
||||
|
||||
##### Properties
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|-----------------|--------|----------|--------------------------------------------------------------------------------------------------------------------|
|
||||
| `client_id` | string | No | For data source plugins. OAuth client id. |
|
||||
| `client_secret` | string | No | For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob. |
|
||||
| `grant_type` | string | No | For data source plugins. OAuth grant type. |
|
||||
| `resource` | string | No | For data source plugins. OAuth resource. |
|
||||
| Property | Type | Required | Description |
|
||||
|-----------------|--------|----------|-------------------------------------------------------------------------------------------|
|
||||
| `client_id` | string | No | OAuth client ID |
|
||||
| `client_secret` | string | No | OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob. |
|
||||
| `grant_type` | string | No | OAuth grant type |
|
||||
| `resource` | string | No | OAuth resource |
|
||||
|
||||
|
||||
|
||||
@@ -350,6 +350,10 @@
|
||||
"type": "array",
|
||||
"description": "For data source plugins. Route headers adds HTTP headers to the proxied request."
|
||||
},
|
||||
"body": {
|
||||
"type": "object",
|
||||
"description": "For data source plugins. Route headers set the body content and length to the proxied request."
|
||||
},
|
||||
"tokenAuth": {
|
||||
"type": "object",
|
||||
"description": "For data source plugins. Token authentication section used with an OAuth API.",
|
||||
@@ -357,28 +361,32 @@
|
||||
"properties": {
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. URL to fetch the authentication token."
|
||||
"description": "URL to fetch the authentication token."
|
||||
},
|
||||
"scopes": {
|
||||
"type": "string",
|
||||
"description": ""
|
||||
},
|
||||
"params": {
|
||||
"type": "object",
|
||||
"description": "For data source plugins. Parameters for the token authentication request.",
|
||||
"description": "Parameters for the token authentication request.",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"grant_type": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth grant type."
|
||||
"description": "OAuth grant type"
|
||||
},
|
||||
"client_id": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth client id."
|
||||
"description": "OAuth client ID"
|
||||
},
|
||||
"client_secret": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob."
|
||||
"description": "OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob."
|
||||
},
|
||||
"resource": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth resource."
|
||||
"description": "OAuth resource"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -391,29 +399,36 @@
|
||||
"properties": {
|
||||
"url": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. URL to fetch the JWT token.",
|
||||
"description": "URL to fetch the JWT token.",
|
||||
"format": "uri"
|
||||
},
|
||||
"scopes": {
|
||||
"type": "string",
|
||||
"description": ""
|
||||
},
|
||||
"params": {
|
||||
"type": "object",
|
||||
"description": "For data source plugins. Parameters for the token authentication request.",
|
||||
"description": "Parameters for the JWT token authentication request.",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"grant_type": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth grant type."
|
||||
"scopes": {
|
||||
"type": "array",
|
||||
"description": "",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"client_id": {
|
||||
"token_uri": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth client id."
|
||||
"description": ""
|
||||
},
|
||||
"client_secret": {
|
||||
"client_email": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth client secret. Usually populated by decrypting the secret from the SecureJson blob."
|
||||
"description": ""
|
||||
},
|
||||
"resource": {
|
||||
"private_key": {
|
||||
"type": "string",
|
||||
"description": "For data source plugins. OAuth resource."
|
||||
"description": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user