--- title: "Grafana Integration" slug: "grafana-integration" updated: 2026-07-06T15:13:50Z published: 2026-07-06T15:13:50Z canonical: "docs.catchpoint.com/grafana-integration" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.catchpoint.com/llms.txt > Use this file to discover all available pages before exploring further. # Grafana Integration 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 1. Log in to the Catchpoint portal. 2. Navigate to Settings → API. 3. 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 1. In Grafana, go to Administration → Plugins and search for "Catchpoint". 2. 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 1. Go to Connections → Data sources → Add data source and choose Catchpoint. 2. Enter a name for the data source instance. 3. Paste the REST API v2 key into the Bearer Token field. 4. 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: ### 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)://:/catchpoint-webhook. ### Step 2 — Configure the Test Data Webhook in Catchpoint 1. In the Catchpoint portal, navigate to Settings → API → Test Data Webhooks and click "Add URL". 2. Set the URL to your exporter endpoint, e.g. http://:9090/catchpoint-webhook. 3. Add the template JSON to select which metrics the webhook sends (Grafana's integration documentation provides the template file). 4. Enable the Test Data Webhook per test: in Control Center → Tests, open the test's Product Properties and enable the webhook, selecting your template. 5. 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: [':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__ = ":", }] 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