Amazon CloudWatch integration for BrowserStack Load Testing

Learn how to send BrowserStack Load Testing metrics and a dashboard to Amazon CloudWatch so you can correlate load-test traffic with application performance.

Use this guide to connect BrowserStack Load Testing with Amazon CloudWatch. You can then correlate test activity with backend performance, infrastructure health, and user experience in one place.

BrowserStack publishes metrics to CloudWatch, creates a custom dashboard you can open from your test results, and posts lifecycle events as dashboard annotations.

Prerequisites

Before you enable the Amazon CloudWatch integration, make sure you have:

• AWS account: An account with permission to create IAM users and CloudWatch resources.
• Permanent IAM access key: A long-lived access key that starts with AKIA. Temporary credentials that start with ASIA are not supported.
• AWS Region: The Region where you want BrowserStack to publish metrics, such as us-east-1. It does not have to match the Region your application runs in.
• CloudWatch namespace: A namespace for your load-test metrics, such as BrowserStack/LoadTest. The namespace cannot start with the reserved AWS/ prefix.
• BrowserStack Load Testing account: Access to BrowserStack Load Testing with admin access to at least one project.

Integration overview

BrowserStack Load Testing streams metrics and events to your AWS account so you can analyze how your systems behave under load.

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

Core capabilities:

• Metric streaming: BrowserStack aggregates performance data into 10-second buckets and publishes it to CloudWatch with the PutMetricData action.
• Virtual user metrics: Track how many virtual users (VUs) are active, how long tests run, and how many requests they generate.
• Error and latency metrics: Monitor error rates and response-time percentiles to identify performance regressions.
• Browser metrics: For browser-based load tests, capture core web vitals such as LCP, FCP, and page load time.
• Dimensions: Each metric carries dimensions, such as load test name, Region, and executor, so that you can filter results inside CloudWatch.
• Native dashboard: BrowserStack creates a preconfigured dashboard in your account on the first run and marks lifecycle events as annotations. The load-test report returns a deep link to that dashboard.

Create your AWS credentials

Create a dedicated IAM user with a minimal CloudWatch policy, then generate a permanent access key. Do not reuse an admin or developer key, so that you limit access if the key is ever exposed.

Attach the following policy to the IAM user. It grants only the actions BrowserStack needs, nothing more:

Each action serves a specific purpose:

• cloudwatch:PutMetricData: Publishes metrics into your namespace.
• cloudwatch:PutDashboard and cloudwatch:GetDashboard: Create the dashboard and add lifecycle annotations during the run.
• cloudwatch:ListMetrics: Verifies read access to the namespace when you save the integration.
• cloudwatch:TagResource: Tags the dashboard so that BrowserStack can filter it correctly.
• sts:GetCallerIdentity: Verifies that the credentials are valid before BrowserStack saves them.

Supported metrics

BrowserStack Load Testing publishes the following metrics to the CloudWatch namespace you configure. All metrics are sent automatically when CloudWatch is connected.

Every metric carries the LoadTestName, TestId, RunNumber, LoadZone, and ExecutorName dimensions so that you can filter and group results.

Lifecycle events

BrowserStack Load Testing also posts lifecycle events as vertical annotations on your CloudWatch dashboard. Use them to align spikes or drops in performance with changes in test state. Annotations are filtered to the dashboard’s test, so only events for that load test appear.

The following lifecycle events are supported:

Configure CloudWatch from the BrowserStack UI

This is the most common path. After you create the IAM user and access key, paste the four values into the BrowserStack Connect form.

1. In the BrowserStack Load Testing UI, navigate to Integrations.
2. Under APM apps, select the Amazon CloudWatch tile and select Connect.
3. Enter your AWS Access Key ID, AWS Secret Access Key, AWS Region, and CloudWatch Namespace.
4. Select Save. BrowserStack runs a short health check and shows a green Connected badge when the credentials and permissions are valid. If a field is wrong, BrowserStack shows an inline error so that you can correct it.

Configure CloudWatch from the CLI

You configure the Amazon CloudWatch integration in the browserstack-load.yml file. The following example enables CloudWatch and sends metrics and events to your account.

This configuration lives under the top-level integrations block in browserstack-load.yml alongside any other APM tools you configure.

Configuration reference

Each field under the connection block maps to a value from your IAM user and target Region:

connection.awsAccessKeyId

The access key ID for your IAM user. It starts with AKIA. Store this in an environment variable, such as AWS_ACCESS_KEY_ID.

connection.awsSecretAccessKey

The secret access key paired with the access key ID. Store this securely in an environment variable, such as AWS_SECRET_ACCESS_KEY.

connection.region

The AWS Region where you want to publish metrics, such as us-east-1. CloudWatch metrics are Region-scoped.

connection.namespace

The CloudWatch namespace for your load-test metrics, such as BrowserStack/LoadTest. The namespace cannot start with the reserved AWS/ prefix.

metrics

Specifies which metrics to send. Use metrics: all to send every metric, or list specific metric names under select and assign dimensions to each group.

events

Specifies which lifecycle events to send. Use events: all to send every event, or list specific event names under select.

Best practices:

• Store the access key ID and secret access key in environment variables instead of hard-coding them in the YAML file.
• Grant the IAM user only the CloudWatch actions the integration needs.
• Choose a dedicated namespace so that you can filter load-test metrics and attribute costs accurately.

Verify the integration

After your next test run completes:

1. In BrowserStack, open the test run’s detail page.
2. Select APM Tools in the side panel.
3. In the Amazon CloudWatch card, select Open in CloudWatch.
4. Your CloudWatch dashboard for this load test opens in a new AWS Console tab. It shows metrics and annotations from the run.

Troubleshooting

If the integration fails to save or no data appears in CloudWatch, use the following table to resolve common issues:

Where your credentials are stored

BrowserStack stores your credentials encrypted at rest. The Load Testing service never sees the raw secret access key. BrowserStack sends credentials only to AWS. To revoke access, select Disconnect on the Amazon CloudWatch tile in Project Settings > Integrations. BrowserStack stops publishing immediately, and the dashboard and previously published metrics remain in your AWS account. To rotate the key, deactivate the old key in IAM, generate a new one, and update BrowserStack with the new values.

Limitations

• BrowserStack supports permanent IAM credentials only. Temporary credentials that start with ASIA, AWS SSO credentials, and assumed-role credentials are not supported.
• BrowserStack publishes to a single Region. Multi-region publishing is not supported.
• Cross-account publishing is not supported. The IAM user must live in the same AWS account where you want to view the dashboard.
• Namespaces that start with the reserved AWS/ prefix are rejected.
• Trace correlation with the W3C traceparent and tracestate headers is not supported. Dashboard metrics and lifecycle events are unaffected.

Next steps

After you save your changes, run your load test from the CLI or dashboard. When the test completes, open CloudWatch and search for your namespace to validate that data is flowing correctly. Then build dashboards and alarms based on the metrics that matter most to your team.