Skip to main content

Running Pyroscope in a CI/CD pipeline

If you're running tests in a CI/CD pipeline, you can use Pyroscope to profile your tests and upload the results to Pyroscope Cloud. This allows you to identify performance bottlenecks and optimize your code.

To use Pyroscope in a CI/CD pipeline, you'll need to install the pyroscope-ci binary. This binary provides the functionality for profiling tests and uploading the results.

Installation#

The pyroscope-ci binary can be downloaded from the Github Releases page. A convenient installation script is available to automate this process:

curl https://raw.githubusercontent.com/pyroscope-io/ci/main/install.sh | sh

You can also download the script and inspect its contents before running it. We recommend pinning the installation to a fixed commit.

After running the installation script, you'll have access to the pyroscope-ci binary in your project. You can run it using:

./pyroscope-ci [COMMAND]

If you're using Github Actions, we recommend using jaxxstorm/action-install-gh-release action to install the pyroscope-ci binary. For a more complete example see the Integrating with Github Actions section below.

CI profiling steps#

To use Pyroscope in your CI/CD pipeline, you'll need to perform three steps: setup, execution, and upload.

  1. Set up tests with Pyroscope: In this step, you'll initialize Pyroscope and start profiling. This is typically done in a setup script that runs before your tests.
  2. Run test suite: In this step, you'll run your tests while Pyroscope is profiling them. Pyroscope will record performance data for each test.
  3. Upload/export results: In this step, you'll upload or export the profiling data. This allows you to view the data and analyze the performance of your code.

The following sections provide language/testing framework specific instructions for each of these steps:

Set up Profiling for Go tests#

To profile your Go tests with Pyroscope, you can use the ./pyroscope-ci go command. This command will recursively search for all Go test packages under the pkg directory, generate a pyroscope_test.go file for each package, and instrument the test functions with the Pyroscope agent.

Here's an example of how to use pyroscope-ci go to profile your tests:

# Note you may need to pull the `pyroscope` dependency, if you are not using it yet.# go mod tidy./pyroscope-ci go install --applicationName=myapp pkg

Note that the --applicationName flag specifies the name of the application being profiled.

We recommend running as a CI step, so that you don't have to commit these lines and profile tests when running locally.

That's it! Pyroscope will now profile your tests in your CI/CD pipeline.

Running test suite with Pyroscope#

After your tests have been set up, it's time to execute them:

Profiling Go test suite#

For CI profiling we offer two methods for viewing results after running the test suite:

  1. (Option 1) Export test results locally: Use this option for local debugging / development to see a quick result
  2. (Option 2) Upload test results to Pyroscope cloud: Use this option for production test suite to track changes over time

In Go, you can use the following commands to run tests with Pyroscope:

Option 1: Export test results locally#

CI=true ./pyroscope-ci exec --uploadToCloud=false --exportLocally -- go test ./...

This will create profiles in the --outputDir (defaults to ./pyroscope-ci). These profiles can be uploaded to www.flamegraph.com, via the UI, the API or using the flamegraph.com Github Action.

Option 2: Upload test results to Pyroscope cloud#

# Note: Make sure to set environment variable CI=true in your test runner./pyroscope-ci exec --apiKey="MY_API_KEY" -- go test ./...
note

Some CI systems will skip certain tests if the files have not been touched. To avoid this, you can run your tests without cache using the -count=1 flag.

Viewing test suite profiles in Pyroscope Cloud#

While testing you may try exporting profiling locally, but in practice we've built tooling around profiles for your test suites that makes optimizing and improving test suites convenient.

The CI Context (branch, commit) are all inferred from the environment. If your auto detection service doesn't work with your CI system, you can pass each flag manually (--branch and --commitSHA).

All the data gathered while your tests were running will be merged and grouped by profile type, which is then uploaded to Pyroscope Cloud.

Integrating with Github Actions#

The following is a simplified example taken from the pyroscope repository using Github Actions:

name: CI Profiling
on:  push:    branches: [main]  pull_request:    branches: [main]
jobs:  js-tests:    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v2      - uses: actions/setup-node@v2        with:          node-version: '16.18'      - name: Install pyroscope-ci        uses: jaxxstorm/action-install-gh-release@v1.5.0        with: # Grab the latest version          repo: pyroscope-io/ci        env:          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}      - name: Install Webapp dependencies        run: yarn install --frozen-lockfile      - name: Run tests and upload        run: pyroscope-ci exec --apiKey=${{ secrets.PYROSCOPE_CLOUD_TOKEN }} yarn test --no-cache --max-workers=1

Visualizing profiles#

The profiles can be visualized in the CI page under Pyroscope Cloud.

For illustration, above is the profile for github.com/pyroscope-io/pyroscope go tests, which shows that the race condition detector (racecall) spends a significant amount of time.