A newer version is available. For the latest information, see the current release documentation.
« Supported Technologies Advanced Topics »
Elastic Docs ›

Configuration

edit

Configuration

edit

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

You can either configure the agent by setting environment variables:

ELASTIC_APM_SERVICE_NAME=foo python manage.py runserver

or with inline configuration:

apm_client = Client(service_name="foo")

or by using framework specific configuration e.g. in your Django settings.py file:

ELASTIC_APM = {
    "SERVICE_NAME": "foo",
}

The precedence is as follows:

  • Central configuration (supported options are marked with dynamic config )
  • environment variables
  • inline configuration
  • framework specific configuration
  • default value

Dynamic configuration

edit

Configuration options marked with the dynamic config badge can be changed at runtime when set from a supported source.

The Python Agent supports Central configuration, which allows you to fine-tune certain configurations from in the APM app. This feature is enabled in the Agent by default, with central_config.

Django

edit

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

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

Flask

edit

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

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

apm = ElasticAPM(app)

Required options

edit

service_name

edit
Environment Django/Flask Default Example

ELASTIC_APM_SERVICE_NAME

SERVICE_NAME

None

my-app

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

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

server_url

edit
Environment Django/Flask Default

ELASTIC_APM_SERVER_URL

SERVER_URL

'http://localhost:8200'

The URL for your APM Server. The URL must be fully qualified, including protocol (http or https) and port.

enabled

edit
Environment Django/Flask Default

ELASTIC_APM_ENABLED

ENABLED

true

Enable or disable the agent. When set to false, the agent will not collect any data, nor start any background threads.

recording

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_RECORDING

RECORDING

true

Enable or disable recording of events. If set to false, then the Python agent does not send any events to the Elastic APM server, and instrumentation overhead is minimized, but the agent will continue to poll the server for configuration changes.

transport_class

edit
Environment Django/Flask Default

ELASTIC_APM_TRANSPORT_CLASS

TRANSPORT_CLASS

elasticapm.transport.http.Transport

The transport class to use when sending events to the APM Server.

Logging Options

edit

log_level

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_LOG_LEVEL

LOG_LEVEL

The logging.logLevel at which the elasticapm logger will log. Available options are:

  • "off" (sets logging.logLevel to 1000)
  • "critical"
  • "error"
  • "warning"
  • "info"
  • "debug"
  • "trace" (sets logging.log_level to 5)

Options are case-insensitive.

Note that this option doesn’t do anything with logging handlers. In order for any logs to be visible, you must either configure a handler (logging.basicConfig will do this for you) or set log_file. This will also override any log level your app has set for the elasticapm logger.

log_file

edit
Environment Django/Flask Default Example

ELASTIC_APM_LOG_FILE

LOG_FILE

""

"/var/log/elasticapm/log.txt"

Enables the agent to log to a file. Disabled by default. The agent will log at the logging.logLevel configured with log_level. Use log_file_size to configure the max size of the log file. This log file will automatically rotate.

Note that setting log_level is required for this setting to do anything.

log_file_size

edit
Environment Django/Flask Default Example

ELASTIC_APM_LOG_FILE_SIZE

LOG_FILE_SIZE

"50mb"

"100mb"

The size of the log file, if log_file is set.

The agent always keeps one backup file when rotating, so the max space that the log files will consume is twice the value of this setting.

Other options

edit

service_node_name

edit
Environment Django/Flask Default Example

ELASTIC_APM_SERVICE_NODE_NAME

SERVICE_NODE_NAME

None

"redis1"

The name of the given service node. This is optional, and if omitted, the APM Server will fall back on system.container.id if available, and finally host.name if necessary.

This option allows you to set the node name manually to ensure uniqueness and meaningfulness.

environment

edit
Environment Django/Flask Default Example

ELASTIC_APM_ENVIRONMENT

ENVIRONMENT

None

"production"

The name of the environment this service is deployed in, e.g. "production" or "staging".

Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See environment selector in the APM app for more information.

This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2.

cloud_provider

edit
Environment Django/Flask Default Example

ELASTIC_APM_CLOUD_PROVIDER

CLOUD_PROVIDER

"auto"

"aws"

This config value allows you to specify which cloud provider should be assumed for metadata collection. By default, the agent will attempt to detect the cloud provider or, if that fails, will use trial and error to collect the metadata.

Valid options are "auto", "aws", "gcp", and "azure". If this config value is set to "none", then no cloud metadata will be collected.

secret_token

edit
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 Server. Both the agents and the APM Server 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()))"

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

api_key

edit
Environment Config key Default Example

ELASTIC_APM_API_KEY

api_key

None

A base64-encoded string

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

