Python management API

The Python agent management API provides calls to manage the configuration, initialization, and shutdown of the agent. Use these API calls to manually integrate the agent into your Python application.

The API call format is newrelic.agent. followed by the API name and values. For example: newrelic.agent.global_settings(). For ease of use, the headings below use only the last part of the API name and not the complete call format.

Management API calls

The management API includes the following calls:

newrelic.agent.global_settings()

This call returns a reference to the global agent settings object.

If accessed before the agent is initialized, the global settings will have the default configuration settings, along with any overrides from user environment variables. If accessed after agent initialization, the global settings contain any agent config file settings that are also global settings. The config file contains fewer settings than does the global settings object.

The returned settings are nested, hierarchical objects. The setting names match the settings in the agent configuration file.

Here are some examples of assigning the proxy_host, proxy_port, slow_sql.enabled, and browser_monitoring.auto_instrument settings:

settings = newrelic.agent.global_settings()

settings.proxy_host = 'proxy.intranet' 
settings.proxy_port = 8888
settings.slow_sql.enabled = False
settings.browser_monitoring.auto_instrument = False

If you are debugging or logging and require the global settings as a traditional Python dictionary object, you can pass the result into a dict. For example:

settings_dict = dict(newrelic.agent.global_settings())

for name, value in settings_dict.items():
     print name, value

Each name will be the full dotted path for that setting.

If you update global settings using the global settings object, the changes will only take affect the next time the agent is being registered with the data collector for a specific application.

newrelic.agent.initialize(config_file=None, environment=None)

This is called to initialize the agent with a specified configuration file when the agent is being manually integrated into a Python application.

newrelic.agent.initialize('/etc/newrelic/newrelic.ini', 'production')

For best instrumentation results, the call to initialize the agent should be done as early as possible. For WSGI and application script files, place the initialize() call before all imports, with the exception of the sys import and updates to the sys.path.

When a configuration file is being used, the environment option specifies any environment-specific overrides in the agent configuration that will be merged on top of the config file settings.

If the initialize() function is called multiple times, subsequent calls will be ignored, provided that the configuration file and environment options are the same. If the options differ, an exception is raised.

If you call the initialize() function with no arguments, the license key (at the very least) must have already been specified by setting the NEW_RELIC_LICENSE_KEY environment variable. Alternatively, the NEW_RELIC_CONFIG_FILE and NEW_RELIC_ENVIRONMENT variables can be set. The values of those are used in place of the missing arguments.

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

When initialize() is called, it sets up the agent, but will not register the agent with the data collector. That registration would normally be done lazily when the first web request or background task occurs for the application.

Because registration is done lazily and registration takes a second or so, details of the first transactions are not recorded. Recording of transactions only occurs once registration is acknowledged and any server-side configuration is received from the data collector.

If it is necessary to force early registration and potentially wait for the registration to complete before serving any web requests or running a background task, it is necessary to call register_application().

If the script itself runs the WSGI server, perform the register_application() call from the main program thread in the main script file. If using Apache/mod_wsgi or uWSGI, make the call from the WSGI script file. Place this call after the initialize() call.

When called with None for the application name, the call uses the default application name specified in the agent configuration file or via the NEW_RELIC_APP_NAME environment variable.

If a timeout value is specified, it gives the maximum number of seconds the caller should be blocked before control is returned and the caller allowed to proceed. When the timeout is set to None, the call relies on the globally configured startup_timeout setting in the agent configuration, which is set to 0.0 by default.

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, with the deadlock only being broken when the timeout expires.

Do not call register_application() in a parent process before the forking of child worker processes where the actual recording of transactions is to be carried out. This causes the background agent thread created by this call, which periodically reports data to our data collector, to be killed off when the process is forked. This causes data to not be reported in the child worker process.

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

The deadlock problem above occurs 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: it has been designed not to do this, so it is safe to create background threads when the WSGI application is loaded.

Calling register_application() results in an application object that corresponds to the application for which registration was triggered. The application object itself does not present any public API, but may be passed in certain circumstances to other API calls when implementing custom instrumentation.

newrelic.agent.application(name=None)

This call returns an application object corresponding to the specified name.

If called with the name set to None, the call uses the default application name specified in the agent configuration file or via the NEW_RELIC_APP_NAME environment variable.

The application object itself does not present any public API, but may be passed in certain circumstances to other API calls when implementing custom instrumentation.

This only returns the application object and will not attempt to register the application with the data collector if this has not already occurred.
newrelic.agent.application_settings(name=None)

This call returns a reference to the application settings object.

If called with the name set to None, the call uses the default application name specified in the agent configuration file or via the NEW_RELIC_APP_NAME environment variable.

If the application hasn't been registered with the data collector when this call is made, it returns the value None. When a call is successfully made and returns values, it will reflect the values of any local configuration overlaid with the server-side configuration for that application obtained during registration.

The returned settings are nested, hierarchical objects and the setting names match the setting names in the agent configuration file. Here is an example of a Python if statement that uses an application setting:

settings = newrelic.agent.application_settings()

if settings and settings.error_collector.enabled:
    ...

The main reason to expose the application settings is to allow any custom user instrumentation to consult application specific configuration.

Do not make any changes to the application settings object. Do not cache the settings object because it will be invalidated and replaced if a server side configuration change causes the agent to reregister the application with the data collector.

If you are debugging or logging and require the global settings as a traditional Python dictionary object, you can pass the result into a dict. For example:

settings_dict = dict(newrelic.agent.application_settings())

for name, value in settings_dict.items():
    print name, value

Each name will be the full dotted path for that setting.

newrelic.agent.shutdown_agent(timeout=None)
	

During a normal process shutdown, the agent is shut down and a last attempt is made to upload any data to the data collector. If you need to forcibly shut down the agent, use the shutdown_agent() call.

The timeout value is the maximum length of time the caller will wait for any final reporting of data to complete. If a timeout does occur, the reporting of data still continues in the background, but that may be interrupted if the caller forcibly kills the whole process.

Here is an example of the timeout value set to 3 seconds:

newrelic.agent.shutdown_agent(timeout=3)
	

If timeout is set as None, the default global value is used. If a timeout value is set as an override in the configuration settings, that value will be used. If no value is set, the default timeout value is 2.5 seconds.

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.