Configuration
editConfiguration
editTo 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:
- environment variables
- inline configuration
- framework specific configuration
- default value
Django
editTo configure Django, add an ELASTIC_APM
dictionary to your settings.py
:
ELASTIC_APM = { 'SERVICE_NAME': 'my-app', 'SECRET_TOKEN': 'changeme', }
Flask
editTo 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
editservice_name
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
|
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
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
|
The URL for your APM Server.
The URL must be fully qualified, including protocol (http
or https
) and port.
transport_class
editEnvironment |
Django/Flask |
Default |
|
|
|
The transport class to use when sending events to the APM server.
The default AsyncTransport
uses a background thread to send data.
If your environment doesn’t allow background threads, you can use
elasticapm.transport.http.Transport
instead.
Note however that this can have adverse effects on performance.
Other options
editenvironment
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
|
The name of the environment this service is deployed in, e.g. "production" or "staging".
environment
is currently not supported in the Kibana APM UI.
This means that data from different environments that share the same
<<config-service-name,service name>>
will be shown together in the APM UI.
For the time being, we recommend to also append the environment name to the service name.
secret_token
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
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.
service_version
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
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
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
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
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
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
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
|
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
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
|
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
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
|
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
editEnvironment | Django/Flask | Default | Example |
---|---|---|---|
|
|
|
|
The host name to use when sending error and transaction data to the APM server.
auto_log_stacks
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
|
set to |
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
With this setting, you can limit the length of lists in local variables.
source_lines_error_app_frames
editsource_lines_error_library_frames
editsource_lines_span_app_frames
editsource_lines_span_library_frames
editEnvironment |
Django/Flask |
Default |
|
|
|
|
|
|
|
|
|
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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.
span_frames_min_duration
editEnvironment |
Django/Flask |
Default |
|
|
|
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. 5
, will limit stack trace collection to spans
with durations equal or longer than the given value in milliseconds, e.g. 5 milliseconds.
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
A list of processors to process transactions and errors. For more information, see Sanitizing Data.
We recommend to always include the default set of validators if you customize this setting.
transaction_sample_rate
editEnvironment |
Django/Flask |
Default |
|
|
|
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, tags, or spans.
include_paths
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
If set to True
, the agent won’t send any events to the APM server, independent of any debug state.
instrument
editEnvironment |
Django/Flask |
Default |
|
|
|
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
editEnvironment |
Django/Flask |
Default |
|
|
|
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+.
ELASTIC_APM_SERVER_CERT
editEnvironment | Django/Flask | Default |
---|---|---|
|
|
|
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.
Django-specific configuration
editdjango_transaction_name_from_route
editEnvironment |
Django |
Default |
|
|
|
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.
Configuration formats
editSome options require a unit, either duration or size. These need to be provided in a specific format.
Duration format
editThe 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
editThe 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