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.

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.

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

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:

Copied
sentry devservices up

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

Copied
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.

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

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.

Copied
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.

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:

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

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

Copied
sentry devservices rm snuba
sentry devservices up snuba

See also: Sentry vs Getsentry

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

Copied
sentry devservices up

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

Copied
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

Copied
getsentry devserver --workers --ingest

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.

Copied
# 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.

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

Copied
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

Copied
# 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.

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

Copied
# 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

You might also be interested in troubleshooting CI.


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

Solution:

Copied
./bin/mock-subscription

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

Copied
./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:

Copied
make build-platform-assets

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

Or:

Copied
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.

Copied
brew upgrade --cask chromedriver

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

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

Copied
./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:

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

Copied
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.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").