Configuration

The following settings are configured on the Alerta server. For alerta CLI configuration options see command-line reference and for Web UI configuration options see web UI reference.

The configuration file uses standard python syntax for setting variables. The default settings (defined in settings.py) should not be modified directly.

To change any of these settings create a configuration file that overrides these default settings. The default location for the server configuration file is /etc/alertad.conf however the location itself can be overridden by using a environment variable ALERTA_SVR_CONF_FILE.

For example, to set the blackout period default duration to 1 day (ie. 86400 seconds):

$ export ALERTA_SVR_CONF_FILE=~/.alertad.conf
$ echo "BLACKOUT_DURATION = 86400" >$ALERTA_SVR_CONF_FILE

Config File Settings

General Settings

Example

DEBUG = True
SECRET_KEY = 'changeme'
BASE_URL = '/api'
USE_PROXYFIX = False
LOGGER_NAME = 'alerta-api'
LOG_FILE = '/var/log/alertad.log'
LOG_MAX_BYTES = 5*1024*1024  # 5 MB
LOG_BACKUP_COUNT = 2
LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
DEBUG
debug mode for increased logging (default is False)
SECRET_KEY
a unique, randomly generated sequence of ASCII characters.
BASE_URL
if API served on a path or behind a proxy use it to fix relative links (no default)
USE_PROXYFIX
if API served behind SSL terminating proxy (default is False)
LOGGER_NAME
name of logger used by python logging module (default is alerta)
LOG_FILE
full path to write rotating server log file (no default)
LOG_MAX_BYTES
maximum size of log file before rollover (default is 10 MB)
LOG_BACKUP_COUNT
number of rollover files before older files are deleted (default is 2)
LOG_FORMAT
log file format string

API Settings

Example

ALARM_MODEL='ALERTA'
DEFAULT_FIELD = 'text'
DEFAULT_PAGE_SIZE = 1000
HISTORY_LIMIT = 100
HISTORY_ON_VALUE_CHANGE = False  # do not log if only value changes
ALARM_MODEL
set to ISA_18_2 to use experimental alarm model (default is ALERTA)
DEFAULT_FIELD
search default field when no field given when using lucene query syntax (default is text)
DEFAULT_PAGE_SIZE
maximum number of alerts returned in a single query (default 1000)
HISTORY_LIMIT
number of history entries for each alert before old entries are deleted (default 100)
HISTORY_ON_VALUE_CHANGE
create history entry for duplicate alerts if value changes (default True)

Database Settings

There is a choice of either Postgres or MongoDB as the backend database.

The database is defined using the standard database connection URL formats. Many database configuration options are supported as connection URL parameters.

Postgres Example

DATABASE_URL = 'postgresql://[email protected]/otherdb?connect_timeout=10&application_name=myapp'
DATABASE_NAME = 'monitoring'

See Postgres connection strings for more information.

MongoDB Example

DATABASE_URL = 'mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000'
DATABASE_NAME = 'monitoring'
DATABASE_RAISE_ON_ERROR = False  # creating tables & indexes manually

See MongoDB connection strings for more information.

