register_application

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

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 New Relic-monitored application and is used by some Python agent API calls.

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 is safe to create background threads when the WSGI application is loaded.

If you are 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

Parameter Description

name

string

Optional. The application name. If set, this overrides the application name set in the Python agent's configuration.

timeout

int or float

Optional but highly recommended. The number of seconds that the app will try to register before giving up and sending a response. A value of 0 means that the application will not wait for registration before it serves requests. The default is 0.

This value gives the maximum number of seconds the caller should be blocked before control is returned and the caller allowed to proceed. With no value, the call uses the globally configured startup_timeout setting in the agent configuration, which is 0.0 by default.

Return value(s)

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

Example(s)

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()

For more help

Recommendations for learning more: