Connect and get help from 7,000+ developers on our Discord community.

Prometheus integration for BrowserStack Load Testing

Learn how to send BrowserStack Load Testing metrics to Prometheus via remote write and visualize them in Grafana alongside your application telemetry.

Use this guide to connect BrowserStack Load Testing with Prometheus and Grafana. BrowserStack pushes load-test metrics to your Prometheus instance every 10 seconds over the remote write protocol, creates a per-test Grafana dashboard for you, and posts test lifecycle events as annotations on that dashboard.

For an overview of all APM options, see Application Performance Monitoring integration.

Prerequisites

Before you start, make sure you have:

Prometheus host: A Grafana Cloud organization with Hosted Prometheus enabled, or a self-managed Cortex, Mimir, or Prometheus instance with remote write enabled.
Grafana data source: A Prometheus-typed data source already added to Grafana under Connections > Data sources. Grafana Cloud usually adds this automatically.
BrowserStack Load Testing account: Access with admin permission to at least one project.
About 10 minutes: Time to collect six credential values and paste them into BrowserStack.

Other Prometheus hosts also work:

Cortex or Mimir: Use your tenant ID as the username. The token and remote write URL flow is the same.
Self-managed Prometheus behind nginx basic auth: Use your basic-auth user as the username and your basic-auth password as the token.
Self-hosted Grafana: The fields are the same. Substitute your own URLs.

Integration overview

BrowserStack Load Testing pushes 21 standard metrics to your Prometheus instance over the remote write protocol every 10 seconds during a test run, and posts 10 lifecycle event types as Grafana dashboard annotations. Metrics live in Prometheus, and the dashboard and annotations live in Grafana.

Core capabilities:

Metric streaming: BrowserStack aggregates performance data into 10-second time windows and writes it to your Prometheus instance over HTTPS.
Auto-managed dashboard: BrowserStack creates a per-test Grafana dashboard the first time it sees metrics for that test, and keeps it in sync on subsequent runs.
Lifecycle annotations: BrowserStack posts a Grafana annotation for each test event (such as test started or ramp up started), so you can align metric changes with what happened during the run.
Scoped annotations: Annotations carry a dashboard-id:<your-dashboard-uid> tag, so events for one load test only appear on that test’s dashboard.

Supported metrics

BrowserStack pushes all 21 supported metrics automatically after you connect the Prometheus integration. You do not need to enable individual metrics.

Category	Metric name	Description
Load	`browserstack_vu_max`	Maximum virtual users in the window
Load	`browserstack_vu_started`	Virtual users that started in the window
Load	`browserstack_vu_ended`	Virtual users that ended in the window
Load	`browserstack_test_duration`	Elapsed test time
Requests	`browserstack_requests_rate_avg`	Average requests per second
Requests	`browserstack_requests_count_total`	Total requests in the window
Errors	`browserstack_errors_percentage`	Error rate as a percentage
Errors	`browserstack_errors_count_total`	Total errored requests
Response	`browserstack_response_time_avg`	Mean response time in milliseconds
Response	`browserstack_response_time_p75`	75th percentile response time
Response	`browserstack_response_time_p90`	90th percentile response time
Response	`browserstack_response_time_p95`	95th percentile response time
Response	`browserstack_response_time_p99`	99th percentile response time
Response	`browserstack_response_time_max`	Maximum response time
Browser	`browserstack_browser_lcp`	Largest Contentful Paint
Browser	`browserstack_browser_fcp`	First Contentful Paint
Browser	`browserstack_browser_plt`	Page load time
Browser	`browserstack_browser_network_calls_total`	Browser network call count
System	`browserstack_system_cpu_usage`	Engine CPU usage
System	`browserstack_system_memory_usage`	Engine memory usage
System	`browserstack_system_network_bandwidth`	Engine network bandwidth

Every metric carries these labels: test_id, dashboard_id, load_test_name, region, and executorname.

Prometheus metric names use underscores (browserstack_vu_max), not dots. Prometheus does not allow dots in metric names. BrowserStack converts the names for you. You do not need to do anything.

Lifecycle events

BrowserStack posts one Grafana annotation per lifecycle event, color-coded for quick scanning.

