Python agent admin script: Advanced usage

The Python agent admin script is used during the installation process. When the Python agent package is installed, the newrelic-admin script is also installed into the bin directory of the Python installation or virtual environment.

This document gives more in-depth detail about these uses of the admin script:

Generating the initial agent configuration file
Validating your config file
Testing the connection to New Relic
Wrapping startup of standalone Python web applications

Subcommand structure

To execute subcommands, provide the name of the subcommand as the first argument to the newrelic-admin script. Then add any options after the name of the subcommand. For example:

bash

$newrelic-admin help

help <command>

When executed with no further arguments, this provides a listing of all accepted subcommands:

bash

$newrelic-admin help
 Usage: newrelic-admin command [options]
 
 Type 'newrelic-admin help <command>'for help on a specific command.
 
 Available commands are:
   generate-config
   license-key
   local-config
   network-config
   record-deploy
   run-program
   run-python
   server-config
   validate-config

To view additional details about a subcommand, run the help command with the subcommand and any of its options. For example:

bash

$newrelic-admin help generate-config
 Usage: newrelic-admin generate-config license_key [output_file]
 
 Generates a sample agent configuration file for <license_key>.

generate-config license_key [output_file]

Generates a sample agent configuration file. The license_key option is your .

By default the sample configuration file will be directed to standard output and be displayed on your screen. To capture the output, you can instead save it to a file by giving the name of the file as the output_file option.

When the sample agent configuration file is generated, only the license key option in the file is updated. You should still edit the file and make changes to app_name and log_file options as appropriate. For more information, see Python agent installation.

If you cannot run the generate-config command to produce the initial agent configuration file, you can download a sample configuration file from download.newrelic.com/python_agent/release/newrelic.ini.

validate-config config_file [log_file]

Validates the syntax of an agent configuration file given by the config_file option.

This might be the agent configuration generated by generate-config and subsequently edited, or an agent configuration file created by downloading the sample configuration file from the download site.

As well as validating the syntax of the configuration file, using the license_key contained in the agent configuration file to identify your account, will also test whether a connection can be made to the our servers.

This subcommand can therefore be used to ensure that DNS is available for resolving the hostname of the our data collector host and that there is network connectivity available and that no firewall is blocking access.

In connecting to the our servers, the test will create an application under your account called Python Agent Test. Into this application a small amount of simulated web transaction data and errors will be reported. After a period of time this application in your account will be able to be deleted from the Applications list if desired.

When this test is run, a log file will be created in the location:

/tmp/python-agent-test.log

If you need to override this location you can supply the log_file option. To have what would be written to the log file be displayed to your screen, you can use stdout or stderr as the value passed as the log_file option.

When using a hosting service such as Heroku where an agent configuration file wouldn't normally be used, this subcommand can still be used to test the connection to us. For Heroku the license key information is defined in an environment variable automatically setup by Heroku when you add the New Relic addon to your Heroku instance.

In this case where an environment variable is used to define the license key, to run the connectivity test, pass the value - for the config_file option in place of the path to the agent configuration file. So, to run the command on your Heroku instance you would use:

bash

$heroku run newrelic-admin validate-config - stdout

Note that we have supplied stdout for the log file in this case, else it would be necessary to separately retrieve the log file generated.

It is recommended that when setting up the Python agent for the first time, or even perhaps on a new host, that this subcommand be used to test whether data can be reported okay. For more information, see Testing the Python agent.

run-program ...

Executes the command line for a Python web application given as ... but forces the initialization of the agent automatically at startup.

This is a shortcut method for starting up a Python web application without needing to manually make changes to the web application to add code to specifically initialize the Python agent. It can be used in any situation where a Python web framework or WSGI server is used where instrumentation is being automatically added to wrap the WSGI application entry point. In other words, in situations where only the agent initialization code needed to be added.

Agent configuration when using this method can be provided in two different ways. If using a complete agent configuration file then the location of that configuration can be provided by the NEW_RELIC_CONFIG_FILE environment variable.

If you were using gunicorn for example, you could say:

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn wsgi:application

bash

$NEW_RELIC_CONFIG_FILE=newrelic.ini
$export NEW_RELIC_CONFIG_FILE
$
$newrelic-admin run-program gunicorn wsgi:application

When specifying the location of the configuration file using the NEW_RELIC_CONFIG_FILE environment variable, the following additional environment variables can be set to customize how the configuration file is processed.

