Elastic APM Python Agent

6.25.0 · active · verified Sat Apr 11

The official Python module for Elastic APM. It provides full out-of-the-box support for many popular frameworks, including Django and Flask, and can be adapted for most WSGI-compatible web applications or used in any standalone Python application. It monitors applications in real-time, collecting performance metrics, tracing transactions, and capturing errors. Currently at version 6.25.0, it sees regular updates focusing on framework compatibility and performance.

Warnings

breaking Python 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.
Fix: Upgrade your Python environment to 3.7 or higher.
deprecated The 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.
Fix: Migrate to using the `logging` parameter in the `ElasticAPM` constructor (e.g., `ElasticAPM(app, logging='WARNING')`) or use an external log shipper like Filebeat.
gotcha When 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.
Fix: Add `--enable-threads` or `threads = <num_threads>` to your uWSGI configuration.
gotcha Compatibility 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.
Fix: Upgrade your `elastic-apm` agent to version 2.0 or higher if using APM Server 6.2+.
gotcha In `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.
Fix: Upgrade `elastic-apm` to version 6.25.0 or later if using Tornado 6.5.3.
gotcha When running in FIPS mode (Federal Information Processing Standard), server certificate verification becomes mandatory for secure communication with the APM Server.
Fix: Ensure your APM Server has a valid, verifiable TLS certificate, or configure `ELASTIC_APM_SERVER_CA_CERT` if using a custom CA.

Install

pip install elastic-apm Install core package
pip install elastic-apm[flask] Install with Flask support
pip install elastic-apm[django] Install with Django support

Imports

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.

Quickstart

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)

view raw JSON →