Event	When it fires
`test_started`	Test transitions from queued to running
`test_completed`	Test reaches a terminal success state
`test_failed`	Test reaches a terminal failure state
`test_stopped`	A user manually stops the test
`iteration_started`	A test iteration begins (iteration-based load profile only)
`iteration_ended`	A test iteration completes
`rampup_started`	The ramp-up phase begins (ramping load profile only)
`rampdown_started`	The ramp-down phase begins
`scenario_start`	A multi-scenario test enters a scenario
`scenario_end`	A multi-scenario test exits a scenario

Configure Prometheus

You can configure Prometheus from the BrowserStack UI or from the CLI. Select your preferred method:

UI Builder
CLI

Use the following steps to collect six values, three from your Prometheus instance and three from your Grafana, and paste them into the Connect form:

Open the Prometheus Connect form

To open the Connect form:

Navigate to the BrowserStack Load Testing dashboard.
Click Integrations > APM apps > Prometheus.
Click Connect.

A form opens with six fields. Keep this tab open while you collect the values in the following steps.

Get your Prometheus remote write URL, username, and token

Grafana Cloud Hosted Prometheus exposes all three Prometheus-specific values on one page. To collect them:

Sign in to grafana.com.
Open your Grafana Cloud Portal, which lists your stacks and bundled services.
Find the Prometheus card and click Details.
On the Details page, copy these three values:
- URL: This URL ends in /api/prom/push. It is your Remote Write URL.
- Username: Your instance ID, a numeric value such as 1234567.
- Password: Click Generate now to create a Cloud Access Policy token. Pick a name such as browserstack-load-testing. Copy the token immediately, since Grafana does not show it again.
Paste each value into the matching BrowserStack field:
- Prometheus Remote Write URL receives the URL.
- Username receives the instance ID.
- Token receives the glc_... token.

The Generate now button creates a token with the required metrics:write scope by default. You do not need to pick anything.

For Cortex, Mimir, or self-managed Prometheus, see the hosting options note in the Prerequisites section.

Get your Grafana URL

Your Grafana URL is the host URL of your Grafana instance. To find it:

