Skip to content

Docs: Logs data sources #2497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
urbiz-grafana wants to merge 3 commits into from
Closed

Docs: Logs data sources #2497

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9edffb5
Tweaks
urbiz-grafana Feb 27, 2026
09889b1
WIP
urbiz-grafana Mar 2, 2026
cf31701
Merge branch 'main' into urbiz-logs-explore
urbiz-grafana Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 26 additions & 25 deletions docusaurus/docs/tutorials/build-a-logs-data-source-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,31 @@ Grafana data source plugins support metrics, logs, and other data types. The ste

## Before you begin

This guide assumes that you're already familiar with how to [Build a data source plugin](./build-a-data-source-plugin.md) for metrics. We recommend that you review this material before continuing.
This guide assumes that you're already familiar with how to [Build a data source plugin](./build-a-data-source-plugin.md) for metrics. Review this material before proceeding with this guide.

## Add logs support to your data source

To add logs support to an existing data source, you need to:
To add logs support to an existing data source:

1. Enable logs support
1. Construct the log data frame
1. [Enable logs support](#enable-logs-support)
1. [Build the log data frame](#build-the-log-data-frame)
1. Optionally, you can improve the user experience with one or more [optional features](#enhance-your-logs-data-source-plugin-with-optional-features).

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).
## Enable logs support

### Step 1: Enable logs support

Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json](../reference/metadata.md) file.
Add `"logs": true` to the [plugin.json](../reference/metadata.md) file to tell Grafana that your data source plugin can return log data:

```json title="src/plugin.json"
{
"logs": true
}
```

### Step 2: Construct the log data frame
## Build the log data frame

### Logs data frame format
Grafana supports a variety of different data sources. To make this possible, Grafana consolidates the query results from each of these data sources into one unified data structure called a _data frame_, a collection of fields organized as columns. Each field, in turn, consists of a collection of values and metadata. Learn more in [Data frames](../key-concepts/data-frames).

The log data frame should include following fields:
The _log data frame_ can include following fields:

| Field name | Field type | Required field | Description |
| ------------- | ----------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -55,7 +54,7 @@ The log data frame should include following fields:

Logs data frame's `type` needs to be set to `type: DataFrameType.LogLines` in data frame's meta.

**Example of constructing a logs data frame in Go:**
### Example: Build a logs data frame in Go

```go
frame := data.NewFrame(
Expand All @@ -72,7 +71,7 @@ frame.SetMeta(&data.FrameMeta{
})
```

**Example of constructing a logs data frame in TypeScript:**
### Example: Build a logs data frame in Go TypeScript

```ts
import { createDataFrame, DataFrameType, FieldType } from '@grafana/data';
Expand All @@ -99,9 +98,7 @@ const result = createDataFrame({

You can use the following optional features to enhance your logs data source plugin in the Explore and Logs panel.

[Explore](https://grafana.com/docs/grafana/latest/explore/) provides a useful interface for investigating incidents and troubleshooting logs. If the data source produces log results, we highly recommend implementing the following APIs to allow your users to get the most out of the logs UI and its features within Explore.

The following steps show the process for adding support for Explore features in a data source plugin through a seamless integration. Implement these APIs to enhance the user experience and take advantage of Explore's powerful log investigation capabilities.
[Explore](https://grafana.com/docs/grafana/latest/explore/) provides a useful interface for investigating incidents and troubleshooting logs. If your data source produces log results, you can implement the following APIs to allow your users to get the most out of the logs UI and its features within Explore.

### Show log results in Explore's Logs view

Expand All @@ -128,11 +125,15 @@ const result = createDataFrame({
});
```

### Order logs in Explore view

TBC

### Highlight searched words

:::note

This feature must be implemented in the data frame as a meta attribute.
Implement this feature in the data frame as a meta attribute.

:::

Expand Down Expand Up @@ -167,15 +168,15 @@ const result = createDataFrame({

:::note

This feature must be implemented in the data frame as a meta attribute, or in the data frame as a field.
Implement this feature in the data frame as a meta attribute or as a field.

:::

[Log result meta information](https://grafana.com/docs/grafana/latest/explore/logs-integration/#log-result-meta-information) can be used to communicate information about logs results to the user. The following information can be shared with the user:

- **Count of received logs vs limit** - Displays the count of received logs compared to the specified limit. Data frames should set a limit with a meta attribute for the number of requested log lines.
- **Count of received logs vs limit**: Displays the count of received logs compared to the specified limit. Data frames should set a limit with a meta attribute for the number of requested log lines.
- **Error**: Displays possible errors in your log results. Data frames should to have an `error` in the `meta` attribute.
- **Common labels**: Displays labels present in the `labels` data frame field that are the same for all displayed log lines. This feature is supported for data sources that produce log data frames with an labels field. Refer to [Logs data frame format](#logs-data-frame-format) for more information.
- **Common labels**: Displays labels present in the `labels` data frame field that are the same for all displayed log lines. This feature is supported for data sources that produce log data frames with an labels field. Refer to [Logs data frame format](#build-the-log-data-frame) for more information.

**Example in Go:**

Expand Down Expand Up @@ -204,7 +205,7 @@ const result = createDataFrame({
});
```

### Logs to trace using data link with URL
### Logs with trace IDs

If your log data contains **trace IDs**, you can enhance your log data frames by adding a field with _trace ID values_ and _URL data links_. These links should use the trace ID value to accurately link to the appropriate trace. This enhancement enables users to seamlessly move from log lines to the relevant traces.

Expand Down Expand Up @@ -238,7 +239,7 @@ const result = createDataFrame({

:::note

This feature must be implemented in the data frame as a field.
Implement this feature in the data frame as a field.

:::

Expand All @@ -250,7 +251,7 @@ Refer to [Logs data frame format](#logs-data-frame-format) for more information.

:::note

This feature must be implemented in the data frame as a field.
Implement this feature in the data frame as a field.

:::

Expand All @@ -260,7 +261,7 @@ If the underlying database doesn't return an `id` field, you can implement one w

Refer to [Logs data frame format](#logs-data-frame-format) for more information.

### Filter fields using Log details
### Filter fields using log details

:::note

Expand Down Expand Up @@ -302,7 +303,7 @@ export class ExampleDatasource extends DataSourceApi<ExampleQuery, ExampleOption

:::note

Implement this feature data source method and enabled in `plugin.json`
Implement this feature as a data source method and enabled it in `plugin.json`.

:::

Expand Down
Loading