> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bronto.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana Plugin

> Install the Bronto data source plugin and query your Bronto log data from Grafana dashboards and Explore.

## Overview

The Bronto data source plugin lets you search Bronto log data from inside Grafana, without leaving the dashboards your team already uses. Once connected you can:

* Search log events with Bronto's SQL-style filter syntax, rendered in Grafana's Logs panel and Explore, with a log volume histogram.
* Aggregate with functions such as `count(*)` and `avg(response_time_ms)` and plot the result as a time series.
* Group by one or more fields to break an aggregation into a multi-series graph.
* Query multiple datasets at once from a searchable picker grouped by collection.

The plugin covers log data only. Traces and metrics are not queryable through it today.

<Warning>
  This guide is for self-managed Grafana. The plugin is distributed as a zip file rather than through the Grafana plugin catalog, so Grafana treats it as an unsigned plugin and you have to allow it explicitly. Grafana Cloud does not load unsigned plugins. If you run Grafana Cloud, contact Bronto support.
</Warning>

## Prerequisites

* Grafana 12.3.0 or later, self-managed. Check your version from the help menu in Grafana, or run `grafana server -v` on the server.
* Administrator access to the Grafana host, so you can write to the plugin directory and edit `grafana.ini`. For containerized deployments, access to the compose file or Helm values is enough.
* Network egress from the Grafana server to Bronto. The plugin's backend, not your browser, calls the Bronto API, so the Grafana host must reach `api.<REGION>.bronto.io` on port 443.
* A Bronto API key with the Search role. Creating one requires the Admin role in Bronto. See [API Keys](/Account-Management/API-Keys).

Your Bronto API base URL depends on your account's region:

| Region | API base URL               |
| ------ | -------------------------- |
| EU     | `https://api.eu.bronto.io` |
| US     | `https://api.us.bronto.io` |

## Step 1: Download and verify the plugin

