To gather APM events (called Transactions and Spans), errors and metrics, the Python agent instruments your application in a few different ways. These events, are then sent to the APM Server. The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application.
Broadly, we differentiate between three different approaches to collect the necessary data: framework integration, instrumentation, and background collection.
To collect data about incoming requests and background tasks, we integrate with frameworks like Django, Flask and Celery. Whenever possible, framework integrations make use of hooks and signals provided by the framework. Examples of this are
Framework integrations require some limited code changes in your app.
E.g. for Django, you need to add
What if you are not using a frameworkedit
If you’re not using a supported framework, for example, a simple Python script, you can still leverage the agent’s automatic instrumentation.
In order to collect the Spans generated by the supported libraries, you need to invoke
(just once, at the initalization stage of your application) and create at least one Transaction.
It is up to you to determine what you consider a Transaction within your application — it can be the whole execution of the
script or a part of it.
The example below will consider the whole execution as a single transaction with two HTTP request Spans in it.
elasticapm.Client can be setup programmatically or using the environment variables.
import requests import time import elasticapm def main(): sess = requests.Session() for url in [ 'https://www.elastic.co', 'https://benchmarks.elastic.co' ]: resp = sess.get(url) time.sleep(1) if __name__ == '__main__': client = elasticapm.Client() elasticapm.instrument() client.begin_transaction('main') main() client.end_transaction('main')
To collect data from database drivers, HTTP libraries etc., we instrument certain functions and methods in these libraries. Our instrumentation wraps these callables and collects additional data, like
- time spent in the call
- the executed query for database drivers
- the fetched URL for HTTP libraries
Instrumentations are set up automatically and do not require any code changes. See Automatic Instrumentation to learn more about which libraries we support.
In addition to APM and error data, the Python agent also collects system and application metrics in regular intervals. This collection happens in a background thread that is started by the agent.
In addition to the metrics collection background thread, the agent starts two additional threads per process:
- a thread to regularly fetch remote configuration from the APM Server
- a thread to process the collected data and send it to the APM Server via HTTP.
Note that every process that instantiates the agent will have these three threads. This means that when you e.g. use gunicorn or uwsgi workers, each worker will have three threads started by the Python agent.