Python Custom Code Instrumentation with Atatus

The Atatus Python APM agent makes it easy to monitor and troubleshoot custom Python applications.
By manually instrumenting your code, you can:

Track performance metrics for your scripts and background tasks
Create and manage transactions for key workflows
Enable distributed tracing across services
Capture custom spans for fine-grained visibility

Creating New Transactions

atatus.capture_span works only when there’s an active transaction.
If your application is not running inside a supported framework (like Django or Flask), you’ll need to:

Create a Client instance
Begin and end transactions manually

You can still leverage automatic instrumentation for supported libraries by calling atatus.instrument(). A transaction can represent any logical operation like the entire script execution or a specific code block.

Example:

import requests
import time
import atatus

# Initialize the Atatus client
client = atatus.Client({
  'APP_NAME': "<YOUR_APP_NAME>",
  'LICENSE_KEY': "<LICENSE_KEY>",
  'NOTIFY_HOST': "YOUR_ON_PREMISE_URL",
  'ANALYTICS_NOTIFY_HOST': "YOUR_ON_PREMISE_URL",
})
# Enable automatic instrumentation (call only once at startup)
atatus.instrument()

def main():
    # Start a transaction
    client.begin_transaction(name="main",transaction_type="script")
    sess = requests.Session()
    for url in ['https://www.atatus.com', 'https://apm.atatus.com']:
        resp = sess.get(url)
        time.sleep(1) # Simulate processing time
    # End the transaction    
    client.end_transaction(name="main", result="success")

if __name__ == '__main__':
    main()

Call atatus.instrument() only once, as early as possible.
Treat the Client object as a singleton, so create one instance and reuse it.

Distributed Tracing

When instrumenting custom Python code across multiple services, ensure the TraceParent is propagated so Atatus can link transactions into a single distributed trace. It also provides utilities to work with TraceParent in string or header dictionary formats for manual propagation.

Example:

import atatus

# Init Atatus client with tracing
client = atatus.Client({
    'APP_NAME': "<YOUR_APP_NAME>",
    'LICENSE_KEY': "<LICENSE_KEY>",
    'TRACING': True
})

# --- Example 1: TraceParent as string ---
# Get current TraceParent
traceparent_string = atatus.get_trace_parent_header()

# Start a new transaction using the TraceParent string
parent = atatus.trace_parent_from_string(traceparent_string)
client.begin_transaction(transaction_type="script", trace_parent=parent)
# Perform work here
client.end_transaction(name=__name__, result="success")


# --- Example 2: TraceParent from headers ---
# Create a TraceParent from a headers dictionary
parent = atatus.trace_parent_from_headers(headers_dict)
client.begin_transaction(transaction_type="script", trace_parent=parent)
# Perform work here
client.end_transaction(name=__name__, result="success")

Creating Additional Spans in a Transaction

While Atatus automatically instruments many libraries, you may want to measure the execution time or frequency of specific functions. For this, use the @atatus.capture_span() decorator or @atatus.async_capture_span() for async code.

capture_span requires an active transaction. If you’re not using a supported framework, create a Client and manually manage transactions. See Creating New Transactions for details.

Synchronous Example

import atatus

@atatus.capture_span()
def coffee_maker(strength):
    fetch_water()

    with atatus.capture_span('near-to-machine'):
        insert_filter()
        for i in range(strength):
            pour_coffee()
        start_drip()

    fresh_pots()

Asynchronous Example

import atatus

@atatus.async_capture_span()
async def coffee_maker(strength):
    await fetch_water()

    async with atatus.async_capture_span('near-to-machine'):
        await insert_filter()
        async for i in range(strength):
            await pour_coffee()
        start_drip()

    fresh_pots()

Async span instrumentation requires Python 3.7+.

​Creating New Transactions

​Example:

​Distributed Tracing

​Example:

​Creating Additional Spans in a Transaction

​Synchronous Example

​Asynchronous Example

Creating New Transactions

Example:

Distributed Tracing

Example:

Creating Additional Spans in a Transaction

Synchronous Example

Asynchronous Example