Configurationedit

To adapt the Elastic APM agent to your needs, you can configure it using environment variables, or framework specific configuration.

Djangoedit

To configure Django, add an ELASTIC_APM dictionary to your settings.py:

ELASTIC_APM = {
    'APP_NAME': 'my-app',
    'SECRET_TOKEN': 'changeme,
}

Flaskedit

To configure Flask, add an ELASTIC_APM dictonary to your app.config:

app.config['ELASTIC_APM'] = {
    'APP_NAME': 'my-app',
    'SECRET_TOKEN': 'changeme,
}

apm = ElasticAPM(app)

Required optionsedit

app_nameedit

Environment Django/Flask Default Example

ELASTIC_APM_APP_NAME

APP_NAME

None

my-app

The name of your app. This is used to keep all the errors and transactions of your app together and is the primary filter in the Elastic APM user interface.

Note

The app name must conform to this regular expression: ^[a-zA-Z0-9 _-]+$. In less regexy terms: Your app name must only contain characters from the ASCII alphabet, numbers, dashes, underscores and spaces.

serversedit

Environment Django/Flask Default

ELASTIC_APM_SERVERS

SERVERS

['http://localhost:8200']

multiple values separated by commas, without spaces

A list of URLs for your APM Servers. The URL must be fully qualified, including protocol (http or https) and port.

Note

if you configure multiple servers, errors and transactions are sent to each server.

transport_classedit

Environment

Django/Flask

Default

ELASTIC_APM_TRANSPORT_CLASS

TRANSPORT_CLASS

elasticapm.transport.http_urllib3.AsyncUrllib3Transport

The transport class to use when sending events to the APM server. The default AsyncUrllib3Transport uses a background thread to send data. If your environment doesn’t allow background threads, you can use elasticapm.transport.http_urllib3.Urllib3Transport instead. Note however that this can have adverse effects on performance.

Other optionsedit

secret_tokenedit

Environment Django/Flask Default Example

ELASTIC_APM_SECRET_TOKEN

SECRET_TOKEN

None

A random string

This string is used to ensure that only your agents can send data to your APM servers. Both the agents and the APM servers have to be configured with the same secret token. One example to generate a secure secret token is:

python -c "import uuid; print(str(uuid.uuid4()))"
Warning

secret tokens only provide any security if your APM servers use TLS.

app_versionedit

Environment Django/Flask Default Example

ELASTIC_APM_APP_VERSION

APP_VERSION

None

A string indicating the version of the deployed app

A version string for the currently deployed version of the app. If you don’t version your deployments, the recommended value for this field is the commit identifier of the deploved revision, e.g. the output of git rev-parse HEAD.

filter_exception_typesedit

Environment Django/Flask Default Example

ELASTIC_APM_FILTER_EXCEPTION_TYPES

FILTER_EXCEPTION_TYPES

[]

['OperationalError', 'mymodule.SomeoneElsesProblemError']

multiple values separated by commas, without spaces

A list of exception types to be filtered. Exceptions of these types will not be sent to the APM server.

transactions_ignore_patternsedit

Environment Django/Flask Default Example

ELASTIC_APM_TRANSACTIONS_IGNORE_PATTERNS

TRANSACTIONS_IGNORE_PATTERNS

[]

['^OPTIONS ', 'myviews.Healthcheck']

multiple values separated by commas, without spaces

A list of regular expressions. Transactions that match any of the of the configured patterns will be ignored and not sent to the APM server.

timeoutedit

Environment Django/Flask Default

ELASTIC_APM_TIMEOUT

TIMEOUT

5

A timeout in seconds. If a request to the APM server takes longer than the configured timeout, the request is cancelled and the event (exception or transaction) is discarded. Set to None to disable timeouts.

Warning

If timeouts are disabled or set to a high value, your app could experience memory issues if the APM server times out.

hostnameedit

Environment Django/Flask Default Example

ELASTIC_APM_HOSTNAME

HOSTNAME

socket.gethostname()

app-server01.example.com

The host name to use when sending error and transaction data to the APM server.

auto_log_stacksedit

Environment Django/Flask Default

ELASTIC_APM_AUTO_LOG_STACKS

AUTO_LOG_STACKS

True

set to "true" / "false"

If set to True (the default), the agent will add a stack trace to each log event, indicating where the log message has been issued.

This setting can be overridden on an individual basis by setting the extra-key stack:

logger.info('something happened', extra={'stack': False})

traces_send_frequencyedit

Environment

Django/Flask

Default

ELASTIC_APM_TRACES_SEND_FREQ

TRACES_SEND_FREQ

60

Interval with which transactions should be sent to the APM server, in seconds. A lower value will increase the load on your APM server, while a higher value can increase the memory pressure of your app. A higher value also impacts the time until transactions are indexed and searchable in Elasticsearch.

processorsedit

Environment

Django/Flask

Default

ELASTIC_APM_PROCESSORS

PROCESSORS

['elasticapm.processors.sanitize_stacktrace_locals', 'elasticapm.processors.sanitize_http_request_cookies', 'elasticapm.processors.sanitize_http_headers', 'elasticapm.processors.sanitize_http_wsgi_env', 'elasticapm.processors.sanitize_http_request_querystring', 'elasticapm.processors.sanitize_http_request_body']

A list of processors to process transactions and errors. For more information, see Sanitizing Data.

Warning

We recommend to always include the default set of validators if you customize this setting.

include_pathsedit

Environment

Django/Flask

Default

ELASTIC_APM_INCLUDE_PATHS

INCLUDE_PATHS

Depending on framework

multiple values separated by commas, without spaces

A set of module paths that should be considered when detecting if a stacktrace frame is a library frame or an "in-app" frame. For Django, the default set is the list of INSTALLED_APPS, but without django.contrib apps. For Flask, it’s the app module.

Note

for a given module path, all sub-modules will also match. E.g. foo.bar also matches for foo.bar.baz.

exclude_pathsedit

Environment

Django/Flask

Default

ELASTIC_APM_EXCLUDE_PATHS

EXCLUDE_PATHS

Depending on framework

multiple values separated by commas, without spaces

A set of module paths that should be considered when excluding a frame from being detected as an in-app frame. exclude_paths takes precedence over include_paths.

For Django, the default is set to {'elasticapm', 'django'}. Everywhere else, the default is set(['elasticapm']).

Note

for a given module path, all sub-modules will also match. E.g. foo.bar also matches for foo.bar.baz.

debugedit

Environment

Django/Flask

Default

ELASTIC_APM_DEBUG

DEBUG

False

If your app is in debug mode (e.g. in Django with settings.DEBUG = True or in Flask with app.debug = True), the agent won’t send any data to the APM server. You can override it by changing this setting to True.

disable_sendedit

Environment

Django/Flask

Default

ELASTIC_APM_DISABLE_SEND

DISABLE_SEND

False

If set to True, the agent won’t send any events to the APM server, independent of any debug state.

disable_instrumentationedit

Environment

Django/Flask

Default

ELASTIC_APM_DISABLE_INSTRUMENTATION

DISABLE_INSTRUMENTATION

False

If set to True, the agent won’t instrument any code. This disables most of the tracing functionality, but can be useful to debug possible instrumentation issues.