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.

Dependencies

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

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

macOS

On macOS we recommend you to use homebrew to manage dependencies:

brew install git
brew install go
brew install node
brew install rust
npm install -g yarn

Building pyroscope locally

To start developing Pyroscope you need to know a few commands:

# clone the repo:
git@github.com:pyroscope-io/pyroscope.git
# installs go developer tools needed for some tasks:
make install-dev-tools
# builds rust dependencies for rbspy / pyspy / phpspy,
# normally you only need to run this once:
make build-third-party-dependencies
# builds web assets (JavaScript + SCSS code):
make assets
# to build assets in --watch mode use this command:
make assets-watch
# builds the main binary, puts it in bin/pyroscope:
make build
# if the build fails because of linking issues (ld), try building it without spies:
ENABLED_SPIES=none make build
# starts pyroscope server:
make server

Text Editors

VS Code

Go

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, set files.insertFinalNewline to true. See this stack overflow answer for context on why this is important.

Style Guides

Please checkout out the style guides we use.

Logging

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

Makefile

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

examples

docker-compose examples for integrations with different languages.

pkg

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.

pkg/agent

Code that does the actual profiling.

pkg/exec

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

pkg/server

Server related code, mostly HTTP controllers.

pkg/storage

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

cmd/pyroscope

Place for command line interface initialization code.

tools

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

webapp

This is where the webapp lives.

scripts

Location for various helper programs / scripts.

scripts/packages

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

third_party/rustdeps

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