Grafana Plugin

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.

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.

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.

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

Open the releases page and find the latest release.
Download the plugin archive and its checksum. Take the brontoio-bronto-datasource-<VERSION>.zip asset, not the “Source code” archives.

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:

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.

Linux or macOS package
Docker
Kubernetes and Helm

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:

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:

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.

Have Grafana install the plugin from the release URL on startup, and allow it in the same place. In docker-compose.yaml:

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.

With the Grafana Helm chart, add the release URL to plugins and allow the plugin in grafana.ini:

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.

Step 3: Allow the unsigned plugin

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

[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:

GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=brontoio-bronto-datasource

Step 4: Restart Grafana

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

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

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.

Step 6: Create a Bronto API key

Open Settings > API Keys in Bronto

Select Create a new API Key

Name the key, for example grafana-datasource

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.

Select Create Key, then copy the key

Bronto displays the key once. If you lose it, create a new one.

Step 7: Add the Bronto data source

In Grafana, go to Connections > Data sources > Add new data source.
Search for and select Bronto.
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.
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/:

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. 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.

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:

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.

Get started

Changelog

Tracing

Metrics

Search

Query syntax

Visualize

Monitors and alerting

Notification channels

My Data

Account and security

SSO

Reference

Overview

Prerequisites

Step 1: Download and verify the plugin

Step 2: Install the plugin

Alternative: install with the Grafana CLI

Step 3: Allow the unsigned plugin

Step 4: Restart Grafana

Step 5: Confirm the plugin loaded

Step 6: Create a Bronto API key

Step 7: Add the Bronto data source

Provisioning the data source as code

Run your first query

Upgrading and removing

Current limitations

Troubleshooting

Bronto does not appear when you add a data source

Save & test returns “Failed to connect to Bronto”

Save & test returns “Bronto returned HTTP 401” or “403”

Queries return “at least one dataset is required”

The plugin appears but queries fail, and the log mentions gpx_bronto

A query returns no data even though the dataset has events

​Overview

​Prerequisites

​Step 1: Download and verify the plugin

​Step 2: Install the plugin

​Alternative: install with the Grafana CLI

​Step 3: Allow the unsigned plugin

​Step 4: Restart Grafana

​Step 5: Confirm the plugin loaded

​Step 6: Create a Bronto API key

​Step 7: Add the Bronto data source

​Provisioning the data source as code

​Run your first query

​Upgrading and removing

​Current limitations

​Troubleshooting

​Bronto does not appear when you add a data source

​Save & test returns “Failed to connect to Bronto”

​Save & test returns “Bronto returned HTTP 401” or “403”

​Queries return “at least one dataset is required”

​The plugin appears but queries fail, and the log mentions gpx_bronto

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

Overview

Prerequisites

Step 1: Download and verify the plugin

Step 2: Install the plugin

Alternative: install with the Grafana CLI

Step 3: Allow the unsigned plugin

Step 4: Restart Grafana

Step 5: Confirm the plugin loaded

Step 6: Create a Bronto API key

Step 7: Add the Bronto data source

Provisioning the data source as code

Run your first query

Upgrading and removing

Current limitations

Troubleshooting

Bronto does not appear when you add a data source

Save & test returns “Failed to connect to Bronto”

Save & test returns “Bronto returned HTTP 401” or “403”

Queries return “at least one dataset is required”

The plugin appears but queries fail, and the log mentions gpx_bronto

A query returns no data even though the dataset has events