No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

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.

Use a permanent IAM access key that starts with AKIA. Temporary credentials that start with ASIA, including AWS SSO and assumed-role credentials, are not supported and fail authentication during the run. Generate the key with the Create access key flow on an IAM user, not on an assumed role.

Integration overview

When you enable push mode, BrowserStack publishes load-test metrics and a dashboard to Amazon CloudWatch so you can correlate test activity with backend performance and infrastructure health.

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.

Create a dedicated IAM user

  1. Sign in to the AWS Management Console and open the IAM console.
  2. Go to Users and select Create user.
  3. Name the user browserstack-load-testing, or any name you prefer.

Attach a CloudWatch policy

  1. On the Set permissions screen, select Attach policies directly, then select Create policy.
  2. Open the JSON tab and paste the following policy.
  3. Name the policy BrowserStackLoadTestingPolicy and create it.
  4. Return to the user creation flow and refresh the policy list. Attach BrowserStackLoadTestingPolicy, then finish creating the user.

Generate a permanent access key

  1. Open the IAM user you created and go to the Security credentials tab.
  2. Under Access keys, select Create access key and choose Application running outside AWS.
  3. Copy the access key ID and the secret access key. The access key ID starts with AKIA. AWS displays the secret only once. For details, see the AWS access keys documentation.

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

BrowserStackLoadTestingPolicy
Copy icon Copy

Each action serves a specific purpose:

  • cloudwatch:PutMetricData: Publishes metrics into your namespace (push mode only).
  • cloudwatch:PutDashboard and cloudwatch:GetDashboard: Create the dashboard and add lifecycle annotations during the run (push mode only).
  • cloudwatch:ListMetrics: Verifies read access to the namespace when you save the integration.
  • cloudwatch:GetMetricData: Fetches server metrics for your test report (pull mode only).
  • cloudwatch:TagResource: Tags the dashboard so that BrowserStack can filter it correctly (push mode only).
  • 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.

Category Metric name Description
Load VuMax Maximum virtual users in the window
Load VuStarted Virtual users started in the window
Load VuEnded Virtual users ended in the window
Load TestDuration Elapsed test time
Requests RequestsRateAvg Average requests per second
Requests RequestsCountTotal Total requests in the window
Errors ErrorsPercentage Error rate as a percentage
Errors ErrorsCountTotal Total errored requests
Response ResponseTimeAvg Mean response time, in milliseconds
Response ResponseTimeP75 75th percentile response time
Response ResponseTimeP90 90th percentile response time
Response ResponseTimeP95 95th percentile response time
Response ResponseTimeP99 99th percentile response time
Response ResponseTimeMax Maximum response time
Browser BrowserLcp Largest Contentful Paint
Browser BrowserFcp First Contentful Paint
Browser BrowserPlt Page Load Time
Browser BrowserNetworkCallsTotal Browser network call count
System SystemCpuUsage Engine CPU usage percentage
System SystemMemoryUsage Engine memory usage percentage
System SystemNetworkBandwidth Engine network bandwidth

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:

Event When it fires
test_started The test transitions from queued to running.
test_completed The test reaches a terminal success state.
test_failed The test reaches a terminal failure state.
test_stopped You manually stop the test.
iteration_started An iteration begins, for iteration-based load profiles.
iteration_ended An iteration completes.
rampup_started The ramp-up phase begins, for ramping load profiles.
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 CloudWatch

Choose your integration mode and preferred configuration method:

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

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.

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.

Pull mode limitations

  • You can use one APM tool at a time. If you connect CloudWatch in pull mode and later want to pull from Prometheus, you must disconnect CloudWatch first.
  • You select one namespace and the metrics to pull. Select metrics that are actively reported by your load test (inactive metrics are not displayed in the UI picker).
  • Data is fetched live, not stored. When you open a test report, BrowserStack queries CloudWatch for the metrics. If your CloudWatch metrics have been expired or deleted, the report shows “No metric data.”
  • The settlement window is 1 minute. After your test ends, the chart continues querying every 5 seconds for 1 minute while CloudWatch ingests the final data points. After the window closes, the chart only updates when you reopen the report.
  • Credentials do not need a reconnect to switch modes. If you connected CloudWatch for push and later enable pull, you add the additional required IAM permissions to the same credentials. Switching modes later does not disconnect the tool.

Troubleshooting

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

Symptom Likely cause Fix
Save fails immediately with AccessDenied The policy is missing sts:GetCallerIdentity. Add sts:GetCallerIdentity to the policy and confirm it is attached to the user.
Save fails with InvalidClientTokenId or The security token is invalid The access key starts with ASIA, which is a temporary credential. Generate a permanent access key that starts with AKIA on an IAM user, not on an assumed role.
Save fails with SignatureDoesNotMatch The secret access key has a typo, often a trailing space. Re-copy the secret from AWS. If you no longer have it, deactivate the old key and create a new one.
Save fails with AccessDenied for a CloudWatch action The policy is missing ListMetrics, PutMetricData, PutDashboard, GetDashboard, or TagResource. Recheck the policy and confirm all five CloudWatch actions are present.
Save fails with Namespace cannot start with AWS/ The namespace uses the reserved AWS/ prefix. Choose a custom namespace, such as BrowserStack/LoadTest.
No metrics appear after a test run The console is open in a different Region than the one you configured. Switch the console to the Region you entered, then open CloudWatch > Metrics > All metrics.
The dashboard widgets show No data The IAM user that opens the dashboard lacks read permission. Grant cloudwatch:GetMetricData and cloudwatch:GetMetricStatistics to whichever user opens the dashboard.

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.

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





Thank you for your valuable feedback

Is this page helping you?

Yes
No

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





Thank you for your valuable feedback!

Talk to an Expert
Download Copy Check Circle