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
.
#
DependenciesMake 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- macOS
- Ubuntu
- Debian
- CentOS/RHEL
- Fedora
brew install gitbrew install gobrew install nodebrew install rust # optionalbrew install php # optional
npm install -g yarn
#
Developing pyroscope#
1. Clone the repo:git@github.com:pyroscope-io/pyroscope.git
#
2. BootstrapThese 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 servermake dev
It builds assets in watch mode + builds the main binary and starts the server all on one command.
note
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 serverIt should be available at http://localhost:4040
#
Text Editors#
VS Code#
GoIf 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
#
GoLand#
DebugIf 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 commandpyroscope --help
#
Style GuidesPlease checkout out the style guides we use.
#
Storyboard / Design Guide for the frontendWhen 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.
#
LoggingWe use logrus library for logging purposes. There are two rules we follow when it comes to logging:
pkg/agent/profiler
should not depend onlogrus
. 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 toDebug
level.
#
Code Map#
/MakefileUsed as a collection of shortcuts, e.g make build
or make server
#
/examplesdocker-compose
examples for integrations with different languages.
#
/pkgMain 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/agentCode that does the actual profiling.
#
/pkg/execCode for pyroscope exec
. Mostly code related to command line interface.
#
/pkg/serverServer related code, mostly HTTP controllers.
#
/pkg/storageStorage code. Heavy on various tree-like data structures, low level database things.
#
/cmd/pyroscopePlace for command line interface initialization code.
#
/toolsPlace where we define the developer dependencies for go code. Kind of like devDependencies
, but for Go.
#
/webappThis is where the webapp lives.
#
/scriptsLocation for various helper programs / scripts.
#
/scripts/packagesHelper code / files we use to make releases and generate packages for Linux / macOS. See Downloads page for more information.
#
/third_party/rustdepsPyroscope depends on a few rust projects, particularly rbspy
and py-spy
.
#
Troubleshootinggoreman: 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).