background_task (Python agent API)

Syntax

newrelic.agent.background_task(application=None, name=None, group=None)

Used to instrument a background task or other non-web transaction of finite run time.

Description

This Python decorator can be used to instrument background tasks or other non-web transactions of finite run time. This is typically used to instrument non-web activity like worker processes, job-based systems, and standalone scripts. Transactions marked as background tasks are displayed as non-web transactions in the APM UI and separated from web transactions.

If a function using the background task decorator is called within the context of a web transaction, then the web transaction is marked as a background task. The measurement of the time taken begins when the original web transaction starts.

If you cannot use the decorator, one of these call formats may be more useful:

• The context manager: If the tasks to be monitored will only be determined at runtime (and not import time), you can use the BackgroundTask context manager to directly wrap the execution of a block of code. (This is the context manager used by BackgroundTaskWrapper.)
• The wrapper: If you know in advance where the specific functions you want to track are, you can use the background_task decorator. But if you don't know all the functions that need to be traced (for example, if they're being looked up dynamically as part of a routing system), then you must use the BackgroundTaskWrapper to wrap the function at the time of registration or at the time of calling.
• The path-based wrapper: The path-based wrapper form is wrap_background_task.

For more on the differences between and uses of these function forms, see Variable call formats.

Parameters

Decorator and context manager parameters

newrelic.agent.background_task(application=None, name=None, group=None)

newrelic.agent.BackgroundTask(application=None, name=None, group=None)

Parameters for these calls:

Wrapper parameters:

newrelic.agent.BackgroundTaskWrapper(wrapped, application=None, name=None, group=None)

BackgroundTaskWrapper takes the same parameters as the background_task decorator and this additional wrapped parameter:

Path-based parameters:

newrelic.agent.wrap_background_task(module, object_path, application=None, name=None, group=None)

wrap_background_task takes the same parameters as the background_task decorator plus these additional parameters:

Examples

background_task decorator example

Here's an example of using the background_task decorator:

@newrelic.agent.background_task()
def task():
    ...

BackgroundTask context manager example

An example of using BackgroundTask:

application = newrelic.agent.application()
name = newrelic.agent.callable_name(task)

with BackgroundTask(application, name):
    task()

Here's another example with more parameters:

application = newrelic.agent.register_application(timeout=10.0)

def execute_task(task_name):
    with newrelic.agent.BackgroundTask(application, name=task_name, group='Task'):
        ...

BackgroundTaskWrapper example

An example of using the BackgroundTaskWrapper:

task = newrelic.agent.BackgroundTaskWrapper(get_next_task())
result = task(*args, **kwargs)

In this example, if this call was made in a web transaction being monitored by an agent, the call will reclassify the web transaction as a background task. If, however, the call was made in a background thread or coroutine, then it would start the recording of a fresh background task transaction that tracks what occurs until the call returns.

Troubleshooting

If the background task's transaction is not showing up in the UI, this could be because the transaction that was created by the background task was never exited or the task ran too long. If a background task runs for over 20 minutes, it is dropped by the server because it was considered too old to keep. Background tasks should not run for over 20 minutes and if they do they should be broken up into multiple background tasks.