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.
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.
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.