• English日本語한국어
  • Log inStart now

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

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

The number of seconds that the app will try to register before giving up and sending a response; meaning this line will block until New Relic starts up or the timeout is exceeded. A value of 0 means that the application will not wait for registration before it serves requests. The default is 0. If running a web application, setting this value isn't recommended as it'll block and delay the application while New Relic starts up. If instrumenting a single program run or task, where the process runs once and immediately terminates, setting this is recommended as otherwise New Relic will not be started in time to capture the information.

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 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()
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.