This base64-encoded string is used to ensure that only your agents can send data to your APM Server. You must have created the API key using the APM Server command line tool. Please see the APM Server documentation for details on how to do that.

API keys only provide any real security if your APM Server uses TLS.

service_version

edit
Environment Django/Flask Default Example

ELASTIC_APM_SERVICE_VERSION

SERVICE_VERSION

None

A string indicating the version of the deployed service

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

framework_name

edit
Environment Django/Flask Default

ELASTIC_APM_FRAMEWORK_NAME

FRAMEWORK_NAME

Depending on framework

Name of the used framework. For Django and Flask, this defaults to django and flask respectively, otherwise, the default is None.

framework_version

edit
Environment Django/Flask Default

ELASTIC_APM_FRAMEWORK_VERSION

FRAMEWORK_VERSION

Depending on framework

Version number of the used framework. For Django and Flask, this defaults to the used version of the framework, otherwise, the default is None.

filter_exception_types

edit
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_patterns

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

server_timeout

edit
Environment Django/Flask Default

ELASTIC_APM_SERVER_TIMEOUT

SERVER_TIMEOUT

"5s"

A timeout for requests to the APM Server. The setting has to be provided in duration format. 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.

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

hostname

edit
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_stacks

edit
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})

collect_local_variables

edit
Environment Django/Flask Default

ELASTIC_APM_COLLECT_LOCAL_VARIABLES

COLLECT_LOCAL_VARIABLES

errors

Possible values: errors, transactions, all, off

The Elastic APM Python agent can collect local variables for stack frames. By default, this is only done for errors.

collecting local variables has a non-trivial overhead. Collecting local variables for transactions in production environments can have adverse effects for the performance of your service.

local_var_max_length

edit
Environment Django/Flask Default

ELASTIC_APM_LOCAL_VAR_MAX_LENGTH

LOCAL_VAR_MAX_LENGTH

200

When collecting local variables, they will be converted to strings. With this setting, you can limit the length of resulting string.

local_var_list_max_length

edit

Environment

Django/Flask

Default

ELASTIC_APM_LOCAL_VAR_LIST_MAX_LENGTH

LOCAL_VAR_LIST_MAX_LENGTH

10

With this setting, you can limit the length of lists in local variables.

local_var_dict_max_length

edit
Environment Django/Flask Default

ELASTIC_APM_LOCAL_VAR_DICT_MAX_LENGTH

LOCAL_VAR_DICT_MAX_LENGTH

10

With this setting, you can limit the length of dicts in local variables.

source_lines_error_app_frames

edit

source_lines_error_library_frames

edit

source_lines_span_app_frames

edit

source_lines_span_library_frames

edit
Environment Django/Flask Default

ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES

SOURCE_LINES_ERROR_APP_FRAMES

5

ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES

SOURCE_LINES_ERROR_LIBRARY_FRAMES

5

ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES

SOURCE_LINES_SPAN_APP_FRAMES

0

ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES

SOURCE_LINES_SPAN_LIBRARY_FRAMES

0

By default, the APM agent collects source code snippets for errors. With the above settings, you can modify how many lines of source code is collected.

We differ between errors and spans, as well as library frames and app frames.

Especially for spans, collecting source code can have a large impact on storage use in your Elasticsearch cluster.

capture_body

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_CAPTURE_BODY

CAPTURE_BODY

off

For transactions that are HTTP requests, the Python agent can optionally capture the request body (e.g. POST variables).

Possible values: errors, transactions, all, off.

If the request has a body and this setting is disabled, the body will be shown as [REDACTED].

For requests with a content type of multipart/form-data, any uploaded files will be referenced in a special _files key. It contains the name of the field, and the name of the uploaded file, if provided.

request bodies often contain sensitive values like passwords, credit card numbers etc. If your service handles data like this, we advise to only enable this feature with care.

capture_headers

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_CAPTURE_HEADERS

CAPTURE_HEADERS

true

For transactions and errors that happen due to HTTP requests, the Python agent can optionally capture the request and response headers.

Possible values: true, false

request headers often contain sensitive values like session IDs, cookies etc. See our documentation on sanitizing data for more information on how to filter such data.

transaction_max_spans

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_TRANSACTION_MAX_SPANS

TRANSACTION_MAX_SPANS

500

Limits the amount of spans that are recorded per transaction. This is helpful in cases where a transaction creates a very high amount of spans (e.g. thousands of SQL queries). Setting an upper limit will prevent overloading the agent and the APM Server with too much work for such edge cases.

stack_trace_limit

edit
Environment Django/Flask Default

ELASTIC_APM_STACK_TRACE_LIMIT

STACK_TRACE_LIMIT

500

