Environment

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.

Setup

Begin by installing the devenv tool following these instructions.

After installation you should be able to run devenv bootstrap which will guide you through the rest.

When you're done with setup, you'll want to also review the development workflow.

Keeping your environment up-to-date

Simply run devenv sync inside of your sentry or getsentry repo.

Running the Development Server

The devservices ensure that you have all the services required for local development running. See the devservices docs for more information on managing services. When setting up sentry, execute the following command in the sentry folder:

sentry devservices up

After that, you can start the development server inside the sentry folder:

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.

Access it at http://dev.getsentry.net:8000 (you'll have to wait a bit for webpack to finish). A superuser account should have been created for you during bootstrap - admin@sentry.io with password admin. You can create other users with 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.

Enabling HTTPS

You may wish to run the development server in HTTPS mode. This can be done by generating and installing local certificates.

We will be using mkcert to create and install a locally-trusted, development certificate. The following will install mkcert and then create and install the local certificates.

brew install mkcert
brew install nss # if you use Firefox
yarn mkcert-localhost

Running sentry devserver will automatically use HTTPS when the certificates have been installed.

Ingestion Pipeline (Relay)

Some services are not run in all situations. Among those are Relay and the ingest workers.

If you need to ingest errors, but don't require metrics ingestion: 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

After enabling KafkaEventStream the snuba service has to be reset to pick up the new configuration:

sentry devservices rm snuba
sentry devservices up snuba

Running the Getsentry Development Server

See also: Sentry vs Getsentry

Just like running sentry (see above), you can start the devservices using the following command in the getsentry folder:

sentry devservices up

After that, you can start the development server inside the getsentry folder:

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 must access it at http://dev.getsentry.net:8000. Using localhost doesn't work.

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.

To enable the ingest workers, follow the steps described here and run

getsentry devserver --workers --ingest

Running siloed instances

By default sentry devserver will run a monolith mode application server. You can also run devserver with siloed application instances. Before you do, you need to create split silo databases.

The devserver command supports --silo option that lets you create siloed instances. Any workers, consumers, or celery-beat processes will be started with the same silo mode.

# Start control silo servers
sentry devserver --silo=control --celery-beat --workers

# Start region silo servers
sentry devserver --silo=region --celery-beat --workers --ingest

Siloed servers have the following port assignments:

• 8000 - Webpack
• 8010 - Region silo webserver
• 8001 - Control silo webserver

In the above setup your local environment will use org slug domains, and send requests to us.dev.getsentry.net (region silo) and dev.getsentry.net (control silo). All requests will be proxied by webpack and forwarded to the appropriate server based on hostname.

Ngrok and siloed servers

To combine ngrok and local development servers you’ll need to reserve multiple domains in ngrok, and create a configuration file for ngrok:

version: '2'
authtoken: <YOUR-NGROK-AUTHTOKEN>
tunnels:
  acme-org:
    proto: http
    hostname: acme.<yourname>.ngrok.dev
    addr: 8000
  control-silo:
    proto: http
    hostname: <yourname>.ngrok.dev
    host_header: 'rewrite'
    addr: 8000
  region-silo:
    proto: http
    hostname: us.<yourname>.ngrok.dev
    addr: 8010
    host_header: 'rewrite'

Then run all the required servers

# Run a control silo with ngrok
sentry devserver --silo=control --ngrok <yourname>.ngrok.dev

# Run a region silo without ngrok
sentry devserver --silo=region --ngrok <yourname>.ngrok.dev

# Run ngrok
ngrok start --all --config regions.yml

This setup will result in both the region and control servers responding to different domains. The multi-region setup with ngrok also enables customer-domains and you'll need ngrok domains for each organization you plan on using. In this configuration, CORS will work similar to production. For ngrok setup with non-siloed development server see developement server.

Siloed Django Shell

If you want to use a repl with silo modes active:

# Start a control silo shell
SENTRY_SILO_DEVSERVER=1 SENTRY_SILO_MODE=CONTROL getsentry django shell

# Start a region silo shell
SENTRY_SILO_DEVSERVER=1 SENTRY_SILO_MODE=REGION SENTRY_REGION=us getsentry django shell

Troubleshooting

You might also be interested in troubleshooting CI.

Problem: DoesNotExist: Subscription matching query does not exist during getsentry devserver

Solution:

./bin/mock-subscription

You can also 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

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: 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:

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: You use an Android emulator with a DSN pointing to localhost, and the events don't show up in your local Sentry instance.

Solution: Change localhost to 10.0.2.2. So, for example, change http://d895df97e1cb4a33b4dff8af3e78da09@localhost:8000/2 to http://d895df97e1cb4a33b4dff8af3e78da09@10.0.2.2:8000/2. This is because localhost or 127.0.0.1 refers to the emulator's own loopback interface, not the loopback interface of the host machine. For more information see https://developer.android.com/studio/run/emulator-networking.