mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 11:32:36 +08:00
Docs: Plugin doc review for chunk 1-A (#67070)
* Plugin doc review for chunk 1-A Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Group of fixes in response to review comments Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Updates for review comments Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Fixed extra space Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Additional doc fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * More doc fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Fixes from doc review Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Doc review fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * More changes from doc review Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Fix links and relrefs using doc-validator advice Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Publishing criteria update Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Markdown fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Testing Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Testing Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Testing Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Link fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Prettier Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Fix to publishing criteria Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Doc fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Doc fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Doc fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/build-a-logs-data-source-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/get-started-with-plugins/_index.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/publish-a-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/publish-a-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/publish-a-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Update docs/sources/developers/plugins/sign-a-plugin.md Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> * Prettier Signed-off-by: Joe Perez <joseph.perez@grafana.com> --------- Signed-off-by: Joe Perez <joseph.perez@grafana.com> Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com>
This commit is contained in:
Joseph Perez
@ -4,19 +4,22 @@ title: Build a logs data source plugin
|
||||
|
||||
# Build a logs data source plugin
|
||||
|
||||
This guide explains how to build a logs data source plugin.
|
||||
Grafana data source plugins support metrics, logs, and other data types. The steps to build a logs data source plugin are largely the same as for a metrics data source, but there are a few differences which we will explain in this guide.
|
||||
|
||||
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](/tutorials/build-a-data-source-plugin/) for metrics.
|
||||
## Before you begin
|
||||
|
||||
This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/) for metrics. We recommend that you review this material before continuing.
|
||||
|
||||
## Add logs support to your data source
|
||||
|
||||
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
|
||||
1. Enable logs support
|
||||
1. Construct the log data
|
||||
|
||||
### Enable logs support
|
||||
When these steps are done, then you can improve the user experience with one or more [optional features](#enhance-your-logs-data-source-plugin-with-optional-features).
|
||||
|
||||
### Step 1: Enable logs support
|
||||
|
||||
Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "metadata/" >}}) file.
|
||||
|
||||
@ -26,9 +29,9 @@ Tell Grafana that your data source plugin can return log data, by adding `"logs"
|
||||
}
|
||||
```
|
||||
|
||||
### Construct the log data
|
||||
### Step 2: Construct the log data
|
||||
|
||||
Just like for metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames/" >}}).
|
||||
As it does with metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "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.
|
||||
|
||||
@ -51,9 +54,13 @@ 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
|
||||
## Enhance your logs data source plugin with optional features
|
||||
|
||||
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" >}})
|
||||
Add visualization type hints, labels, and other optional features to logs.
|
||||
|
||||
### Add a preferred visualization type hint to the data frame
|
||||
|
||||
To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore, set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries/#selecting-preferred-visualisation" >}})
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -70,11 +77,11 @@ const frame = new MutableDataFrame({
|
||||
});
|
||||
```
|
||||
|
||||
## Add labels to your logs
|
||||
### Add labels to your logs
|
||||
|
||||
To help filter log lines, many log systems let you query logs based on metadata, or _labels_.
|
||||
Many log systems let you query logs based on metadata, or _labels_, to help filter log lines.
|
||||
|
||||
You can add labels to a stream of logs by setting the labels property on the Field.
|
||||
Add labels to a stream of logs by setting the `labels` property on the Field.
|
||||
|
||||
**Example**:
|
||||
|
||||
@ -91,15 +98,15 @@ frame.add({ time: 1589189388597, content: 'user registered' });
|
||||
frame.add({ time: 1589189406480, content: 'user logged in' });
|
||||
```
|
||||
|
||||
## Extract detected fields from your logs
|
||||
### Extract detected fields from your logs
|
||||
|
||||
You can add additional information about each log line by adding more data frame fields.
|
||||
Add additional information about each log line by supplying more data frame fields.
|
||||
|
||||
If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Any subsequent text fields are treated as [detected fields]({{< relref "../../explore/#labels-and-detected-fields" >}}).
|
||||
If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Grafana treats subsequent text fields as [detected fields]({{< 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.
|
||||
Any number of custom fields can be added to your data frame; Grafana comes with two dedicated fields: `levels` and `id`.
|
||||
|
||||
### Levels
|
||||
#### Levels
|
||||
|
||||
To set the level for each log line, add a `level` field.
|
||||
|
||||
@ -119,7 +126,7 @@ frame.add({ time: 1589189388597, content: 'user registered', level: 'info' });
|
||||
frame.add({ time: 1589189406480, content: 'unknown error', level: 'error' });
|
||||
```
|
||||
|
||||
### Unique log lines
|
||||
#### 'id' for assigning unique identifiers to log lines
|
||||
|
||||
By default, Grafana offers basic support for deduplicating log lines. You can improve the support by adding an `id` field to explicitly assign identifiers to each log line.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user