DATABASE_URL
database connection string (default is mongodb://localhost:27017/monitoring)
DATABASE_NAME
database name can be used to override database in connection string (no default)
DATABASE_RAISE_ON_ERROR
terminate startup if database configuration fails (default is True)

Bulk API Settings

The bulk API requires a Celery backend and can be used to off-load long-running tasks. (experimental)

Example Redis Task Queue

BULK_QUERY_LIMIT = 10000
CELERY_BROKER_URL='redis://localhost:6379/0'
CELERY_RESULT_BACKEND='redis://localhost:6379/0'
BULK_QUERY_LIMIT
limit the number of tasks in a single bulk query (default is 100000)
CELERY_BROKER_URL
URL of Celery-supported broker (no default)
CELERY_RESULT_BACKEND
URL of Celery-supported result backend (no default)

Authentication Settings

If enabled, authentication provides additional benefits beyond just security, such as auditing, and features like the ability to assign and watch alerts.

Example

AUTH_REQUIRED = True
AUTH_PROVIDER = 'basic'
ADMIN_USERS = ['[email protected]', '[email protected]']
USER_DEFAULT_SCOPES = ['read', 'write:alerts']
CUSTOMER_VIEWS = True
SIGNUP_ENABLED = False
ALLOWED_EMAIL_DOMAINS = ['alerta.io', 'example.com']
TOKEN_EXPIRE_DAYS = 4*365  # 4 years

LDAP_URL = 'ldap://openldap'
LDAP_DOMAINS = {
    'my-domain.com': 'cn=%s,dc=my-domain,dc=com'
}
AUTH_REQUIRED
users must authenticate when using web UI or command-line tool (default False)
AUTH_PROVIDER
valid authentication providers are basic, github, gitlab, google, keycloak, pingfederate, saml2 (default is basic)
ADMIN_USERS
email addresses or logins that have admin role
USER_DEFAULT_SCOPES
default permissions assigned to logged in users (default is ['read', 'write'])
CUSTOMER_VIEWS
alert views partitioned by customer (default is False)
BASIC_AUTH_REALM
BasicAuth authentication realm (default is Alerta)
SIGNUP_ENABLED
prevent sign-up of new users via the web UI (default is True)
OAUTH2_CLIENT_ID
client ID required by OAuth2 providers (no default)
OAUTH2_CLIENT_SECRET
client secret required by OAuth2 providers (no default)
ALLOWED_EMAIL_DOMAINS
authorised email domains when using email as login (default is *)
GITHUB_URL
API URL for privately run GitHub Enterprise server when using GitHub as OAuth2 provider (no default)
ALLOWED_GITHUB_ORGS
authorised GitHub organisations a user must belong to when using Github as OAuth2 provider (default is *)
GITLAB_URL
API URL for public or privately run GitLab server when using GitLab as OAuth2 provider (default is https://gitlab.com)
ALLOWED_GITLAB_GROUPS
authorised GitLab groups a user must belong to when using GitLab as OAuth2 provider (default is *)
LDAP_URL
URL of the LDAP server (no default)
LDAP_DOMAINS
dictionary of LDAP domains and LDAP search filters (no default)
PINGFEDERATE_URL
PingFederate OpenID access token URL (no default)
PINGFEDERATE_PUBKEY_LOCATION
PingFederate public key location (no default)
PINGFEDERATE_TOKEN_ALGORITHM
PingFederate JWT token algorithm (no default)
PINGFEDERATE_OPENID_PAYLOAD_USERNAME
PingFederate JWT user attribute name (no default)
PINGFEDERATE_OPENID_PAYLOAD_EMAIL
PingFederate JWT email attribute name (no default)
PINGFEDERATE_OPENID_PAYLOAD_GROUP
PingFederate JWT group attribute name (no default)
KEYCLOAK_URL
Keycloak website URL when using Keycloak as OAuth2 provider (no default)
KEYCLOAK_REALM
Keycloak realm when using Keycloak as OAuth2 provider (no default)
ALLOWED_KEYCLOAK_ROLES
list of authorised Keycloak roles a user must belong to when using Keycloak as OAuth2 provider (default is *)
SAML2_CONFIG
pysaml2 configuration dict. See SAML 2.0 Authentication (no default)
ALLOWED_SAML2_GROUPS
list of authorised groups a user must belong to. See SAML 2.0 Authentication for details (default is *)
SAML2_USER_NAME_FORMAT
Python format string which will be rendered to user’s name using SAML attributes. See SAML 2.0 Authentication (default is '{givenName} {surname}')
TOKEN_EXPIRE_DAYS
number of days a bearer token is valid (default is 14)
API_KEY_EXPIRE_DAYS
number of days an API key is valid (default is 365)

Audit Log Settings

Audit events can be logged locally to the standard application log (which could also help with general debugging) or forwarded to a HTTP endpoint using a POST.

Example

AUDIT_TRAIL = ['admin', 'write', 'auth']
AUDIT_LOG = True  # log to Flask application logger
AUDIT_URL = 'https://listener.logz.io:8071/?token=TOKEN'
AUDIT_TRAIL
audit trail for admin, write or auth changes. (default is ['admin'])
AUDIT_LOG
enable audit logging to configured application log file (default is False)
AUDIT_URL
forward audit logs to HTTP POST URL (no default)

CORS Settings

Example

CORS_ORIGINS = [
    'http://localhost',
    'http://localhost:8000',
    r'https?://\w*\.?local\.alerta\.io:?\d*/?.*'  # => http(s)://*.local.alerta.io:<port>
]
CORS_ORIGINS
URL origins that can access the API for Cross-Origin Resource Sharing (CORS)

Severity Settings

The severities and their order are customisable to fit with the environment in which Alerta is deployed.

Example

SEVERITY_MAP = {
    'critical': 1,
    'warning': 4,
    'indeterminate': 5,
    'ok': 5,
    'unknown': 9
}
DEFAULT_NORMAL_SEVERITY = 'ok'  # 'normal', 'ok', 'cleared'
DEFAULT_PREVIOUS_SEVERITY = 'indeterminate'

COLOR_MAP = {
    'severity': {
        'critical': 'red',
        'warning': '#1E90FF',
        'indeterminate': 'lightblue',
        'ok': '#00CC00',
        'unknown': 'silver'
    },
    'text': 'black',
    'highlight': 'skyblue '
}
SEVERITY_MAP
dictionary of severity names and levels
DEFAULT_NORMAL_SEVERITY
severity to be assigned to new alerts (default is normal)
DEFAULT_PREVIOUS_SEVERITY
previous severity to be assigned to new alerts (default is indeterminate)
COLOR_MAP
dictionary of severity colors, text and highlight color

Timeout Settings

Alert timeouts are important for housekeeping and heartbeat timeouts are important for generating alerts from stale heartbeats.

Example

ALERT_TIMEOUT = 43200  # 12 hours
HEARTBEAT_TIMEOUT = 7200  # 2 hours
ALERT_TIMEOUT
default timeout period in seconds for alerts (default is 86400)
HEARTBEAT_TIMEOUT
default timeout period in seconds for heartbeats (default is 86400)

Email Settings

If email verification is enabled then emails are sent to users when they sign up via BasicAuth. They must click on the provided link to verify their email address before they can login.

Example

EMAIL_VERIFICATION = True
SMTP_HOST = 'smtp.example.com'
MAIL_FROM = '[email protected]'
EMAIL_VERIFICATION
enforce email verification of new users (default is False)
SMTP_HOST
SMTP host of mail server (default is smtp.gmail.com)
SMTP_PORT
SMTP port of mail server (default is 587)
MAIL_LOCALHOST
mail server to use in HELO/EHLO command (default is localhost)
SMTP_STARTTLS
SMTP connection in TLS (Transport Layer Security) mode. All SMTP commands that follow will be encrypted (default is False)
SMTP_USE_SSL
used for situations where SSL is required from the beginning of the connection and using SMTP_STARTTLS is not appropriate (default is False)
SSL_KEY_FILE
a PEM formatted private key file for the SSL connection(no default)
SSL_CERT_FILE
a PEM formatted certificate chain file for the SSL connection (no default)
MAIL_FROM
valid email address from which emails are sent (no default)
SMTP_USERNAME
application-specific username, if different to MAIL_FROM user (no default)
SMTP_PASSWORD
application-specific password for MAIL_FROM or SMTP_USERNAME (no default)

Web UI Settings

The following settings are specific to the web UI and are not used by the server.

Example

SITE_LOGO_URL = 'http://pigment.github.io/fake-logos/logos/vector/color/fast-banana.svg'
DATE_FORMAT_SHORT_TIME = 'HH:mm'
DATE_FORMAT_MEDIUM_DATE = 'EEE d MMM HH:mm'
DATE_FORMAT_LONG_DATE = 'd/M/yyyy h:mm:ss.sss a'
DEFAULT_AUDIO_FILE = '/audio/Bike Horn.mp3'
COLUMNS = ['severity', 'status', 'lastReceiveTime', 'duplicateCount',
        'customer', 'environment', 'service', 'resource', 'event', 'value', 'text']
SORT_LIST_BY = 'lastReceiveTime'
ACTIONS = ['createIssue', 'updateIssue']
GOOGLE_TRACKING_ID = 'UA-44644195-5'
AUTO_REFRESH_INTERVAL = 30000  # 30s
SITE_LOGO_URL
URL of company logo to replace “alerta” in navigation bar (no default)
DATE_FORMAT_SHORT_TIME
format used for time in columns eg. 09:24 (default is HH:mm)
DATE_FORMAT_MEDIUM_DATE
format used for dates in columns eg. Tue 9 Oct 09:24 (default is EEE d MMM HH:mm)
DATE_FORMAT_LONG_DATE
format used for date and time in detail views eg. 9/10/2018 9:24:03.036 AM (default is d/M/yyyy h:mm:ss.sss a)
DEFAULT_AUDIO_FILE
make sound when new alert arrives. must exist on client at relative path eg. /audio/Bike Horn.mp3 (no default)
COLUMNS
user defined columns and column order for alert list view (default is standard web console column order)
SORT_LIST_BY
to sort by newest use lastReceiveTime or oldest use -createTime. minus means reverse (default is lastReceiveTime)
ACTIONS
adds buttons to web console for operators to trigger custom actions against alert (no default)
GOOGLE_TRACKING_ID
used by the web UI to send tracking data to Google Analytics (no default)
AUTO_REFRESH_INTERVAL
interval in milliseconds at which the web UI refreshes alert list (default is 5000)

Plugin Settings

Plugins are used to extend the behaviour of the Alerta server without having to modify the core application. The only plugins that are installed and enabled by default are the reject and blackout plugins. Other plugins are available in the contrib repo.

Example

PLUGINS = ['reject', 'blackout', 'slack']
PLUGINS_RAISE_ON_ERROR = False  # keep processing other plugins if exception
PLUGINS
list of enabled plugins (default ['reject', 'blackout'])
PLUGINS_RAISE_ON_ERROR
stop processing plugins if there is an exception (default is True)

Reject Plugin Settings

Alerts can be rejected based on the origin or environment alert attributes.

Example

ORIGIN_BLACKLIST = ['foo/bar$', '.*/qux']  # reject all foo alerts from bar, and everything from qux
ALLOWED_ENVIRONMENTS = ['Production', 'Development', 'Testing']
ORIGIN_BLACKLIST
list of alert origins blacklisted from submitting alerts. useful for rouge alert sources (no default)
ALLOWED_ENVIRONMENTS
list of allowed environments. useful for enforcing discrete set of environments (default is ['Production', 'Development'])

Note

To disable the reject plugin simply remove it from the list of enabled plugins in the PLUGINS configuration setting to override the default.

Blackout Plugin Settings

Alerts can be suppressed based on alert attributes for arbitrary durations known as “blackout periods”. An alert received during a blackout period is rejected, by default.

Example

BLACKOUT_DURATION = 7200  # 2 hours
NOTIFICATION_BLACKOUT = True
BLACKOUT_ACCEPT = ['normal', 'ok', 'cleared']
BLACKOUT_DURATION
default period for an alert blackout (default is 3600)
NOTIFICATION_BLACKOUT
instead of rejecting alerts received during blackout periods, set status of alert to blackout and do not forward to plugins (default is False)
BLACKOUT_ACCEPT
used with NOTIFICATION_BLACKOUT if alerts with status of blackout should still be closed by “ok” alerts (no default)

Environment Variables

Some configuration settings are special because they can be overridden by environment variables. This is to make deployment to different platforms and managed environments such as Heroku, Kubernetes and AWS easier, or to make use of managed Postgres or MongoDB services.

Note

Environment variables are read after configuration files so they will always override any other setting.

General Settings

DEBUG
see above
BASE_URL
see above
USE_PROXYFIX
see above
SECRET_KEY
see above
AUTH_REQUIRED
see above
AUTH_PROVIDER
see above
ADMIN_USERS
see above
CUSTOMER_VIEWS
see above
OAUTH2_CLIENT_ID
see above
OAUTH2_CLIENT_SECRET
see above
ALLOWED_EMAIL_DOMAINS
see above
GITHUB_URL
see above
ALLOWED_GITHUB_ORGS
see above
GITLAB_URL
see above
ALLOWED_GITLAB_GROUPS
see above
KEYCLOAK_URL
see above
KEYCLOAK_REALM
see above
ALLOWED_KEYCLOAK_ROLES
see above
PINGFEDERATE_OPENID_ACCESS_TOKEN_URL
see above
PINGFEDERATE_OPENID_PAYLOAD_USERNAME
see above
PINGFEDERATE_OPENID_PAYLOAD_EMAIL
see above
PINGFEDERATE_OPENID_PAYLOAD_GROUP
see above
PINGFEDERATE_PUBKEY_LOCATION
see above
PINGFEDERATE_TOKEN_ALGORITHM
see above
CORS_ORIGINS
see above
MAIL_FROM
see above
SMTP_PASSWORD
see above
GOOGLE_TRACKING_ID
see above
PLUGINS
see above

Database Settings

DATABASE_URL
used by both Postgres and MongoDB for database connection strings
DATABASE_NAME
database name can be used to override default database defined in DATABASE_URL

MongoDB Settings

Deprecated since version 5.0: Use DATABASE_URL and DATABASE_NAME instead.

MONGO_URI
used to override MONGO_URI config variable using the standard connection string format
MONGODB_URI
alternative name for MONGO_URI environment variable which is used by some managed services
MONGOHQ_URL
automatically set when using Heroku MongoHQ managed service
MONGOLAB_URI
automatically set when using Heroku MongoLab managed service
MONGO_PORT
automatically set when deploying Alerta to a Docker linked mongo container

Dynamic Settings

Using the management switchboard on the API some dynamic settings can be switched on and off without restarting the Alerta server daemon.

Currently, there is only one setting that can be toggled in this way and it is the Auto-refresh allow switch.

Auto-Refresh Allow

The Alerta Web UI will automatically referesh the list of alerts in the alert console every 5 seconds.

If for whatever reason, the Alerta API is experiencing heavy load the auto_refresh_allow switch can be turned off and the Web UI will respect that and switch to manual refresh mode. The Alerta web UI will start auto-refereshing again if the auto_refresh_allow switch is turned back on.