background_task

For general information on how the Python agent API calls relate to each other, see the API guide.

newrelic.agent.background_task(application=None, name=None, group=None)
Used to instrument a background task or other non-web transaction.

Description

This Python decorator can be used to instrument background tasks or other non-web transactions. 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:

Parameter Description

application

Application instance

Required. The application under which the data will be reported to New Relic. Default is None. If left without a value, the application specified in the agent configuration (config file or environment variable) will be used.

For more on generating an application object, see the application() method.

The application, even if specified, can still be overridden if newrelic.app_name is defined in the WSGI application per request environ dictionary.

name

string

Required. The name of the transaction. The default value is None. By default, the name will be the name of the function the decorator has been applied to but you can override this by supplying this name.

group

string

Optional. The group represents the naming structure for the name parameter. This is used in the UI to set the transaction type.

If not supplied, the group defaults to Function in expectation that the name is of the form module:class.function or module:function and represents the name of the function being executed. If you are creating a custom group, New Relic recommends you prefix it with Python/.

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:

Parameter Description

wrapped

method

Required. The method to be traced.

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:

Parameter Description

module

module or string

Required. The module containing the non-web function/activity you are instrumenting.

object_path

string

Required. The path to the module.

Example(s)

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 New Relic, 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.

For more help

Recommendations for learning more: