Install & Compatibility
Where this runs
tested against v6.26.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.311s · 22.3MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.6s · import 0.296s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from elasticapm import Client
For general-purpose APM client initialization outside of framework integrations.
ElasticAPM
✓ from elasticapm.contrib.flask import ElasticAPM
For integrating with Flask applications. Similar imports exist for other frameworks like Django.
capture_span
✓ from elasticapm import capture_span
Decorator for manually creating spans around functions.
This Flask example demonstrates basic setup with environment variable configuration, capturing a custom message, and an exception. It also shows how to ignore specific routes from tracing using `TRANSACTIONS_IGNORE_PATTERNS`. Ensure an Elastic APM Server is running and accessible at the configured `SERVER_URL`.
import os
from flask import Flask
from elasticapm.contrib.flask import ElasticAPM
app = Flask(__name__)
app.config['ELASTIC_APM'] = {
'SERVICE_NAME': os.environ.get('ELASTIC_APM_SERVICE_NAME', 'my-flask-app'),
'SERVER_URL': os.environ.get('ELASTIC_APM_SERVER_URL', 'http://localhost:8200'),
'ENVIRONMENT': os.environ.get('ELASTIC_APM_ENVIRONMENT', 'development'),
'CAPTURE_HEADERS': True,
'TRANSACTIONS_IGNORE_PATTERNS': ['^/healthcheck']
}
apm = ElasticAPM(app)
@app.route('/')
def hello_world():
apm.client.capture_message('Hello World request received!')
try:
1 / 0
except ZeroDivisionError:
apm.client.capture_exception()
return 'Hello, World!'
@app.route('/healthcheck')
def healthcheck():
return 'OK'
if __name__ == '__main__':
# Set environment variables or ensure APM server is running at localhost:8200
# For example: ELASTIC_APM_SERVICE_NAME=my-service ELASTIC_APM_SERVER_URL=http://localhost:8200 python your_app.py
app.run(debug=True)
elastic-apm --version
Debug
Known issues
breakingPython 3.6 support will be removed in version 7.0.0 of the agent. Projects using Python 3.6 must upgrade to Python 3.7+ before upgrading to agent version 7.0.0 or later.fixUpgrade your Python environment to 3.7 or higher.
affects: >=6.23.0 (upcoming v7.0.0)
deprecatedThe log shipping `LoggingHandler` will be removed in version 7.0.0. Consider using built-in log shipping via `logging=LEVEL` in the `ElasticAPM` constructor or filebeat for less urgent logs.fixMigrate to using the `logging` parameter in the `ElasticAPM` constructor (e.g., `ElasticAPM(app, logging='WARNING')`) or use an external log shipper like Filebeat.
affects: >=6.23.0 (upcoming v7.0.0)
gotchaWhen integrating with Flask and uWSGI, ensure that threads are explicitly enabled in your uWSGI configuration, as the APM agent relies on background threads for metrics collection and other operations.fixAdd `--enable-threads` or `threads = <num_threads>` to your uWSGI configuration.
affects: All versions
gotchaCompatibility with APM Server versions is crucial. For APM Server 6.2 and higher, ensure you are using `elastic-apm` agent version 2.0 or higher.fixUpgrade your `elastic-apm` agent to version 2.0 or higher if using APM Server 6.2+.
affects: <2.0 (agent) with >=6.2 (server)
gotchaIn `v6.25.0`, a change in Tornado 6.5.3's `HttpHeaders` `in` operator behavior was handled. If using Tornado and upgrading it, ensure you are on `elastic-apm` v6.25.0+ to avoid potential issues.fixUpgrade `elastic-apm` to version 6.25.0 or later if using Tornado 6.5.3.
affects: Tornado 6.5.3 with elastic-apm <6.25.0
gotchaWhen running in FIPS mode (Federal Information Processing Standard), server certificate verification becomes mandatory for secure communication with the APM Server.fixEnsure your APM Server has a valid, verifiable TLS certificate, or configure `ELASTIC_APM_SERVER_CA_CERT` if using a custom CA.
affects: >=6.24.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'elasticapm'
The 'elastic-apm' package is not installed or not properly installed in the Python environment.
fixInstall the package using pip: 'pip install elastic-apm'.
ValueError: APM Server responded with an error: 'i/o timeout'
The APM agent is experiencing I/O timeouts when communicating with the APM Server, possibly due to misconfigured timeout settings.
fixEnsure that timeout settings are incrementally configured from the APM agent through any load balancer to the APM Server, e.g., agent: 10s, load balancer: 15s, server: 3600s.
AttributeError: module 'elasticapm' has no attribute 'capture_exception'
The 'capture_exception' function is not available in the 'elasticapm' module, possibly due to an outdated version of the package.
fixUpdate the 'elastic-apm' package to the latest version using pip: 'pip install --upgrade elastic-apm'.
HTTP 400: Data decoding error
The APM agent and APM Server versions are incompatible, leading to data decoding errors.
fixVerify and ensure compatibility between the APM agent and APM Server versions by consulting the compatibility matrix.
HTTP 400: Event too large
The APM agent is sending events that exceed the maximum allowed size configured in the APM Server.
fixIncrease the 'max_event_size' setting in the APM Server configuration to accommodate larger events.
Upgrade
Version history
6.26.2latest on PyPI · released Jun 22, 2026
Audit
Dependencies
PythonrequiredRequired runtime environment.