Skip to main content

Developer Guide

This guide will help you get started developing Pyroscope.

Pyroscope consists of 2 core components:

  • webapp, mostly JS code, UI for the web application
  • go code, this is all the backend code including profiling code and the storage engine.

Both run under the port 4040.


Make sure you have the following dependencies installed before setting up your developer environment:

  • git
  • go
  • node + yarn
  • rust (optional, you'll only need it to work on Python and Ruby integrations)
  • php (optional, you'll only need it to work on PHP integration)

Installing dependencies#

On macOS we recommend you to use homebrew to manage dependencies:
brew install gitbrew install gobrew install nodebrew install rust # optionalbrew install php  # optional
npm install -g yarn

Developing pyroscope#

1. Clone the repo:#

2. Bootstrap#

These are required to build the go code, among other things.

(Only run these commands once)

make install-dev-tools
# optional step, only run if you need to work on ruby/python/php integrationsmake build-third-party-dependencies
make install-web-dependenciesmake web-bootstrap

3. Run the server#

make dev

It builds assets in watch mode + builds the main binary and starts the server all on one command.


If you have skipped building third-party dependencies, you'll need to build the binary without third party integrations:

ENABLED_SPIES=none make dev

4. Access the server#

It should be available at http://localhost:4040

Text Editors#

VS Code#


If you're using VS Code we would recommend the official Go extension from Google.

We use revive for linting. Add --config=${workspaceFolder}/revive.toml to Go: Lint Flags section in VS Code settings.

To make sure VS Code adds new lines to the end of text files, set files.insertFinalNewline to true. See this stack overflow answer for context on why this is important.

To make sure VS Code removes trailing whitespaces, set files.trimTrailingWhitespace to true. See this stack overflow answer



If you're using GoLand IDE and want to debug it, you can set GoLand's run/debug configuration as the following:

  • Run Kind :Package
  • Package Path: {Your Project Path}/pyroscope-io/pyroscope/cmd/pyroscope
  • Program arguments: The sub-module your want to run/debug, such as server, you can see all of them wih command pyroscope --help

Style Guides#

Please checkout out the style guides we use.

Storyboard / Design Guide for the frontend#

When working on the frontend, please refer to our Storybook for examples of commonly used elements and examples.

These examples are stored under the /stories directory.


We use logrus library for logging purposes. There are two rules we follow when it comes to logging:

  • pkg/agent/profiler should not depend on logrus. This is because we don't want our users' logs to be tainted with pyroscope messages.
  • Be mindful of log levels. Only log information that would truly be useful to an average end user in log levels Info or higher. When in doubt, lean on the side of moving log messages to Debug level.

Code Map#


Used as a collection of shortcuts, e.g make build or make server


docker-compose examples for integrations with different languages.


Main place for the go code. We use golang-standards/project-layout as the standard for where different parts of the system should go. See Style Guide for more information on various style guides we use.


Code that does the actual profiling.


Code for pyroscope exec. Mostly code related to command line interface.


Server related code, mostly HTTP controllers.


Storage code. Heavy on various tree-like data structures, low level database things.


Place for command line interface initialization code.


Place where we define the developer dependencies for go code. Kind of like devDependencies, but for Go.


This is where the webapp lives.


Location for various helper programs / scripts.


Helper code / files we use to make releases and generate packages for Linux / macOS. See Downloads page for more information.


Pyroscope depends on a few rust projects, particularly rbspy and py-spy.


goreman: No such file or directory#

Ensure $GOPATH/bin in your PATH. (GOPATH is usually ~/go)

bad file descriptor/too many open files#

If you are getting a bad file descriptor or too many open files error, then run this command: ulimit -S -n 2048. Once you do that, run the make dev command again. Please note that the ulimit shell command only works on Unix-like OS (e.g. Linux/macOS).