NEW_RELIC_ENVIRONMENT: The name of a specific deployment environment. When specified, additional override configuration will be read from a separate deployment section within the configuration file. The section of the configuration file for a specific deployment environment should be named as newrelic:environment where environment is replaced with the name being specified by this environment variable

In place of a complete agent configuration file, you can also set environment variables providing only the key agent configuration information. The environment variables which can be set in this case are:

NEW_RELIC_LICENSE_KEY - Your New Relic .
NEW_RELIC_APP_NAME - The name of the application you wish to report data against in the UI. If not defined, this defaults to Python Application.
NEW_RELIC_LOG - The path to a file to be used for the agent log. If not defined then no logging will occur. Can also be set to stdout or stderr to have logging go to standard output or standard error for process.
NEW_RELIC_LOG_LEVEL - The level at which logging will be output by the agent. If not defined then defaults to info. Possible values, in increasing order of detail, are: critical, error, warning, info and debug.

Individual environment variables are used when hosting your application on Heroku. The environment variables will be set automatically as appropriate by the Heroku environment when you add the New Relic addon. It is therefore not necessary when using Heroku to set any of the above environment variables when using the newrelic-admin command with this option from your Procfile.

Note that the wrapped program must be using the same Python installation or virtual environment as that which the Python agent package and the newrelic-admin script was installed into. If this is not the case then the wrapper script will have no affect and you may even encounter an error on startup of the Python interpreter due to the newrelic Python package not being able to be found.

If using sudo to startup your WSGI application as another user, be aware that the default sudo configuration will generally be such that user environment variables from the shell in which sudo is run will be ignored. In this case you would need to change the sudoers configuration to allow passing of the specific environment variables. Alternatively, create a shell script which sets the environment variables and runs your WSGI application under newrelic-admin. To start up your WSGI application as a different user, then run sudo on that script rather than directly on your WSGI application.

The use of an additional wrapper script to set the environment variables and run your WSGI application under newrelic-admin may also be required when using supervisord if any issues are encountered with environment variable settings within the supervisord configuration not being passed through correctly.

run-python ...

Executes the python executable from the Python installation or virtual environment that newrelic-admin is installed into with the arguments given as ... but forces the initialization of the agent automatically at startup.

As for run-program subcommand above, environment variables are used to configure the Python agent. If you were using python executable directly for example, you could say:

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-python wsgi.py

bash

$NEW_RELIC_CONFIG_FILE=newrelic.ini 
$export NEW_RELIC_CONFIG_FILE 
$
$newrelic-admin run-python wsgi.py

license-key config_file [log_file]

Outputs the license key which will be used. This can be used in any startup scripts prior to starting up of the actual WSGI application to log the license key for the purpose of verifying that the correct value is being used.

It may be used with the agent configuration file:

bash

$newrelic-admin license-key newrelic.ini

If setting the license key using environment variables, use - as the name of the configuration file:

bash

$NEW_RELIC_LICENSE_KEY='YOUR-LICENSE-KEY'
$export NEW_RELIC_LICENSE_KEY 
$
$newrelic-admin license-key -

Output will be in the form:

license_key = 'YOUR-LICENSE-KEY'

If no license key was found in the agent configuration file or picked up from user environment variables, the output will be:

license_key = None

network-config config_file [log_file]

Outputs the network configuration which will be used. This can be used in any startup scripts prior to starting up of the actual WSGI application to log the network configuration for the purpose of verifying that the correct values are being used.

It may be used with the agent configuration file:

bash

$newrelic-admin network-config newrelic.ini

If setting any proxy information using environment variables, use - as the name of the configuration file:

bash

$NEW_RELIC_PROXY_HOST=proxy.example.com
$export NEW_RELIC_PROXY_HOST
$
$NEW_RELIC_PROXY_PORT=8888
$export NEW_RELIC_PROXY_PORT
$
$newrelic-admin network-config -

Output will be in the form:

host = 'collector.newrelic.com'
port = 0
proxy_host = 'proxy.example.com'
proxy_port = 8888
proxy_user = None
proxy_pass = None
ssl = True

A value of 0 for port indicates that the port number, either 80 or 443, will be automatically selected based on whether an SSL connection is being used to communicate with our data collector.

local-config config_file [log_file]

Outputs the local agent configuration based on built-in defaults, environment variables, and any agent configuration file. This information may be requested by our technical support when trying to debug any agent startup issues. It may be used with the agent configuration file:

bash

$newrelic-admin local-config newrelic.ini

If setting any settings using environment variables, you can use - as the name of the configuration file:

bash

$newrelic-admin local-config -

