--- title: Python agent admin script: Advanced usage source: https://docs.newrelic.com/docs/apm/agents/python-agent/installation/python-agent-admin-script-advanced-usage --- The Python agent admin script is used during the [installation process](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/introduction-new-relic-python/#installation). 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 [#sub-commands] 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: ```shell newrelic-admin help ``` ## help <command> [#help] When executed with no further arguments, this provides a listing of all accepted subcommands: ```shell newrelic-admin help [output] Usage: newrelic-admin command [options] [output] [output] Type 'newrelic-admin help 'for help on a specific command. [output] [output] Available commands are: [output] generate-config [output] license-key [output] local-config [output] network-config [output] record-deploy [output] run-program [output] run-python [output] server-config [output] validate-config ``` To view additional details about a subcommand, run the help command with the subcommand and any of its options. For example: ```shell newrelic-admin help generate-config [output] Usage: newrelic-admin generate-config license_key [output_file] [output] [output] Generates a sample agent configuration file for . ``` ## generate-config license_key \[output_file] [#generate-config] Generates a sample agent configuration file. The `license_key` option is your 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](https://docs.newrelic.com/docs/python/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](https://download.newrelic.com/python_agent/release/newrelic.ini). ## validate-config config_file \[log_file] [#validate-config] 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: ```shell 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](https://docs.newrelic.com/docs/python/testing-the-python-agent). ## run-program ... [#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: ```ini NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn wsgi:application ``` OR ```shell 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 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 ... [#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: ```ini NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-python wsgi.py ``` OR ```shell NEW_RELIC_CONFIG_FILE=newrelic.ini export NEW_RELIC_CONFIG_FILE newrelic-admin run-python wsgi.py ``` ## license-key config_file \[log_file] [#license-key] 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: ```shell newrelic-admin license-key newrelic.ini ``` OR If setting the license key using environment variables, use `-` as the name of the configuration file: ```shell NEW_RELIC_LICENSE_KEY='YOUR-LICENSE-KEY' export NEW_RELIC_LICENSE_KEY newrelic-admin license-key - ``` Output will be in the form: ```ini 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: ```ini license_key = None ``` ## network-config config_file \[log_file] [#network-config] 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: ```shell newrelic-admin network-config newrelic.ini ``` OR If setting any proxy information using environment variables, use `-` as the name of the configuration file: ```shell 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: ```ini 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] [#local-config] 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: ```shell newrelic-admin local-config newrelic.ini ``` OR If setting any settings using environment variables, you can use `-` as the name of the configuration file: ```shell newrelic-admin local-config - ``` ## server-config config_file \[log_file] [#server-config] Outputs the full configuration for a specific application. This will be the local agent configuration, overridden by any [server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/configure-agent#ssc) 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: ```shell newrelic-admin server-config newrelic.ini ``` OR If changing any settings using environment variables, you can use `-` as the name of the configuration file: ```shell 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 [#record-deploy] 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](https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/recording-deployments). To use the command: 1. Add your [API key](https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-keys) in the [agent configuration file](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration#agent-configuration-file) (`newrelic.ini`) by adding a line similar to the following in the `[newrelic]` section: ```ini 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: ```shell 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 [#advanced-tips] Here are some advanced instructions for running the admin script: **Splitting admin script command across multiple lines** 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`: ````shell 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`: ```shell 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`. ```ini [program:warpdrive] command = newrelic-admin run-program YOUR_COMMAND_OPTIONS environment = NEW_RELIC_CONFIG_FILE=newrelic.ini ``` ```` **Running admin script with Python executable** 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: ````shell 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. ```` **Notes about the location of newrelic-admin** 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: ````ini [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. ````