Open your Grafana account.
Copy your stack URL (for example, https://myorg.grafana.net).
Paste it into the Grafana URL field in BrowserStack.

Create a Grafana service account API key

The Grafana API key lets BrowserStack create the dashboard and post annotations on your behalf. This key is separate from the Prometheus token in the previous steps. It controls access on the Grafana side, not on Prometheus.

To create the key:

In Grafana, click Administration > Users and access > Service accounts.
Click Add service account.
Name it browserstack-load-testing and pick the role Editor.
Click Create.
On the service-account detail page, click Add service account token.
Set a display name and pick an expiration date. Rotate the key every 90 days.
Click Generate token.
Copy the glsa_... token immediately. Grafana does not show it again.
Paste it into the Grafana API Key field in BrowserStack.

The default Editor role grants the four required scopes:

dashboards:create and dashboards:write to create and update your load-test dashboard.
annotations:write to post lifecycle events.
datasources:read to verify your data source UID at save time.

If you use a custom role, make sure that the role includes these scopes.

Find your Grafana data source UID

The UID tells BrowserStack which Prometheus data source in your Grafana to point the dashboard at. Make sure this UID belongs to a Prometheus-typed data source, not an InfluxDB or other type. BrowserStack verifies the type at save time.

To find the UID:

In Grafana, click Connections > Data sources.
Click the Prometheus data source that you want BrowserStack to use.

Look at your browser’s address bar. The UID is the last segment of the URL, as shown in the following example:

https://myorg.grafana.net/connections/datasources/edit/grafanacloud-prom
                                                       ^^^^^^^^^^^^^^^^^
                                                              UID

Copy the UID.
Paste it into the Grafana Datasource UID field in BrowserStack.

Grafana Cloud’s bundled Prometheus data source usually has the fixed UID grafanacloud-prom. If you added a custom Prometheus data source, the UID is random, for example cflt8gnh3a8owc. Either is fine. Paste whichever matches the Prometheus instance that you push metrics to.

Save and verify

Click Save in the BrowserStack Connect form. BrowserStack runs a five-step health check that takes 2 to 5 seconds. You see one of the following results:

A green Connected badge if all six credentials are valid. You can now run a load test and view results in Grafana.
A red error message identifying which field is wrong. Fix that field and click Save again. For common errors, see the Troubleshooting section.

You can enable Prometheus by adding an integrations.prometheus block to your browserstack-load.yml file. This approach is useful for committing the integration to source control.

The CLI path uses the same six credentials as the UI path. To keep secrets out of source control, store the Prometheus token and the Grafana API key in environment variables and reference them in your YAML.

Copy

Run your load test with this YAML using the given command:

Copy

Best practices:

Store the Prometheus token and the Grafana API key in environment variables instead of hard-coding them in the YAML file.
Match the remoteWriteUrl to the Prometheus host where you want BrowserStack to write data.
For Grafana Cloud Hosted Prometheus, set username to your Grafana Cloud instance ID, not your email address.

Verify the integration

After your next test run completes, confirm that data is flowing:

In BrowserStack, open the test run’s detail page.
Click APM Tools in the side panel.
Locate the Prometheus card and click Open in Grafana.
Confirm that your Grafana dashboard opens in a new tab and shows panels for VU max, response time, and error percentage with data from the run.

Troubleshooting

The following table lists common errors and how to fix them.

Symptom	Cause	Fix
Save fails with legacy auth cannot be upgraded or HTTP 401 on the Prometheus side	You pasted only a token without a username, and Grafana Cloud Hosted Prometheus rejects Bearer-only authentication	Fill both Username (your instance ID) and Token. Re-copy them from the Grafana Cloud Send Metrics page.
Save fails with Invalid Prometheus credentials	The username and token combination is wrong	Regenerate the token from the Send Metrics page. Confirm that Username is your Grafana Cloud instance ID, not your email address.
Save fails with Datasource UID not found or the API key lacks `datasources:read` scope	Grafana returns 403 for both cases	Confirm the UID in Grafana, and confirm that your service account has the Editor role or higher.
Save fails with Datasource type mismatch, expected `prometheus`	The Datasource UID you pasted points to a different type, for example InfluxDB	Select the Prometheus-typed data source in Grafana and paste its UID.
Save fails with Grafana API key insufficient permissions	Service-account role does not grant `dashboards:create`, `dashboards:write`, or `annotations:write`	Promote the service account to Editor, or add a custom role that includes the four required scopes.
Save fails with Minimum Grafana version 9.x required	You are on an older Grafana that does not support the RBAC permissions endpoint	Upgrade Grafana to 9.0 or later.
Save succeeds, but no metrics appear in Prometheus after a test run	Token scope is wrong, or your Prometheus instance is read-only	Confirm that the token has the `metrics:write` scope. For self-managed Prometheus, confirm that remote write is enabled in your `prometheus.yml` config (`--web.enable-remote-write-receiver` flag or equivalent).
Metrics appear with dots in the names, for example `browserstack.vu.max`	Cached or old dashboard	Hard-refresh your Grafana dashboard. Prometheus metric names always use underscores (`browserstack_vu_max`).
Annotations appear in a single color instead of per-event colors	Browser cache on the dashboard	Hard-refresh the dashboard. Colors come from per-event annotation tracks and render correctly after refresh.
Cannot reach Prometheus endpoint	Remote Write URL typo, network or firewall issue, or Prometheus region down	Confirm the remote write URL. For Grafana Cloud Hosted Prometheus, open the URL host in a browser. It should return a Grafana Cloud landing page.

How BrowserStack stores your credentials

BrowserStack encrypts all six credentials at rest in the integrations service. The Load Testing service never sees the raw token or API key. It asks the integrations service to push metrics and create dashboards on your behalf. BrowserStack sends your credentials only to Prometheus and Grafana, and never logs them or exposes them to other tools.

To revoke access at any time, navigate to Integrations > APM apps > Prometheus in the BrowserStack Load Testing dashboard and click Disconnect.

Next steps

Run a load test: See the Get started guide to run your first test.
Customize the dashboard: Add panels for your application-specific metrics. BrowserStack does not overwrite panels that you create.
Set up alerts: Use Grafana alerting on the metrics that BrowserStack publishes. For example, alert if browserstack_errors_percentage exceeds 5% during a scheduled test. See the Grafana alerting documentation.
Add InfluxDB: Many teams run InfluxDB and Prometheus side by side. See InfluxDB integration.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!