Catchpoint + Grafana Integration Guide
Two supported approaches to visualize Catchpoint data in Grafana
This guide covers the two officially supported methods for bringing Catchpoint monitoring data into Grafana dashboards:
Approach 1 — Pull: the Catchpoint data source plugin for Grafana, which queries the Catchpoint REST API directly (no additional infrastructure).
Approach 2 — Push: Catchpoint Test Data Webhooks streaming results into a time-series database (Prometheus) via the Catchpoint Prometheus exporter or Grafana Alloy, with Grafana querying the TSDB.
At-a-Glance Comparison
Approach 1: Data Source Plugin (Pull) | Approach 2: Webhook → TSDB (Push) | |
|---|---|---|
Grafana edition | Grafana Cloud or Grafana Enterprise (min. v11.6.7); | Any edition, including OSS Grafana |
Infrastructure required | None — plugin calls the Catchpoint REST API | Exporter endpoint reachable by Catchpoint + Prometheus (or Grafana Cloud via Alloy) |
Data available | Tests, RUM, and SLO data via query editor | 40+ test metrics (DNS time, response time, load time, errors, content types) for webhook-enabled tests |
Historical data | Immediately queryable, subject to Catchpoint data retention | Collected from webhook enablement onward (no backfill); retention controlled by your TSDB |
Data ownership | Data remains in Catchpoint; queried on demand | Data stored in your own TSDB; full control of retention and alerting |
Recommendation: if you run Grafana Cloud or Grafana Enterprise, start with the data source plugin — it is the fastest path with zero infrastructure. Choose the webhook/TSDB approach if you run OSS Grafana, need long-term retention under your control, or want Prometheus-native alerting on Catchpoint metrics.
Approach 1 — Catchpoint Data Source Plugin (Pull)
The Catchpoint data source plugin is developed by Grafana Labs and queries the Catchpoint REST API v2 using bearer-token authentication. It supports querying Tests, RUM (Real User Monitoring), and SLO data directly from Grafana panels.
Prerequisites
An active Catchpoint account with REST API access.
Grafana Cloud (any plan) or a Grafana Enterprise license (self-managed).
Grafana version 11.6.7 or later.
Note: support is provided through your Grafana Enterprise support channel.
Step 1 — Obtain the Catchpoint REST API v2 key
Log in to the Catchpoint portal.
Navigate to Settings → API.
In the REST API section, locate the "REST API v2 Key". Copy this key — it is used as the bearer token in Grafana.
Step 2 — Install the plugin
In Grafana, go to Administration → Plugins and search for "Catchpoint".
Select the Catchpoint data source plugin (grafana-catchpoint-datasource) and click Install.
Installation can also be automated via the Grafana Cloud API or Terraform for managed environments.
Step 3 — Configure the data source
Go to Connections → Data sources → Add data source and choose Catchpoint.
Enter a name for the data source instance.
Paste the REST API v2 key into the Bearer Token field.
Click Save & Test.
For provisioning-as-code environments, the data source can be provisioned via YAML:
apiVersion: 1
datasources:
- name: Catchpoint
type: grafana-catchpoint-datasource
jsonData:
authMethod: bearer
secureJsonData:
catchpoint.token: <your REST API v2 key>
Step 4 — Query data in dashboards
The query editor offers three query types:
Tests — synthetic test performance metrics. Select the action type and provide the required and optional parameters.
RUM — Real User Monitoring data.
SLO — Service Level Objective status and tracking.
The plugin also supports Grafana Explore, query variables (for templated dashboards), annotations, transformations, and Grafana alerting.
Approach 2 — Test Data Webhook → TSDB → Grafana (Push)
In this model, Catchpoint pushes test results in near-real time via its Test Data Webhook to an exporter, which exposes the results as Prometheus metrics. Prometheus (or Grafana Alloy remote-writing to Grafana Cloud) stores the data, and Grafana visualizes it. You own the data, its retention, and alerting.
Data flow: Catchpoint Test Data Webhook → Catchpoint Prometheus exporter → Prometheus / Grafana Cloud Metrics → Grafana dashboards & alerts
Prerequisites
A host (VM or container platform) to run the exporter, with an HTTPS/HTTP endpoint reachable from Catchpoint's infrastructure.
A Prometheus server (self-managed) or Grafana Cloud with Grafana Alloy.
Admin access to the Catchpoint portal to configure Test Data Webhooks.
Step 1 — Run the Catchpoint Prometheus exporter
Grafana maintains an official exporter (github.com/grafana/catchpoint-prometheus-exporter). Build and run it:
go build -o catchpoint-exporter ./cmd/catchpoint-exporter/main.go
./catchpoint-exporter --port="9090" --webhook-path="/catchpoint-webhook" --verbosity
Configuration options (flags or environment variables):
Flag | Environment variable | Default |
|---|---|---|
--port | CATCHPOINT_EXPORTER_PORT | 9090 |
--webhook-path | CATCHPOINT_WEBHOOK_PATH | /catchpoint-webhook |
--verbose | CATCHPOINT_VERBOSE | disabled |
Expose the endpoint (directly, or behind a reverse proxy / load balancer with TLS) so that Catchpoint can POST results to http(s)://<exporter-address>:<port>/catchpoint-webhook.
Step 2 — Configure the Test Data Webhook in Catchpoint
In the Catchpoint portal, navigate to Settings → API → Test Data Webhooks and click "Add URL".
Set the URL to your exporter endpoint, e.g. http://<your_exporter_address>:9090/catchpoint-webhook.
Add the template JSON to select which metrics the webhook sends (Grafana's integration documentation provides the template file).
Enable the Test Data Webhook per test: in Control Center → Tests, open the test's Product Properties and enable the webhook, selecting your template.
Review test frequency under "Targeting & Scheduling" — this determines the data-point interval that lands in Prometheus.
Step 3a — Scrape with self-managed Prometheus
Add a scrape job pointing at the exporter:
scrape_configs:
- job_name: 'catchpoint'
static_configs:
- targets: ['<exporter-address>:9090']
Then add Prometheus as a data source in Grafana (Connections → Data sources → Prometheus) and build dashboards on the Catchpoint metrics.
Step 3b — Or use Grafana Alloy + Grafana Cloud integration
If you use Grafana Cloud, install the Catchpoint integration (Connections → Add new connection → Catchpoint) and configure Alloy to scrape the exporter and remote-write to your Cloud stack:
prometheus.scrape "metrics_integrations_integrations_catchpoint" {
targets = [{
__address__ = "<catchpoint-hostname>:<catchpoint-exporter-port>",
}]
forward_to = [prometheus.remote_write.metrics_service.receiver]
job_name = "integrations/catchpoint"
}
Alloy also ships a native component, prometheus.exporter.catchpoint, which can run the exporter inside Alloy itself instead of as a separate process.
Step 4 — Dashboards and alerts
The Grafana Cloud Catchpoint integration installs pre-built content:
Dashboards: Catchpoint overview; Web performance by node; Web performance by test.
Alerts: high server response time; total time exceeded; high DNS resolution time; content loading delays; high failed-request ratio.
Metrics: 40+ series covering DNS time, connect/response/load times, error counts, and content-type breakdowns.
Alternative push variant — InfluxDB via Node-RED
Catchpoint webhook → Node-RED → InfluxDB → Grafana pipeline. Node-RED receives the Test Data Webhook, transforms the payload, and writes three measurements (test_counter, test_byte, test_timing) into InfluxDB, which Grafana queries. This is a good fit for teams already standardized on InfluxDB; otherwise the Prometheus exporter path above is recommended.
References
Catchpoint data source plugin (Grafana Labs) — https://grafana.com/grafana/plugins/grafana-catchpoint-datasource/
Plugin documentation (configuration & query editor) — https://grafana.com/docs/plugins/grafana-catchpoint-datasource/latest/
Catchpoint Prometheus exporter (GitHub) — https://github.com/grafana/catchpoint-prometheus-exporter
Grafana Cloud Catchpoint integration (dashboards, alerts, Alloy config) — https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-catchpoint/
Alloy component: prometheus.exporter.catchpoint — https://grafana.com/docs/alloy/latest/reference/components/prometheus/prometheus.exporter.catchpoint/
Catchpoint KB: Grafana Integration Guide (Node-RED + InfluxDB) — https://docs.catchpoint.com/docs/grafana-integration-guide
Catchpoint blog: Build a Grafana dashboard with Node-RED & InfluxDB — https://www.catchpoint.com/blog/node-red-influxdb-grafana