Environment

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.

NOTE: After running devenv sync you may need to restart your terminal to continue.

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

Optionally, you may wish to run the development server over HTTPS, for certain situations (like testing JS APIs that require a secure context).

First we will use mkcert to create and install a locally-trusted, development certificate and Caddy as our reverse proxy.

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

Then we will run the reverse proxy as needed:

yarn https-proxy

After the server is running we can visit the dev server using https at port :8003 instead of over http at :8000.

Ingestion Pipeline (Relay) aka Sending Events to your Dev Environment

Relay and the ingest workers are not started by default. Follow the instructions below to start them so you can send events to your dev environment Sentry instance:

• Set SENTRY_USE_RELAY = True in ~/.sentry/sentry.conf.py. This will tell sentry devservices up to also start services that Relay needs.
• Run sentry devservices up to start the services Relay needs. (like for example Kafka)
• (Re-)Start your devserver with the --ingest flag (e.g. sentry devserver --workers --ingest). This will start the Relay container and all related services alongside your devserver.

Note: To update Relay, manually run sentry devservices up --skip-only-if relay.

Metrics Ingestion Pipeline

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

Before running getsentry, you might need to run devenv sync inside the getsentry directory if you have previously run sentry locally, as there might be differences between the environments.

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, access it at http://dev.getsentry.net:8000. Using localhost won't work. Note that the http protocol is used, not https. If you encounter a certificate error while accessing it locally, it might be because your browser has remembered that dev.getsentry.net previously used the https protocol (possibly while running yarn dev-ui) and is now redirecting all http requests to https. To resolve this, open the site in an incognito window of your browser.

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

Refer to ngrok docs.

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

The more up-to-date troubleshooting docs for the internal development environment on MacOS are here.

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 devenv sync.

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.

Problem: Switching from Docker Desktop to Colima results in error Failed to start service: Credentials store error: StoreError('docker-credential-desktop not installed or not available in PATH')

Solution: Remove the credsStore key in your ~/.docker/config.json file.