Getting Started

Hi there! thank you for trying out Pyroscope! In this guide you'll need just 3 steps in order to start monitoring your application's performance.

  1. Install Pyrocope server
  2. Start Pyroscope server
  3. Start your application using our Pyroscope Agent

Quick Start

# install pyroscope
brew install pyroscope-io/brew/pyroscope
# start pyroscope server:
pyroscope server
# in a separate tab, start profiling your app:
pyroscope exec python manage.py runserver

Summary

This diagram shows the architecture of a typical application running with pyroscope:

pyroscope_diagram_with_logo

If you have any questions or if something doesn't work reach out to us in our slack group or email us at contact@pyroscope.io.

You can also schedule a call with an engineer if that's easier for you. We would love to learn about your use-case and help you get started.

Step 1: Install the Pyroscope server

We provide a few different ways for you to install Pyroscope server. To find out about other ways of installing Pyroscope, or to find packages for other CPU architectures (e.g ARM) visit our Downloads page.

brew install pyroscope-io/brew/pyroscope

Step 2: Start the Pyroscope server

To start pyroscope server run pyroscope server command:

pyroscope server
note

By default pyroscope server sends anonymized usage data to Pyroscope team. This helps us understand how people use Pyroscope and prioritize features accordingly. We take privacy of our users very seriously and only collect high-level stats such as number of apps added, types of spies used, etc. Source code for the analytics module is available on Github.

If you want to opt out of this, run pyroscope server with a flag or an environment variable:

pyroscope server -analytics-opt-out
# or
PYROSCOPE_ANALYTICS_OPT_OUT=true pyroscope server

Pyroscope server is the database where all the profiling information is stored. It also has a web UI (by default available on port :4040)

After you start the server you should be able to open http://localhost:4040/ and see that pyroscope server is profiling itself (pyroscope.server.cpu application).

Step 3: Start your app with Pyroscope agent

Now that you have pyroscope server running you can start continuously profiling your own applications.

We currently support 3 platforms:

  • Python
  • Ruby
  • Go

We'll be adding more platforms soon, if you want us to prioritize one particular platform, create an issue at Github or reach out to us in our slack group.

To start profiling a Python application, just add pyroscope exec before the command. For example, if you're working with a Django application, here's how you profile it:

export PYROSCOPE_SPY_NAME=pyspy
export PYROSCOPE_APPLICATION_NAME=my.python.app
pyroscope exec python manage.py runserver

If you're running your app inside a Docker container, see our Docker Guide. We also have examples.

This will make pyroscope agent send profiling data over to pyroscope server. Open http://localhost:4040/ in your browser to explore the incoming profiling data.

Configuration

Pyroscope can be configured with command line arguments, environment variables and config files. See Configuration for more info on this topic.

Deploy Pyroscope in production

If you're installing pyroscope in production environment, read Deployment Guide.