This guide steps you through configuring a local development environment for the Sentry server on macOS and Linux. If you're using another operating system (Plan 9, BeOS, Windows, …) the instructions are still roughly the same, but we don't maintain any official documentation for anything else for now.

Read about known issues in the troubleshooting section.

Automatic Bootstrapping

If you are using macOS you can use the automatic bootstrapping script that can be piped to bash:

bash <(curl -s https://raw.githubusercontent.com/getsentry/bootstrap-sentry/main/bootstrap.sh)

This script does more than what's documented on the rest of the page to ensure a somewhat uniform development environment for Sentry engineers.

Manual Setup

This will guide you through manually setting up your development environment.

Clone the Repository

To get started, clone the repo at https://github.com/getsentry/sentry or your fork.

git clone https://github.com/getsentry/sentry.git
cd sentry

You're going to be working out of this repository for the remainder of the setup.

System Dependencies

Let's make sure that your system is ready for Sentry.

Xcode CLI tools (Mac specific)

You'll need to first install Xcode CLI tools. Run this command and follow the instructions:

xcode-select --install

Brew

Install Homebrew, and then run the following command to install the various system packages (like Docker, openssl, ...) as listed in Sentry's Brewfile.

brew bundle --verbose

Docker (Mac specific)

Docker was installed by brew bundle.

On macOS, docker (which brew has already installed for you under /Applications/Docker.app) needs some manual intervention. You can run this command to set it up automatically for you:

open -g -a Docker.app

You should soon see the Docker icon in your macOS menubar. Docker will automatically run on system restarts, so this should be the only time you do this.

Increasing the memory limit

It's recommended to increase the Docker memory limit to something higher than the default (2048MB).

On Docker Desktop, you can adjust the memory limits by going to:

[Cog Symbol] > Preferences > Resources > Advanced > Memory

Or you can change the memory limit via the CLI:

# quit Docker if its running
osascript -e 'quit app "Docker"'

# check what the default is configured currently
cat /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json | grep "memoryMiB"

# increase configured memory to something reasonable
sed -i .bak 's/"memoryMiB":.*/"memoryMiB": 7168,/g' /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json

# check configuration
cat /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json | grep "memoryMiB"

# start up docker with next steps

You can verify that Docker is running by running docker ps in your terminal.

Python

Sentry depends on binary Python packages called Python Wheels, which we distribute for the following platforms:

• Linux (arm64 or x86_64) compatible with PEP-600 (``manylinux_2_28)
• macOS 11 (x86_64) or macOS 12 (arm64) or newer

We utilize pyenv to install and manage Python versions. It got installed when you ran brew bundle.

To install the required version of Python you'll need to run the following command. This will take a while, since your computer is actually compiling Python!

make setup-pyenv

After this, if you type which python, you should see something like $HOME/.pyenv/shims/python rather than /usr/bin/python. This is because the following has been added to your start up script:

Given that the bash instructions vary greatly based on the user's
configuration, it is recommended to visit

https://github.com/pyenv/pyenv#installation

for instructions on how to set up Bash.

Virtual Environment

You're now ready to create a Python virtual environment. Run:

python -m venv .venv

And activate the virtual environment:

source .venv/bin/activate

If everything worked, running which python should now result in something like /Users/you/sentry/.venv/bin/python.

JavaScript

We use volta to install and manage the version of Node.js that Sentry requires. To install Volta run:

curl https://get.volta.sh | bash

The volta installer will tell you to "open a new terminal to start using Volta", but you don't have to! You can just reload your shell:

exec "$SHELL"

This works because the volta installer conveniently made changes to your shell installation files for your shell's startup script:

export VOLTA_HOME="$HOME/.volta"
grep --silent "$VOLTA_HOME/bin" <<< $PATH || export PATH="$VOLTA_HOME/bin:\$PATH"

Now, if you try and run volta, you should see some help text, meaning volta is installed correctly. To install node, simply run:

node -v

Volta intercepts this and automatically downloads and installs the node and yarn versions in sentry's package.json.

Bootstrap Services

Source your virtual environment again (source .venv/bin/activate), then run:

make bootstrap

This will take a long time, as it bootstraps Sentry, its dependencies, starts up related services and runs database migrations.

The bootstrap command does a few things you'll want to know about:

• sentry init creates the baseline Sentry configuration in ~/.sentry/.
• sentry devservices up spins up required Docker services (such as Postgres and Clickhouse)
• sentry upgrade runs Postgres migrations, and will also prompt you to create a user. This user will be the superuser.

Once this command has finished you'll have Sentry installed in development mode with all its required dependencies.

If the command is done you should see a "Finished bootstrapping!" message.

Note: This command is meant to be run only once. If the command fails please remove all existing Docker containers, all Docker volumes, and ~/.sentry/ and try running it again.

(Optional) Bringing your services up-to-date

To bring your dependencies up-to-date do not run make bootstrap again but instead run:

make develop

direnv

direnv automatically activates your virtual environment, sets some helpful environment variables for you, and performs some simple checks to make sure your environment is as expected (and tries its best to guide you if it isn't). This happens every time you change directories into sentry.

First, you should be done bootstrapping. Then, run:

brew install direnv

After direnv is installed add the following snippet to the end of your startup script:

eval "\$(direnv hook bash)"

And after doing that, reload your shell:

exec "$SHELL"

Any time the .envrc configuration changes (including the first load) you will be prompted to run

direnv allow

before any of the configuration will run. This is for security purposes and you are encouraged to inspect the changes before running this command.

Customize your development environment variables

If you want to personalize your environment variables, you can do so by creating a .env file. This file is ignored by git, thus, you will not be able to leak it into one of your PRs.

Running make direnv-help will list all of the latest supported environment variables. Using SENTRY_DEVENV_NO_REPORT as an example, to enable that setting you would insert SENTRY_DEVENV_NO_REPORT=1 into your .env file.

Running the Development Server

Now you can run the development server at http://localhost:8000:

sentry devserver --workers

If you are developing for aesthetics only and do not rely on the async workers, you can omit the --workers flag in order to use fewer system resources.

If you would like to be able to run devserver outside of your root checkout, you can install webpack globally with npm install -g webpack.

To create a user, run:

sentry createuser

Frontend Only & Backend Only

Please refer to Frontend Development Server and Backend Development Server for alternative ways to bring up the Sentry UI.

Ingestion Pipeline (Relay)

Some services are not run in all situations. Among those are Relay and the ingest workers. If you need a more production-like environment in development, you can set SENTRY_USE_RELAY=True in ~/.sentry/sentry.conf.py. If sentry devservices is currently up ,make sure to restart it after you make the change. This will launch Relay as part of the devserver workflow.

Additionally, you can explicitly control this during devserver usage with the --ingest and --no-ingest flags. The sentry devservices command will not update Relay automatically in that case, to do this manually run:

sentry devservices up --skip-only-if relay
sentry devserver --workers --ingest

If you want to enable the entire metrics ingestion pipeline, you need to add the following to your config at ~/.sentry/sentry.conf.py:

SENTRY_USE_RELAY = True
SENTRY_USE_METRICS_DEV = True
SENTRY_EVENTSTREAM = "sentry.eventstream.kafka.KafkaEventStream"
SENTRY_FEATURES['organizations:metrics-extraction'] = True  # Enables session metrics
SENTRY_FEATURES['organizations:transaction-metrics-extraction'] = True  # Enables transaction metrics

Setting up Getsentry

Now that you have sentry all set up, it's time to set up Getsentry. For information on the distinction between the two, refer to Sentry vs Getsentry. After setting it up, you'll also want to read about the development workflow here.

Let's start off by cloning the getsentry repository to be adjacent to your sentry repository:

# Go to where you have sentry and clone getsentry.
cd /path/to/sentry
cd ..
git clone git@github.com:getsentry/getsentry.git

It's necessary to keep getsentry in an adjacent directory (it's expected by various make targets in the getsentry Makefile). For example, if you did a ls ~/code you'd see something like:

sentry/   getsentry/

Next, create a virtual environment just like how you did with Sentry earlier.

Then, run make bootstrap and follow any additional instructions that come up.

If all went well, then you can start the development server:

getsentry devserver --workers

Note: You cannot have both sentry and getsentry devserver running at the same time.

After the server warms up for a little while, you should be able to access it at http://dev.getsentry.net:8000.

If you see DoesNotExist: Subscription matching query does not exist in your dev server, run the following in getsentry:

./bin/mock-subscription

You can set your local instance's org to use a business plan by running the following in getsentry:

./bin/mock-subscription <org_slug> --plan mm2_a_500k

If you need to overwrite configuration options for your local environment, you can create getsentry/conf/settings/devlocal.py and put the configuration option overrides there. This module will be automatically imported by dev.py if it exists.

Troubleshooting

You might also be interested in troubleshooting CI.

Problem: You see an error that mentions something like pkg_resources.DistributionNotFound: The 'some_dependency<0.6.0,>=0.5.5' distribution was not found and is required by sentry

Solution: Your virtualenv needs to be updated. Run make install-py-dev.

Problem: You see Error occured while trying to proxy to: dev.getsentry.net:8000/

Solution: You likely need to upgrade your Python dependencies. Go to the git root directory and run make install-py-dev.

Problem: Module not found: Error: Can't resolve 'integration-docs-platforms'

Solution:

make build-platform-assets

Problem: You see SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version 76

Or:

Traceback (most recent call last):
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/pytest/selenium.py", line 344, in browser
    driver = start_chrome(**chrome_args)
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/retries.py", line 41, in execute_with_retry
    return retrier(functools.partial(fn, *args, **kwargs))
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/retries.py", line 85, in __call__
    error,
RetryException: Could not successfully execute <functools.partial object at 0x10f31e7e0> within 15.830 seconds (12 attempts.)

Solution:

ChromeDriver needs to be updated.

brew upgrade --cask chromedriver

Problem:

--- snip ---
00:51:27 server  | ImportError: cannot import name _remove_dead_weakref
00:51:27 server  | unable to load app 0 (mountpoint='') (callable not found or import error)

This is caused by uwsgi running the wrong version of Python. When starting up, you'll see something like

uwsgi socket 0 bound to TCP address 127.0.0.1:8889 fd 3
Python version: 2.7.10 (default, Feb 22 2019, 21:17:52)  [GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.37.14)]
Set PythonHome to /Users/dfuller/code/sentry/.venv