Limits the number of frames captured for each stack trace.

Setting the limit to 0 will disable stack trace collection, while any positive integer value will be used as the maximum number of frames to collect. To disable the limit and always capture all frames, set the value to -1.

span_frames_min_duration

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_SPAN_FRAMES_MIN_DURATION

SPAN_FRAMES_MIN_DURATION

"5ms"

In its default settings, the APM agent will collect a stack trace with every recorded span. While this is very helpful to find the exact place in your code that causes the span, collecting this stack trace does have some overhead.

To collect traces for all spans, independent of the length, set the value to -1. Setting it to a positive value, e.g. 5ms, will limit stack trace collection to spans with durations equal or longer than the given value.

To disable stack trace collection for spans completely, set the value to 0.

Except for the special values -1 and 0, this setting has to be provided in duration format.

api_request_size

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_API_REQUEST_SIZE

API_REQUEST_SIZE

"768kb"

Maximum queue length of the request buffer before sending the request to the APM Server. 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 data is indexed and searchable in Elasticsearch.

This setting is useful to limit memory consumption if you experience a sudden spike of traffic. It has to be provided in size format.

Due to internal buffering of gzip, the actual request size can be a few kilobytes larger than the given limit. By default, the APM Server limits request payload size to 1 MByte.

api_request_time

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_API_REQUEST_TIME

API_REQUEST_TIME

"10s"

Maximum queue time of the request buffer before sending the request to the APM Server. 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 data is indexed and searchable in Elasticsearch.

This setting is useful to limit memory consumption if you experience a sudden spike of traffic. It has to be provided in duration format.

The actual time will vary between 90-110% of the given value, to avoid stampedes of instances that start at the same time.

processors

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

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

sanitize_field_names

edit
Environment Django/Flask Default

ELASTIC_APM_SANITIZE_FIELD_NAMES

SANITIZE_FIELD_NAMES

['authorization', 'password', 'secret', 'passwd', 'token', 'api_key', 'access_token', 'sessionid']

A list of field names to mask when using processors. For more information, see Sanitizing Data.

We recommend always including the default set of field names if you customize this setting.

transaction_sample_rate

edit

dynamic config

Environment Django/Flask Default

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

TRANSACTION_SAMPLE_RATE

1.0

By default, the agent will sample every transaction (e.g. request to your service). To reduce overhead and storage requirements, you can set the sample rate to a value between 0.0 and 1.0. We still record overall time and the result for unsampled transactions, but no context information, labels, or spans.

This setting will be automatically rounded to 4 decimals of precision.

include_paths

edit
Environment Django/Flask Default

ELASTIC_APM_INCLUDE_PATHS

INCLUDE_PATHS

[]

multiple values separated by commas, without spaces

A set of paths, optionally using shell globs (see fnmatch for a description of the syntax). These are matched against the absolute filename of every frame, and if a pattern matches, the frame is considered to be an "in-app frame".

include_paths takes precedence over exclude_paths.

exclude_paths

edit
Environment Django/Flask Default

ELASTIC_APM_EXCLUDE_PATHS

EXCLUDE_PATHS

Varies on Python version and implementation

multiple values separated by commas, without spaces

A set of paths, optionally using shell globs (see fnmatch for a description of the syntax). These are matched against the absolute filename of every frame, and if a pattern matches, the frame is considered to be a "library frame".

include_paths takes precedence over exclude_paths.

The default value varies based on your Python version and implementation, e.g.:

  • PyPy3: ['\*/lib-python/3/*', '\*/site-packages/*']
  • CPython 2.7: ['\*/lib/python2.7/*', '\*/lib64/python2.7/*']

debug

edit
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_send

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

instrument

edit
Environment Django/Flask Default

ELASTIC_APM_INSTRUMENT

INSTRUMENT

True

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

verify_server_cert

edit
Environment Django/Flask Default

ELASTIC_APM_VERIFY_SERVER_CERT

VERIFY_SERVER_CERT

True

By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM Server. Verification can be disabled by changing this setting to False. This setting is ignored when server_cert is set.

SSL certificate verification is only available in Python 2.7.9+ and Python 3.4.3+.

server_cert

edit
Environment Django/Flask Default

ELASTIC_APM_SERVER_CERT

SERVER_CERT

None

If you have configured your APM Server with a self signed TLS certificate, or you just wish to pin the server certificate, you can specify the path to the PEM-encoded certificate via the ELASTIC_APM_SERVER_CERT configuration.

metrics_interval

edit
Environment Django/Flask Default

ELASTIC_APM_METRICS_INTERVAL

METRICS_INTERVAL

30s

The interval in which the agent collects metrics. A shorter interval increases the granularity of metrics, but also increases the overhead of the agent, as well as storage requirements.

