Python agent admin script

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 admin script provides a number of subcommands for performing different actions; for example:

  • Generating the initial agent configuration file
  • Validating your config file
  • Testing the connection to the New Relic core application
  • 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:

newrelic-admin help

help <command>

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

$ newrelic-admin help
    Usage: newrelic-admin command [options]

    Type 'newrelic-admin help <command>' for help on any of the commands listed in this document.

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

    $ 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 New Relic license key.

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 https://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 New Relic download site.

As well as validating the syntax of the configuration file, using the licence_key contained in the agent configuration file to identify your account, will also test whether a connection can be made to the New Relic core application.

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

In connecting to the New Relic core application, 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 New Relic. 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:

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

OR

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 license key.
  • NEW_RELIC_APP_NAME - The name of the application you wish to report data against in the New Relic 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.

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.

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

OR

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:

newrelic-admin license-key newrelic.ini

OR

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

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:

newrelic-admin network-config newrelic.ini

OR

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

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 the New Relic 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 New Relic Technical Support when trying to debug any agent startup issues. It may be used with the agent configuration file:

newrelic-admin local-config newrelic.ini

OR

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

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 New Relic Technical Support when trying to debug any agent startup issues.

It may be used with the agent configuration file:

newrelic-admin server-config newrelic.ini

OR

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

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 New Relic 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:

  1. 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
  2. Call the newrelic-admin command from the command line. (Do not add it to your config file.) using the following subcommand structure:
    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

For more help

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.