Syntax
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.
Important
If a function isn't already instrumented, you can use function_trace() to create a function trace for that function within a background task. Or you can use the config file to instrument uninstrumented functions.
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
BackgroundTaskcontext manager to directly wrap the execution of a block of code. (This is the context manager used byBackgroundTaskWrapper.) - The wrapper: If you know in advance where the specific functions you want to track are, you can use the
background_taskdecorator. 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 theBackgroundTaskWrapperto 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 instance | Required. The application under which the data will be reported. Default is For more on generating an application object, see the The application, even if specified, can still be overridden if |
string | Required. The name of the transaction. The default value is |
string | Optional. The If not supplied, the group defaults to |
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 |
|---|---|
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 or string | Required. The module containing the non-web function/activity you are instrumenting. |
string | Required. The path to the module. |
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.