mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Update plugin docs for annotation support (#31715)
* Update plugin docs for annotation support * Update docs/sources/developers/plugins/add-support-for-annotations.md Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/sources/developers/plugins/add-support-for-annotations.md Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
This commit is contained in:
Marcus Olsson
GitHub
parent
ee96861ce1
commit
c2a6f9623e
@ -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.
|
||||
|
||||
### 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` method 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;
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user