Python Agent Troubleshooting Framework Configuration

Python Agent Configuration Framework

Agent Configuration

  1. Make sure the agent has been successfully installed (follow the Installation Troubleshooting Framework for any issues) and reports the data to your New Relic UI.

  2. The only setting that needs to be configured to run the agent is the license_key. It can be set within the newrelic.ini configuration file or via NEW_RELIC_LICENSE_KEY environment variable.

  3. To output the current agent configuration including local settings and server side settings execute newrelic-admin server-config newrelic.ini from the terminal. Confirm that the required settings for your needs are set.

  4. Configuration options:

  5. The primary configuration option is through the newrelic.ini configuration file. This file can be generated by executing newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini which is done during installation.

  6. Python agent can be configured using Environment Variables. The list of available settings is here.

  7. Python agent supports configuration via Server Side Configuration (SSC).

  8. For certain WSGI servers per-request configuration is available. More information is available here.

  9. Selecting which configuration file will be used by the agent:

  10. You can have multiple .ini files stored on your server but you have to point the agent to only one that it will use for configuration. This can be done in two ways:

  11. By using the NEW_RELIC_CONFIG_FILE environment variable supplied at the beginning of the newrelic-admin command.

  12. When using advanced integration you pass the path to the config file as a first argument in the newrelic.agent.initialize() call.

  13. Virtual Environments:

  14. Python agent is another Python package. It can be used within the virtual environment. You must make sure however that the agent and your application are run from within the same virtual environment. Utilize pip freeze command to see available packages for your environments.

  15. Environment variables configuration.

  16. The agent expects that some settings might come in the form of an environment variable. In such a scenario, the setting does not need to exist in the configuration file and having the variable set, will get the agent to read and use it. You can check the list of currently set environment variables with printenv command. Make sure you are within the correct virtual environment.

  17. Configuration order of precedence.

  18. Defaults -> Env Variables -> Agent Config File -> SSC -> per-request config.

Containerized Environments Configuration

  1. The agent feels very good in containers. The installation is essentially the same as the standard way but with use of Dockerfile and automated instructions for example:

  2. By including RUN pip install --no-cache-dir newrelic

  3. By including newrelic within the requirements.txt that is copied over and the following instruction is present in Dockerfile: RUN pip install -r requirements.txt

  4. It is recommended to utilize the power of Environment Variables for the agent configuration in containers.

  5. By passing -e flag to the docker run command, for example docker run -e NEW_RELIC_APP_NAME="MySuperAnaconda" <image_name>

  6. By including ENV instructions within the Dockerfile.

  7. Some examples of Dockerfiles are available here.

Monitoring Background Tasks/Scripts

  1. Very often, the agent is used to capture telemetry data about a script that does some work and dies immediately. Because of the nature of the execution and the agent having no way of knowing what functions will be run it is required to add some manual instrumentation.

  2. The most common and easy way to do that is to decorate the functions/methods that are of interest with a @newrelic.agent.background_task() decorator. This tells the agent that there is a transaction executing and it will instrument it.

  3. Because the script might be too quick for the agent to get a chance and establish connection with New Relic Collectors the following settings are recommended:

  4. startup_timeout = 10.0 which will make sure that the initial transaction is not wasted for the agent connection.

  5. shutdown_timeout = 2.5 to make sure the agent has time to flush the data to us before the application/container dies.

Custom Instrumentation

  1. The Transaction event can be decorated with custom attributes. This is accomplished by calling add_custom_parameter() API call.

  2. It is important to make sure that this call executes within the context of the currently monitored Transaction. To get a reference of a current transaction call `current_transaction() API call.

  3. In some cases, the transaction traces might show Application Code for pieces of code not instrumented by the agent out of the box. To add detail to these traces one can decorate missing functions with @newrelic.agent.function_trace() decorator.