It has to be provided in duration format.

disable_metrics

edit
Environment Django/Flask Default

ELASTIC_APM_DISABLE_METRICS

DISABLE_METRICS

None

A comma-separated list of dotted metrics names that should not be sent to the APM Server. You can use * to match multiple metrics. As an example, to disable all CPU-related metrics, as well as the "total system memory" metric, you would set disable_metrics to:

"*.cpu.*,system.memory.total"

this setting only disables the sending of the given metrics, not collection.

breakdown_metrics

edit
Environment Django/Flask Default

ELASTIC_APM_BREAKDOWN_METRICS

BREAKDOWN_METRICS

True

Enable/disable the tracking and collection of breakdown metrics. By setting this to False, tracking this metric is completely disabled, which can reduce the overhead of the agent.

This feature requires APM Server and Kibana >= 7.3.

central_config

edit
Environment Django/Flask Default

ELASTIC_APM_CENTRAL_CONFIG

CENTRAL_CONFIG

True

When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.

See Dynamic configuration for more information.

This feature requires APM Server and Kibana >= 7.3.

global_labels

edit
Environment Django/Flask Default

ELASTIC_APM_GLOBAL_LABELS

GLOBAL_LABELS

None

Labels added to all events, with the format key=value[,key=value[,...]]. Any labels set by application via the API will override global labels with the same keys.

This feature requires APM Server >= 7.2.

disable_log_record_factory

edit
Environment Django/Flask Default

ELASTIC_APM_DISABLE_LOG_RECORD_FACTORY

DISABLE_LOG_RECORD_FACTORY

False

By default in python 3, the agent will install a LogRecord factory that automatically adds tracing fields to your log records. You can disable this behavior by setting this to True.

use_elastic_traceparent_header

edit
Environment Django/Flask Default

ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER

USE_ELASTIC_TRACEPARENT_HEADER

True

To enable distributed tracing, the agent sets a number of HTTP headers to outgoing requests made with instrumented HTTP libraries. These headers (traceparent and tracestate) are defined in the W3C Trace Context specification.

Additionally, when this setting is set to True, the agent will set elasticapm-traceparent for backwards compatibility.

Django-specific configuration

edit

django_transaction_name_from_route

edit
Environment Django Default

ELASTIC_APM_DJANGO_TRANSACTION_NAME_FROM_ROUTE

DJANGO_TRANSACTION_NAME_FROM_ROUTE

False

By default, we use the function or class name of the view as the transaction name. Starting with Django 2.2, Django makes the route (e.g. users/<int:user_id>/) available on the request.resolver_match object. If you want to use the route instead of the view name as the transaction name, you can set this config option to true.

in versions previous to Django 2.2, changing this setting will have no effect.

django_autoinsert_middleware

edit
Environment Django Default

ELASTIC_APM_DJANGO_AUTOINSERT_MIDDLEWARE

DJANGO_AUTOINSERT_MIDDLEWARE

True

To trace Django requests, the agent uses a middleware, elasticapm.contrib.django.middleware.TracingMiddleware. By default, this middleware is inserted automatically as the first item in settings.MIDDLEWARES. To disable the automatic insertion of the middleware, change this setting to False.

Generic Environment variables

edit

Some environment variables that are not specific to the APM agent can be used to configure the agent.

HTTP_PROXY and HTTPS_PROXY

edit

Using HTTP_PROXY and HTTPS_PROXY, the agent can be instructed to use a proxy to connect to the APM Server. If both are set, HTTPS_PROXY takes precedence.

The environment variables are case-insensitive.

NO_PROXY

edit

To instruct the agent to not use a proxy, you can use the NO_PROXY environment variable. You can either set it to a comma-separated list of hosts for which no proxy should be used (e.g. localhost,example.com) or use * to match any host.

This is useful if HTTP_PROXY / HTTPS_PROXY is set for other reasons than agent / APM Server communication.

Configuration formats

edit

Some options require a unit, either duration or size. These need to be provided in a specific format.

Duration format

edit

The duration format is used for options like timeouts. The unit is provided as suffix directly after the number, without and separation by whitespace.

Example: 5ms

Supported units

  • ms (milliseconds)
  • s (seconds)
  • m (minutes)

Size format

edit

The size format is used for options like maximum buffer sizes. The unit is provided as suffix directly after the number, without and separation by whitespace.

Example: 10kb

Supported units:

  • b (bytes)
  • kb (kilobytes)
  • mb (megabytes)
  • gb (gigabytes)

we use the power-of-two sizing convention, e.g. 1 kilobyte == 1024 bytes

« Supported Technologies Advanced Topics »