Elastic APM instruments a variety of libraries out of the box, but sometimes you need to know how long a specific function took or how often it gets called.

Assuming you’re using one of oursupported frameworks, you can apply the@elasticapm.capture_span() decorator to achieve exactly that. If you’re not using a supported framework, seeCreating New Transactions.

elasticapm.capture_span can be used either as a decorator or as a context manager. The following example uses it both ways:

import elasticapm@elasticapm.capture_span()def coffee_maker(strength):    fetch_water()    with elasticapm.capture_span('near-to-machine'):        insert_filter()        for i in range(strength):            pour_coffee()        start_drip()    fresh_pots()

Similarly, you can useelasticapm.async_capture_span for instrumentingasync workloads:

import elasticapm@elasticapm.async_capture_span()async def coffee_maker(strength):    await fetch_water()    async with elasticapm.async_capture_span('near-to-machine'):        await insert_filter()        async for i in range(strength):            await pour_coffee()        start_drip()    fresh_pots()

Seethe API docs for more information oncapture_span.

It’s important to note thatelasticapm.capture_span only works if there is an existing transaction. If you’re not using one of oursupported frameworks, you need to create aClient object and begin and end the transactions yourself. You can even utilize the agent’sautomatic instrumentation!

To collect the spans generated by the supported libraries, you need to invokeelasticapm.instrument() (just once, at the initialization 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. The config forelasticapm.Client can be passed in programmatically, and it will also utilize any config environment variables available to it automatically.

import requestsimport timeimport elasticapmdef 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(service_name="foo", server_url="https://example.com:8200")    elasticapm.instrument()    client.begin_transaction(transaction_type="script")    main()    client.end_transaction(name=__name__, result="success")

1. Only call this once, as early as possible.

Note that you don’t need to do anything to send the data—theClient object will handle that before the script exits. Additionally, theClient object should be treated as a singleton—you should only create one instance and store/pass around that instance for all transaction handling.

When instrumenting custom code across multiple services, you should propagate the TraceParent where possible. This allows Elastic APM to bundle the various transactions into a single distributed trace. The Python Agent will automatically add TraceParent information to the headers of outgoing HTTP requests, which can then be used on the receiving end to add that TraceParent information to new manually-created transactions.

Additionally, the Python Agent provides utilities for propagating the TraceParent in string format.

import elasticapmclient = elasticapm.Client(service_name="foo", server_url="https://example.com:8200")# Retrieve the current TraceParent as a string, requires active transactiontraceparent_string = elasticapm.get_trace_parent_header()# Create a TraceParent object from a string and use it for a new transactionparent = elasticapm.trace_parent_from_string(traceparent_string)client.begin_transaction(transaction_type="script", trace_parent=parent)# Do some workclient.end_transaction(name=__name__, result="success")# Create a TraceParent object from a dictionary of headers, provided# automatically by the sending service if it is using an Elastic APM Agent.parent = elasticapm.trace_parent_from_headers(headers_dict)client.begin_transaction(transaction_type="script", trace_parent=parent)# Do some workclient.end_transaction(name=__name__, result="success")