1. Open the [releases page](https://github.com/bronto-community/bronto-grafana-datasource/releases) and find the latest release.
2. Download the plugin archive and its checksum. Take the `brontoio-bronto-datasource-<VERSION>.zip` asset, not the "Source code" archives.

```bash theme={"dark"}
curl -LO https://github.com/bronto-community/bronto-grafana-datasource/releases/download/v1.0.0/brontoio-bronto-datasource-1.0.0.zip
curl -LO https://github.com/bronto-community/bronto-grafana-datasource/releases/download/v1.0.0/brontoio-bronto-datasource-1.0.0.zip.sha1
```

Confirm the archive matches its published checksum:

```bash theme={"dark"}
sha1sum brontoio-bronto-datasource-1.0.0.zip   # on macOS: shasum
cat brontoio-bronto-datasource-1.0.0.zip.sha1
```

The two values should be identical.

## Step 2: Install the plugin

Pick the path that matches how you run Grafana.

<Tabs>
  <Tab title="Linux or macOS package">
    Grafana loads plugins from the directory set by `plugins` under `[paths]` in `grafana.ini`, or by the `GF_PATHS_PLUGINS` environment variable. The defaults are `/var/lib/grafana/plugins` on Linux and `/usr/local/var/lib/grafana/plugins` on macOS.

    The archive already contains a top-level `brontoio-bronto-datasource/` folder, so extract it into the plugin directory itself:

    ```bash theme={"dark"}
    sudo unzip brontoio-bronto-datasource-1.0.0.zip -d /var/lib/grafana/plugins/
    sudo chown -R grafana:grafana /var/lib/grafana/plugins/brontoio-bronto-datasource
    ```

    The second command matters: files extracted as `root` are often unreadable by the account Grafana runs under.

    ### Alternative: install with the Grafana CLI

    The Grafana CLI can fetch and unpack the archive for you:

    ```bash theme={"dark"}
    sudo grafana cli --pluginUrl https://github.com/bronto-community/bronto-grafana-datasource/releases/download/v1.0.0/brontoio-bronto-datasource-1.0.0.zip plugins install brontoio-bronto-datasource
    ```

    If `grafana` is not on your `PATH`, call it by full path: `/usr/share/grafana/bin/grafana` on Linux.
  </Tab>

  <Tab title="Docker">
    Have Grafana install the plugin from the release URL on startup, and allow it in the same place. In `docker-compose.yaml`:

    ```yaml theme={"dark"}
    services:
      grafana:
        image: grafana/grafana:latest
        environment:
          GF_PLUGINS_PREINSTALL_SYNC: brontoio-bronto-datasource@1.0.0@https://github.com/bronto-community/bronto-grafana-datasource/releases/download/v1.0.0/brontoio-bronto-datasource-1.0.0.zip
          GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS: brontoio-bronto-datasource
    ```

    `GF_PLUGINS_PREINSTALL_SYNC` takes the format `<plugin ID>@<version>@<zip URL>`.

    If you would rather not download at startup, extract the archive on the host and mount it at `/var/lib/grafana/plugins/brontoio-bronto-datasource` instead, keeping the `GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS` variable.
  </Tab>

  <Tab title="Kubernetes and Helm">
    With the Grafana Helm chart, add the release URL to `plugins` and allow the plugin in `grafana.ini`:

    ```yaml theme={"dark"}
    plugins:
      - https://github.com/bronto-community/bronto-grafana-datasource/releases/download/v1.0.0/brontoio-bronto-datasource-1.0.0.zip;brontoio-bronto-datasource

    grafana.ini:
      plugins:
        allow_loading_unsigned_plugins: brontoio-bronto-datasource
    ```

    The `;brontoio-bronto-datasource` suffix tells the chart which plugin ID the archive contains. Once both values are set, skip to Step 4.
  </Tab>
</Tabs>

## Step 3: Allow the unsigned plugin

Grafana refuses to load unsigned plugins unless you name them explicitly. Add the plugin ID to `grafana.ini`:

```ini theme={"dark"}
[plugins]
allow_loading_unsigned_plugins = brontoio-bronto-datasource
```

If you already allow other unsigned plugins, add this one to the existing comma-separated list. The environment variable equivalent is:

```bash theme={"dark"}
GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=brontoio-bronto-datasource
```

## Step 4: Restart Grafana

```bash theme={"dark"}
sudo systemctl restart grafana-server
```

For containers, restart the container or roll the pod. A configuration reload is not enough: Grafana scans for plugins at startup.

## Step 5: Confirm the plugin loaded

1. Sign in to Grafana as an administrator.
2. Go to **Administration > Plugins and data > Plugins** and search for Bronto.
3. Grafana shows the plugin with an unsigned signature status. That is expected, and the server log records it:

```text theme={"dark"}
level=warn msg="Plugin is unsigned" id=brontoio-bronto-datasource
level=warn msg="Permitting unsigned plugin. This is not recommended" pluginId=brontoio-bronto-datasource
```

If the plugin is missing entirely, see [Troubleshooting](#troubleshooting).

## Step 6: Create a Bronto API key

<Steps>
  <Step title="Open Settings > API Keys in Bronto" />

  <Step title="Select Create a new API Key" />

  <Step title="Name the key, for example grafana-datasource" />

  <Step title="Select the Search role">
    The plugin only reads: it calls Bronto's search, dataset and field-name endpoints. The Search role covers all three and grants no write access. The Admin role also works but is broader than the plugin needs, and the Ingestion role does not work at all.
  </Step>

  <Step title="Select Create Key, then copy the key">
    Bronto displays the key once. If you lose it, create a new one.
  </Step>
</Steps>

## Step 7: Add the Bronto data source

1. In Grafana, go to **Connections > Data sources > Add new data source**.
2. Search for and select **Bronto**.
3. Fill in the connection settings:
   * **Base URL** - the API base URL for your region, with no trailing slash, for example `https://api.<REGION>.bronto.io`.
   * **API Key** - the key from Step 6. Grafana stores it encrypted on the server and never returns it to the browser.
4. Select **Save & test**. On success Grafana reports `Successfully connected to Bronto`.

### Provisioning the data source as code

To create the data source from a provisioning file instead of the UI, add it under `provisioning/datasources/`:

```yaml theme={"dark"}
apiVersion: 1

datasources:
  - name: Bronto
    type: brontoio-bronto-datasource
    access: proxy
    isDefault: false
    orgId: 1
    version: 1
    editable: true
    jsonData:
      baseUrl: "https://api.<REGION>.bronto.io"
    secureJsonData:
      apiKey: "<YOUR_API_KEY>"
```

## Run your first query

Open Explore, select the Bronto data source, and use the query editor:

| Field       | What it does                                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Dataset     | One or more datasets to search, grouped by collection. At least one is required.                                                        |
| Query       | A where-style filter, for example `@status = 'error' AND service = 'checkout'`. Leave it empty to return every event in the time range. |
| Aggregation | An optional select expression such as `count(*)` or `avg(response_time_ms)`.                                                            |
| Group By    | Optional fields to split an aggregation by, producing one series per group.                                                             |

The Aggregation field decides what comes back. Leave it empty and the query returns log events, best viewed as Logs or in Explore. Set it and the query returns a time series you can plot on a graph panel.

Filters support `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, `NOT`, `LIKE` and `IN`. Press **Ctrl+Space** in the Query field for field, operator and keyword suggestions drawn from the datasets you selected. For the full syntax, see [Search Syntax](/query-syntax/search-syntax).

A first query worth running: select one dataset, leave Query and Aggregation empty, and set the time range to the last 15 minutes. You should see recent events and a volume histogram. Then set Aggregation to `count(*)` to turn the same query into a time series, and add a Group By field such as `service` to split it.

## Upgrading and removing

Because the plugin is installed by hand rather than from the Grafana catalog, it does not update itself.

To upgrade, delete the existing plugin folder, extract the new release in its place, and restart Grafana. Your data sources and dashboards are unaffected, since they reference the plugin by ID.

```bash theme={"dark"}
sudo rm -rf /var/lib/grafana/plugins/brontoio-bronto-datasource
sudo unzip brontoio-bronto-datasource-<NEW_VERSION>.zip -d /var/lib/grafana/plugins/
sudo chown -R grafana:grafana /var/lib/grafana/plugins/brontoio-bronto-datasource
sudo systemctl restart grafana-server
```

To remove the plugin, delete any Bronto data sources in **Connections > Data sources**, delete the plugin folder, remove the plugin ID from `allow_loading_unsigned_plugins`, and restart. Panels that queried a deleted data source keep their configuration but return an error until they are pointed elsewhere.

## Current limitations

* Log data only. Bronto traces and metrics cannot be queried through the plugin.
* Not in the Grafana plugin catalog, so it cannot be installed from the Grafana UI, does not auto-update, and is not available on Grafana Cloud.
* Supported platforms: Linux (x86-64, arm64, arm), macOS (x86-64, Apple silicon) and Windows (x86-64). There is no 32-bit x86 or Windows arm64 build.

## Troubleshooting

### Bronto does not appear when you add a data source

The plugin did not load. Confirm the plugin ID in `allow_loading_unsigned_plugins` reads exactly `brontoio-bronto-datasource`, that the folder sits directly inside the plugin directory (`/var/lib/grafana/plugins/brontoio-bronto-datasource/plugin.json` should exist), and that Grafana was fully restarted rather than reloaded.

### Save & test returns "Failed to connect to Bronto"

The Grafana server could not reach the Bronto API. Check that the Base URL starts with `https://`, names the right region, and has no trailing slash, then confirm the Grafana host itself can reach it:

```bash theme={"dark"}
curl -I https://api.<REGION>.bronto.io
```

If your network requires an outbound proxy, Grafana's backend must be configured to use it.

### Save & test returns "Bronto returned HTTP 401" or "403"

The key is wrong, was revoked, or lacks read access. Create a fresh key with the Search role and paste it again, checking for leading or trailing whitespace.

### Queries return "at least one dataset is required"

Select at least one dataset in the query editor's Dataset field.

### The plugin appears but queries fail, and the log mentions gpx\_bronto

The backend process could not start. Check the Grafana log (`/var/log/grafana/grafana.log` by default) and confirm the plugin files are owned by the account Grafana runs as, that the backend binary is executable, and that your platform is on the supported list above.

Archives expanded by tools that discard file permissions, such as PowerShell's `Expand-Archive`, produce a non-executable binary. Re-extract with a tool that preserves them, or restore the permission with `chmod +x`.

### A query returns no data even though the dataset has events

Widen the Grafana time range, and confirm in Bronto's own search that the dataset has events in that window.