The Python version here should be 2.7.16, but will be a lower version, likely your system Python. This is because uwsgi was compiled against a stale Python and the resultant wheel has been cached by pip.

Solution:

In your sentry virtualenv:

pip uninstall uwsgi
pip install --no-cache-dir uwsgi

Problem: You see DoesNotExist: Subscription matching query does not exist

Solution: In getsentry, run the following to mock a subscription:

./bin/mock-subscription <org_slug>

Problem: You see something like Error: No such container: sentry_postgres, or you don't see sentry_snuba, sentry_postgres, sentry_clickhouse, and sentry_redis listed under COMMAND NAMES.

Solution: Review the bootstrap services section or spin up Docker services with:

sentry devservices up

Problem: You see something like Error 61 connecting to 127.0.0.1:6379. Connection refused. when running your dev server.

Solution: Make sure your Docker services are running:

docker ps

--

Problem: If you see the following error about Kafka

%3|1687815512.814|FAIL|rdkafka#producer-1| [thrd:127.0.0.1:9092/bootstrap]: 127.0.0.1:9092/bootstrap: Connect to ipv4#127.0.0.1:9092 failed: Connection refused (after 0ms in state CONNECT)

Solution: You need to start up additional services with:

# In the file ~/.sentry/sentry.conf.py
# Insert this line at the bottom
SENTRY_EVENTSTREAM = 'sentry.eventstream.kafka.KafkaEventStream'

# You should see Kafka and Zookeeper
sentry devservices down && sentry devservices up