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
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
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 is safe to create background threads when the WSGI application is loaded.
Call after worker process fork
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.
|Optional. The application name. If set, this overrides the application name set in the Python agent's configuration.|
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
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
Returns an application object that can be used by some other Python agent API calls.
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()