Python custom instrumentation via API

The Python agent instrumentation API provides you with the components needed to integrate the agent with your WSGI application and enhance any instrumentation provided for specific frameworks to gather additional information.

The API call format is newrelic.agent. followed by the API name and values; for example, newrelic.agent.wsgi_application(). For your convenience, the headings below show the API name, followed by the complete API call format and additional details.

wsgi_application

newrelic.agent.wsgi_application(application=None)

Python decorator for marking the WSGI application entry point for monitoring of web transactions.

@newrelic.agent.wsgi_application()
def application(environ, start_response):
    status = '200 OK'
    output = 'Hello World!'

    response_headers = [('Content-type', 'text/plain'),
                        ('Content-Length', str(len(output)))]
    start_response(status, response_headers)

    return [output]

Data will be reported against the application specified, or if the application is left as the default None value, the application specified in the agent configuration file or via the NEW_RELIC_APP_NAME environment variable will be used.

The application if specified can be either an application object or a string giving the name of the application. If a string is provided, it must be the exact application name and cannot be a list of application names.

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

WSGIApplicationWrapper

newrelic.agent.WSGIApplicationWrapper(wrapped, application=None)

The underlying wrapper object used in the implementation of thenewrelic.agent.wsgi_application() decorator. The wrapper may be used directly where a decorator cannot be readily applied to an existing API.

import os
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

application = newrelic.agent.WSGIApplicationWrapper(application)

Using the wrapper in more than one place in code on distinct WSGI application components which may be stacked is okay. In that case, the first encountered will mark the start of the monitoring of the transaction and the target application will be derived from that as well with that in subsequent ones encountered being ignored.

Note: A WSGI application only generally needs to be wrapped where no framework specific instrumentation is provided for the web framework being used, and the WSGI server being used also isn't being instrumented such that any WSGI application is automatically wrapped. The main WSGI server where the WSGI application is not automatically wrapped is Apache/mod_wsgi.

background_task

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

Python decorator for marking a function which should be monitored as a background task.

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

Data will be reported against the application specified, or if the application is left as the default None value, the application specified in the agent configuration file or via the NEW_RELIC_APP_NAME environment variable will be used.

The application if specified can be either an application object or a string giving the name of the application. If a string is provided, it must be the exact application name and cannot be a list of application names.

If a function using the background task decorator is called within the context of a monitored web transaction, then the web transaction will be marked as a background task. Monitoring of the time taken will still be measured from the point where the original web transaction was started.

By default the name of the background task will be the name of the function the decorator has been applied to but can be overridden by supplying the name when decorating the function.

The group can be used to categorize what the name represents. If not supplied, the group will default 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.

BackgroundTaskWrapper

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

The underlying wrapper object used in the implementation of the newrelic.agent.background_task() decorator. The wrapper may be used directly where a decorator cannot be readily applied to an existing API.

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

BackgroundTaskManager (context manager)

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

A context manager which can be used to directly wrap the execution of a block of code such that it can be monitored as a background task.

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

with BackgroundTask(application, name):
    task()

When using the context manager, the application and name fields are mandatory. The application must be an application object and cannot be a string name of the application.

callable_name

newrelic.agent.callable_name(object, separator=':')

Returns a string name identifying the supplied object. This will be of the form module:object_path.

If object were a function, then the name would be module:function. If a class, module:class. If a member function, module:class.function.

By default the separator between the module path and the object path is : but can be overridden if necessary. The convention used by the Python Agent is : so that it is clearer which part is the module name and which is the name of the object.

For more help

Additional documentation resources include:

Join the discussion about Python in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.