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

Bash

Copied

SENTRY_ENVIRONMENT=production sentry ...

system.admin-email

Declared in config.yml.

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.

YAML

Copied

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

system.url-prefix

Declared in config.yml.

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.

YAML

Copied

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

system.secret-key

Declared in config.yml.

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.

YAML

Copied

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

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

Shell

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](https://docs.python.org/2/library/logging.html#levels).

Shell

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](https://docs.python.org/2/library/logging.html#levels).

Shell

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](https://git.io/fjjna) for reference.

Python

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.

Corporate Users Only

If you are a Sentry employee who is looking for logs in Kibana and they aren't showing up when you expect them to, one potential reason is that a field in the log message does not match Elasticsearch's schema. See the index patterns here.

Redis

redis.clusters

Declared in config.yml.

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,

YAML

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.

SENTRY_FEATURES['auth:register']

Declared in sentry.conf.py.

Should Sentry allow users to create new accounts?

Defaults to True (can register).

SENTRY_FEATURES['auth:register'] = True

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.

SENTRY_PUBLIC = True

SENTRY_ALLOW_ORIGIN

Declared in sentry.conf.py.

If provided, Sentry will set the Access-Control-Allow-Origin header to this value on /api/store/ responses. In addition, the Access-Control-Allow-Headers header will be set to ‘X-Sentry-Auth’. This allows JavaScript clients to submit cross-domain error reports.

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

Defaults to None (don’t add the Access-Control headers)

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.

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.

SENTRY_WEB_PORT = 9000

SENTRY_WEB_OPTIONS

Declared in sentry.conf.py.

A dictionary of additional configuration options to pass to uwsgi.

Defaults to {}.

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:

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

Your GitHub App ID.

github-app.name

Declared in config.yml.

The name of your GitHub App.

github-app.webhook-secret

Declared in config.yml.

The secret used to verify GitHub App Webhook event.

github-app.private-key

Declared in config.yml.

Your app's private key.

github-app.client-id

Declared in config.yml.

Your GitHub App's Client ID.

github-app.client-secret

Declared in config.yml.

Your GitHub App's Client Secret.

Azure DevOps Integration

First create an Azure DevOps App

vsts.client-id

Declared in config.yml.

Your Azure DevOps application App ID

vsts.client-secret

Declared in config.yml.

Your Azure DevOps application App Secret