Configuration

This document describes configuration available to the Sentry server itself.

First Install

During a new install, Sentry prompts first for a walkthrough of the Installation Wizard. This wizard will help you get a few essential configuration options taken care of before beginning. Once done, you will be left with two files:

config.yml
The YAML configuration was introduced in Sentry 8 and will allow you to configure various core attributes. Over time this will be expanded.

sentry.conf.py
The Python file will be loaded once all other configuration is referenced, and allows you to configure various server settings as well as more complex tuning.

Many settings available in config.yml will also be able to be configured in the Sentry UI. Declaring them in the file will generally override the dynamically configured value and prevent it from being changed in the UI. These same settings can also be configured via the sentry config CLI helper.

General

SENTRY_ENVIRONMENT

Declared in System Environment

The environment name for this installation. This will also control defaults for things like DEBUG.

Copied
SENTRY_ENVIRONMENT=production sentry ...

system.admin-email

Declared in config.yaml

The technical contact address for this installation. This will be reported to upstream to the Sentry team (as part of the Beacon), and will be the point of contact for critical updates and security notifications.

Copied
system.admin-email: "admin@example.com"

system.url-prefix

Declared in config.yaml

The URL prefix in which Sentry is accessible. This will be used both for referencing URLs in the UI, as well as in outbound notifications. This only works for scheme, hostname and port. In particular, it does not work for path (we supported this years ago, but it became too difficult to maintain). Sentry needs to be at the root of its own (sub)domain or IP address.

Copied
system.url-prefix: "https://sentry.example.com"

system.secret-key

Declared in config.yaml

A secret key used for session signing. If this becomes compromised it’s important to regenerate it as otherwise its much easier to hijack user sessions.

Copied
system.secret-key: "a-really-long-secret-value"

To generate a new value, we’ve provided a helper:

Copied
sentry config generate-secret-key

Logging

Sentry logs to two major places — stdout, and its internal project. To disable logging to the internal project, add a logger whose only handler is 'console' and disable propagating upwards.

-l/--loglevel

Declared on the command line

Sentry can override logger levels by providing the CLI with the -l/--loglevel flag.

The value of this can be one of the standard Python logging level strings.

Copied
sentry --loglevel=WARNING

SENTRY_LOG_LEVEL

Declared in System Environment

Sentry can override logger levels with the SENTRY_LOG_LEVEL environment variable.

The value of this can be one of the standard Python logging level strings.

Copied
SENTRY_LOG_LEVEL=WARNING sentry ...

LOGGING

Declared in sentry.conf.py

You can modify or override the full logging configuration with this setting. Be careful not to remove or override important defaults. You can check the default configuration for reference.

Copied
LOGGING['default_level'] = 'WARNING'

If logging in a particular module is not showing up when you expect it to, you should check the log level for that module in src/sentry/conf/server.py in the LOGGING variable.

Redis

redis.clusters

Declared in config.yaml

Describes the Redis clusters available to the Sentry server. These clusters may then be referenced by name by other internal services such as the cache, digests, and TSDB backends, among others.

For example,

Copied
redis.clusters:
  default: # cluster name
    hosts: # connection options, passed to `rb.Cluster`
      0:
        host: redis-1.example.com
        port: 6379
      1:
        host: redis-2.example.com
        port: 6379
  other:
    hosts:
      0:
        host: redis-3.example.com
        port: 6379

Authentication

The following keys control the authentication support.

auth.allow-registration

Declared in config.yaml

Should Sentry allow users to create new accounts?

Defaults to False.

This setting only controls public registration. Users can still register new accounts via Single Sign-On and membership invites.

Copied
auth.allow-registration: true

Note: This setting is often configured via the UI.

SENTRY_PUBLIC

Declared in sentry.conf.py

Should Sentry make all data publicly accessible? This should only be used if you’re installing Sentry behind your company’s firewall.

Users will still need to have an account to view any data.

Defaults to False.

Copied
SENTRY_PUBLIC = True

SENTRY_ALLOW_ORIGIN

Declared in sentry.conf.py

Note: This setting has changed, and no longer applies to /api/store/ requests.

If provided, Sentry will set the Access-Control-Allow-Origin header on all web API responses.

You can read more about these headers in the Mozilla developer docs.

Defaults to * (allow API access from any domain)

Copied
SENTRY_ALLOW_ORIGIN = "http://foo.example"

Web Server

The following settings are available for the built-in webserver:

SENTRY_WEB_HOST

Declared in sentry.conf.py

The hostname which the webserver should bind to.

Defaults to localhost.

Copied
SENTRY_WEB_HOST = '0.0.0.0'  # bind to all addresses

SENTRY_WEB_PORT

Declared in sentry.conf.py

The port which the webserver should listen on.

Defaults to 9000.

Copied
SENTRY_WEB_PORT = 9000

SENTRY_WEB_OPTIONS

Declared in sentry.conf.py

A dictionary of additional configuration options to pass to uwsgi.

Defaults to {}.

Copied
SENTRY_WEB_OPTIONS = {
    'workers': 10,
    'buffer-size': 32768,
}

Additionally, if you’re using SSL, you’ll want to configure the following settings in sentry.conf.py:

Copied
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

GitHub App Integration

github-app.id

Declared in config.yaml

Your GitHub App ID.

github-app.name

Declared in config.yaml

The name of your GitHub App.

github-app.webhook-secret

Declared in config.yaml

The secret used to verify GitHub App Webhook event.

github-app.private-key

Declared in config.yaml

Your app's private key, best to use multiline:

Copied
github-app.private-key: |
  -----BEGIN RSA PRIVATE KEY-----
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  privatekeyprivatekeyprivatekeyprivatekey
  -----END RSA PRIVATE KEY-----

github-app.client-id

Declared in config.yaml

Your GitHub App's Client ID.

github-app.client-secret

Declared in config.yaml

Your GitHub App's Client Secret.

Azure DevOps Integration

First create an Azure DevOps App

vsts.client-id

Declared in config.yaml

Your Azure DevOps application App ID

vsts.client-secret

Declared in config.yaml

Your Azure DevOps application App Secret

You can edit this page on GitHub.