register_application (Python agent API)

Syntax

newrelic.agent.register_application(name=None, timeout=None)

Registers the Python agent immediately. Used for manual initialization of agent.

Description

When initialize is called, it sets up the Python agent but does not register the agent with the collector. This call registers the agent with the collector.

This is primarily used for non-web background transactions instrumented using the API. When used with non-web transactions, call register_application as soon as possible after the initialize call.

For web transactions, the agent normally registers automatically when the first web request or background task occurs the agent receives its server-side configuration from the collector. Because registration can take a second or so, details are usually lost from the earliest transactions. You can collect all of this data by forcing registration with register_application, though doing so means your app may wait for registration to complete before serving any web requests or running background tasks.

If the script itself runs the WSGI server, call register_application from the main program thread in the main script file. If you use Apache/mod_wsgi or uWSGI, make the call from the WSGI script file and place the call immediately after initialize.

This call returns the application object, in the same way application does. The application object is used to get a reference to the current agent-monitored application and is used by some Python agent API calls.

Avoid calling during global import lock

Do not call register_application with a non-zero timeout when the Python global import lock will be held. In other words, do not call it in a module file at global scope while the module is being imported. Doing so may result in a temporary deadlock with the background thread created by this call (the deadlock will not be broken until the timeout expires).

Note that many WSGI servers import the module containing the WSGI application via the standard Python module import mechanisms. In those cases, the global import lock will be held and the deadlock problem described above can occur.

For Gunicorn: The deadlock issue just described can also occur when using Gunicorn. The problem is that triggering register_application from the WSGI module is not safe, because it preloads the module into the parent process. To use register_application with Gunicorn (with or without a timeout) call it from a post_fork() callback. This is not a problem with Apache/mod_wsgi, since those tools have been designed not to do this, so it's safe to create background threads when the WSGI application is loaded.

Call after worker process fork

If you're recording transactions in child worker process, do not call register_application in the parent process before the child worker processes are forked. If you were to call register_application before forking, the background agent thread would be killed when the process is forked. Since the parent thread is reporting data to the collector, the agent will not be able to report data from child worker process.

Parameters

Return values

Returns an application object that can be used by some other Python agent API calls.

Examples

Registering a background task

This example registers a non-web background task with a long timeout. Typically, for a web application, you would have a very short time-out (the default is 0), but you might set a longer timeout for a infrequent non-web task to ensure initialization and registration take place.

import newrelic.agent

newrelic.agent.initialize('newrelic.ini')
newrelic.agent.register_application(timeout=10.0)

@newrelic.agent.background_task()
def main():
    pass

if __name__ == '__main__':
    main()