---
title: "Edelbyte Datasource plugin for Grafana"
description: "Grafana data source for Edelbyte. Edelbyte Datasource plugin for Grafana by Edelbyte. Available in Grafana Cloud and self-managed Grafana."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/edelbyte-kql-datasource/

# Edelbyte Datasource

- Developer: Edelbyte
- Version: 0.7.4
- [Installation](https://grafana.com/grafana/plugins/edelbyte-kql-datasource/installation.md)
- [Change log](https://grafana.com/grafana/plugins/edelbyte-kql-datasource/changelog.md)

![Data source configuration](https://grafana.com/api/plugins/edelbyte-kql-datasource/versions/0.7.4/images/img/screenshots/config-editor.png)

![Sample dashboard](https://grafana.com/api/plugins/edelbyte-kql-datasource/versions/0.7.4/images/img/screenshots/dashboard.png)

# Edelbyte data source for Grafana

[Edelbyte](https://edelbyte.io/) is the unified data platform for any data challenge, from search and analytics to AI applications, with an architecture designed from the ground up to make real-time performance practical and cost-efficient at scale. It runs in any cloud, self-hosted or on-premises, and queries data where it lives.

This plugin connects Grafana to an Edelbyte cluster, so you can query it from any panel, from Explore, and from alert rules. Edelbyte is queried in Kusto Query Language (KQL) or PostgreSQL-compatible SQL. This data source uses the KQL endpoint; teams working in SQL can reach the same cluster through Grafana's built-in PostgreSQL data source, and both can sit side by side on one dashboard.

You do not need to know KQL to get started. The visual query builder composes the query for you from a table, filters and aggregations, and the KQL editor completes table and column names from your cluster's schema and marks errors as you type.

## What you can do

- Visualize query results as tables, time series, logs or traces.
- Build alert rules and annotations on queries against your cluster.
- Drive dashboards with template variables backed by queries.
- Compose queries in the visual builder, or write them directly in the KQL editor.
- Mix this data source with Grafana's PostgreSQL data source on the same dashboard when some panels are written in SQL.
- Authenticate with OAuth2 client credentials from Microsoft Entra ID or Amazon Cognito, or with an AWS IAM role.

## Requirements

- Grafana 11.6.11 or later, self-managed or Grafana Cloud.
- An Edelbyte cluster reachable over HTTPS from the Grafana server.
- An identity for the data source with the Viewer role on the cluster or on the databases you want to query.

## Installation

**Grafana Cloud:** open **Administration > Plugins and data**, search for _Edelbyte_, and click **Install**.

**Grafana CLI:**

```sh
grafana cli plugins install edelbyte-kql-datasource
```

Restart Grafana after the install.

## Configuration

Open **Connections > Data sources > Add new data source** and choose **Edelbyte Datasource**.

### Cluster URL

| Field                  | Description                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| **Cluster URL**        | HTTPS URL of your cluster, for example `https://cluster.edelbyte.cloud` |
| **Trust cluster host** | Only for a cluster on a custom domain, see below                        |

The plugin sends access tokens only to hosts under the Edelbyte domains (`.edelbyte.cloud`, `.edelbyte.dev`). If your cluster runs on a custom domain such as `https://logs.example.com`, the connection test fails with `cluster URL host "..." is not a trusted Edelbyte domain`. Enable **Trust cluster host** to trust that one host, and only that host, for this data source. Enable it only for a domain you control.

### Authentication

Pick an **Auth Type**. The remaining fields depend on it.

| Auth Type                     | `authType`          | Use when                                                                                                         | Fields                                                           |
| ----------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Client Credentials (OIDC)** | `clientcredentials` | You have a client ID and secret from Microsoft Entra ID or Amazon Cognito. This is the option for Grafana Cloud. | Issuer URL, Client ID, Client Secret                             |
| **AWS IAM Role**              | `awsiam`            | Grafana runs under an AWS IAM role (EC2, ECS, Fargate, EKS) and the cluster accepts AWS identities               | AWS Region, Audience, optionally Assume Role ARN and External ID |

**Client Credentials (OIDC).** The plugin discovers the token endpoint from `{issuerUrl}/.well-known/openid-configuration` and the OAuth scope from the cluster's protected-resource document ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)). You do not configure a scope or audience. Issuer URLs:

| Identity provider  | Issuer URL                                                |
| ------------------ | --------------------------------------------------------- |
| Microsoft Entra ID | `https://login.microsoftonline.com/{tenantId}/v2.0`       |
| Amazon Cognito     | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}` |

**AWS IAM Role.** Credentials come from the AWS SDK default credential chain on the Grafana host (task role, instance role, IRSA), so no secrets are stored in Grafana. Only temporary, session-based credentials are accepted. **Audience** must match the audience configured on the cluster, and **AWS Region** must be the region you sign in. Set **Assume Role ARN** to have the plugin call `sts:AssumeRole` first; **External ID** is passed through when the role's trust policy requires it. The optional access key fields are for environments where no ambient credentials reach the plugin process; leave them empty in production.

Secrets are stored in Grafana's encrypted secure JSON data.

### Additional settings

| Field                   | Description                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| **Default database**    | Preselected database in the query editor                                                             |
| **Query timeout**       | Client-side timeout per query, up to one hour                                                        |
| **Use dynamic caching** | Caches each query for as long as its time bucket (`bin` size)                                        |
| **Cache max age**       | Fixed cache lifetime when dynamic caching is off                                                     |
| **Default editor mode** | `Builder` or `KQL`                                                                                   |
| **OpenAI API key**      | Optional. Enables the query generator, see [Data sent to third parties](#data-sent-to-third-parties) |

Click **Save & test**. The test resolves the cluster, authenticates and lists the databases the identity can see.

### Provisioning

The same settings can be provisioned from YAML. Minimal Client Credentials (OIDC) example:

```yaml
apiVersion: 1
datasources:
  - name: Edelbyte
    type: edelbyte-kql-datasource
    access: proxy
    jsonData:
      clusterUrl: https://cluster.edelbyte.cloud
      defaultDatabase: Telemetry
      authType: clientcredentials
      oidcIssuerUrl: https://login.microsoftonline.com/{tenantId}/v2.0
      oidcClientId: {clientId}
    secureJsonData:
      clientSecret: {clientSecret}
```

For a cluster on a custom domain add `trustClusterHost: true` to `jsonData`. For AWS IAM Role set `authType: awsiam` with `awsIamRegion`, `awsIamAudience` and optionally `awsIamAssumeRoleArn` and `awsIamExternalId`.

## Querying

Select the **Database** and the **Format** in the query header, then write KQL or switch to **Builder**.

| Format          | Use for                                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table**       | Any result shape, table panels, stat panels                                                                                                                                       |
| **Time series** | Graphs. The result needs a `datetime` column and at least one numeric column                                                                                                      |
| **Logs**        | The Logs view in Explore and logs panels                                                                                                                                          |
| **Trace**       | The Trace view in Explore. The result must follow Grafana's [trace data frame structure](https://grafana.com/docs/grafana/latest/explore/trace-integration/#data-frame-structure) |

Time series:

```kql
Requests
| where $__timeFilter(Timestamp)
| summarize count() by bin(Timestamp, $__timeInterval), Region
| order by Timestamp asc
```

Table:

```kql
Requests
| where $__timeFilter(Timestamp) and StatusCode >= 500
| project Timestamp, Region, StatusCode, Path, DurationMs
| order by Timestamp desc
```

### Macros

| Macro                            | Expands to                                                                                                |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `$__timeFilter(column)`          | `column >= datetime(<from>) and column <= datetime(<to>)` for the dashboard time range                    |
| `$__timeFrom`                    | `datetime(<from>)`                                                                                        |
| `$__timeTo`                      | `datetime(<to>)`                                                                                          |
| `$__timeInterval`                | The panel interval as a timespan, for example `5000ms`, for use in `bin()`                                |
| `$__contains(column, $variable)` | `column in ('a', 'b')` for a multi-value variable. With the custom all value `all` it expands to `1 == 1` |

### Template variables

Create a variable of type **Query**, pick the Edelbyte data source, and write a query that returns one column:

```kql
Requests | distinct Region
```

`databases()` returns the list of databases. Use the variable in a query with `where Region == '$region'`, or for multi-value variables `where Region in ($region)` or `$__contains(Region, $region)`.

### Query builder

The builder lets you pick a table, add type-aware filters, aggregate and group (including time buckets), and expand `dynamic` columns into their properties from a sample of the data. Switch to the KQL editor at any time to see and edit the generated query.

### Annotations

An annotation query returns a `Timestamp` column (datetime), a `Text` column (string) and optionally `Tags` (comma-separated string):

```kql
Deployments
| where $__timeFilter(Timestamp)
| project Timestamp, Text = strcat(Service, " ", Version), Tags = "deploy"
```

### Alerting

Alert rules work with any query in **Table** or **Time series** format. Use `$__timeFilter` so the rule evaluates the configured window.

## Data sent to third parties

The plugin sends data to the cluster you configure and nowhere else, with two optional exceptions that only apply when you use them:

- **Generate query** (OpenAI editor mode) sends your prompt, with a fixed KQL instruction, to OpenAI (`api.openai.com`) using the **OpenAI API key** from the data source settings, or to the provider configured in the Grafana LLM app when that app is enabled.
- **Explain KQL** sends the KQL text of the current query, with a fixed instruction, to the Grafana LLM app and its configured provider.

Nothing is sent until you click one of these buttons. Query results and schema are never sent. Leave the API key empty and the LLM app disabled to turn both features off. The plugin collects no usage statistics.

## Troubleshooting

| Symptom                                  | Check                                                                                                           |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Save & test** fails                    | The cluster URL starts with `https://`; the identity provider and cluster are reachable from the Grafana server |
| `not a trusted Edelbyte domain`          | The cluster runs on a custom domain. Enable **Trust cluster host**                                              |
| No databases in the dropdown             | The data source identity lacks the Viewer role on the cluster or databases                                      |
| Panel says the data is not a time series | The query returns no `datetime` column or no numeric column. Switch to **Table** to inspect the result          |
| AWS IAM Role: credentials not found      | The Grafana host has no task, instance or pod role; or the audience does not match the cluster's configuration  |

## Links

- [Edelbyte](https://edelbyte.io/)
- [Source code and issues](https://github.com/edelbyte-io/edelbyte-grafana-datasource)
- [Changelog](https://github.com/edelbyte-io/edelbyte-grafana-datasource/blob/main/CHANGELOG.md)
- [Apache License 2.0](https://github.com/edelbyte-io/edelbyte-grafana-datasource/blob/main/LICENSE)