server-config config_file [log_file]

Outputs the full configuration for a specific application. This will be the local agent configuration, overridden by any server-side configuration for the specific application. This information may be requested by our technical support when trying to debug any agent startup issues.

It may be used with the agent configuration file:

bash

$newrelic-admin server-config newrelic.ini

If changing any settings using environment variables, you can use - as the name of the configuration file:

bash

$newrelic-admin server-config -

In order to obtain the server-side configuration, this script will force agent registration for the specific application defined by the configuration. If that application does not already appear in the user interface for APM, an entry for it will be created, but no metric data will be reported against it.

record-deploy config_file description

This is a wrapper around the New Relic REST API to record deployments for your application. You can also record deployments directly via the REST API.

To use the command:

Add your API key in the agent configuration file (newrelic.ini) by adding a line similar to the following in the [newrelic] section:
```
api_key=substitute-your-api-key-here
```
Call the newrelic-admin command from the command line. (Do not add it to your config file.) using the following subcommand structure:
bash
```
$newrelic-admin record-deploy config_file description [revision changelog user]
```

This subcommand has two required arguments:

config_file: Path to the config file name
description: Text to describe or identify the deployment; for example, the Git commit comments

There are also three optional arguments:

revision: Identifies a specific revision being deployed
changelog: Provides a detailed log of what changes were made
user: Identifies the person responsible for the deployment

Other advanced tips

Here are some advanced instructions for running the admin script:

You can separately set and export the NEW_RELIC_CONFIG_FILE environment variable before running the script. Ensure you substitute your existing command options for YOUR_COMMAND_OPTIONS:

bash

$NEW_RELIC_CONFIG_FILE=newrelic.ini
$export NEW_RELIC_CONFIG_FILE
$
$newrelic-admin run-program YOUR_COMMAND_OPTIONS

If your startup command uses exec, separate the setting of the environment variable from the execution of the admin script. Ensure you substitute your existing command options for YOUR_COMMAND_OPTIONS:

bash

$NEW_RELIC_CONFIG_FILE=newrelic.ini
$export NEW_RELIC_CONFIG_FILE
$
$exec newrelic-admin run-program YOUR_COMMAND_OPTIONS

If you use a process management system such as supervisord where the environment variables must be set in a separate configuration setting, you cannot set them on the same line as the command.

For example, under supervisord you might use the following. Be sure to substitute your existing command options for YOUR_COMMAND_OPTIONS.

[program:warpdrive]
command = newrelic-admin run-program YOUR_COMMAND_OPTIONS
environment = NEW_RELIC_CONFIG_FILE=newrelic.ini

If the command being run is the python executable and it is being run directly on a Python code file as python main.py, use either of the following:

bash

$newrelic-admin run-program python main.py
$
$newrelic-admin run-python main.py

Using run-python will always use the same python executable as is installed in the Python installation or virtual environment that newrelic-admin is installed.

The newrelic-admin program you run must be coming from the same Python installation or virtual environment as your application is using. You cannot mix programs/components from different Python installations. If this is done, the agent will not run correctly.

If you use a process management system such as supervisord in a virtual environment, you could use this configuration:

[program:warpdrive]
command = newrelic-admin run-program  
environment = PATH="/path/to/python/app/venv/bin",NEW_RELIC_CONFIG_FILE="newrelic.ini"
directory = /path/to/python/app
user = www-data

Note the PATH environment variable that points to the same path that would be used by the virtual environment.

For more information on these options to newrelic-admin and the different configuration options based on user environment variables, see the more detailed documentation for the run-program and run-python options.

Python agent admin script: Advanced usage

Subcommand structure

help <command>

generate-config license_key [output_file]

validate-config config_file [log_file]

run-program ...

run-python ...

license-key config_file [log_file]

network-config config_file [log_file]

local-config config_file [log_file]

server-config config_file [log_file]

record-deploy config_file description

Other advanced tips

Splitting admin script command across multiple lines

Running admin script with Python executable

Notes about the location of newrelic-admin

Python agent admin script: Advanced usage

Subcommand structure .css-21sua1{background:none;border:none;width:0;padding:0;}

help <command>

generate-config license_key [output_file]

validate-config config_file [log_file]

run-program ...

run-python ...

license-key config_file [log_file]

network-config config_file [log_file]

local-config config_file [log_file]

server-config config_file [log_file]

record-deploy config_file description

Other advanced tips

Running admin script with Python executable

Notes about the location of newrelic-admin

Subcommand structure