info
In March 2023, Grafana Labs acquired Pyroscope, the company behind the eponymous open source continuous profiling project. In September 2023, Grafana Pyroscope v1.0.0
was released.
This documentation covers Pyroscope versions preceding v1.0.0
. We're keeping it for the time being, but we recommend that you upgrade to Grafana Pyroscope v1.0.0 or higher and switch to the new Grafana Pyroscope Docs for most up-to-date documentation.
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.
#
InstallationThe 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 stepsTo use Pyroscope in your CI/CD pipeline, you'll need to perform three steps: setup, execution, and upload.
- 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.
- Run test suite: In this step, you'll run your tests while Pyroscope is profiling them. Pyroscope will record performance data for each test.
- 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:
- Go
- Nodejs (jest)
#
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 PyroscopeAfter your tests have been set up, it's time to execute them:
- Go
- Nodejs (jest)
#
Profiling Go test suiteFor CI profiling we offer two methods for viewing results after running the test suite:
- (Option 1) Export test results locally: Use this option for local debugging / development to see a quick result
- (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 locallyCI=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 CloudWhile 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 ActionsThe 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 profilesThe 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.