Install the Python agent for Docker

You can use the Python agent to instrument Python applications deployed in Docker containers. This document will show you how to build, configure, and deploy an instrumented version of your Dockerized Python application.

Build your instrumented container

This Dockerfile provides a base for your Python Docker image by installing the Python agent. You can customize it by changing the FROM instruction, for example to use another version of Python or a different Linux distribution.

1. To get started, copy the code block below and save it as a new Dockerfile in your directory.

   FROM python:3.6-alpine
   
   RUN pip install --no-cache-dir newrelic
   
   ENTRYPOINT ["newrelic-admin", "run-program"]

   Copy

2. Build the base image:

   $ docker build -t python_newrelic:latest .

   Copy

3. You can use the new image as the base for your own Dockerfile, replacing your FROM line with FROM python_newrelic:latest. You'll need to put your app's command line in a CMD instruction, not in ENTRYPOINT, so that the newrelic-admin program can start it. For example:

   CMD ["gunicorn", "-b :5000", "myapp:app"]

   Copy

4. To enable the agent, you'll need to configure it with environment variables. The NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME variables are required. If you use docker run, for example, you can add -e options:

   $ docker run -e NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY \
           -e NEW_RELIC_APP_NAME="YOUR APPLICATION NAME" \
           INSTRUMENTED_IMAGE_NAME

   Copy

   Tip

   If you're using docker-compose, you can use secrets to manage your license key.

Configure the agent

When configuring the agent, you have two options:

• Recommended: Set the configuration with environment variables
• Use a configuration file

Recommended: Set the configuration with environment variables

You can configure most agent settings with environment variables. You can do this at run time with the -e parameter to docker run, for example:

$ docker run -e NEW_RELIC_APP_NAME="A Different App" \
        -e NEW_RELIC_LOG=stdout \
        -e NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true \
        -e NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY \ 
        INSTRUMENTED_IMAGE_NAME

Or you can include environment variables in your Dockerfile:

ENV NEW_RELIC_LOG=stdout \
    NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true \
    NEW_RELIC_APP_NAME="My Application"
    # etc.

Use a configuration file

When you can't or don't want to set options with environment variables, you can do this with a configuration file.

If you want to configure the Python agent with a configuration file, you can either add your newrelic.ini file to your Docker image at build time or mount the file at run time. The file needs to be placed in your app's root directory.

1. Generate or download the newrelic.ini file described in the Python agent configuration docs.

2. Edit the newrelic.ini file to configure your settings. See the Python agent configuration documentation for more details.

3. Chose one of the following options:

   • Option 1: ADD the newrelic.ini file to your Docker image at build time. Add this line to your Dockerfile, replacing the placeholder with the path to your app (either relative to your WORKDIR or absolute) and build it you normally would.

     ADD newrelic.ini /PATH/TO/YOUR/APP

     Copy

   • Option 2: Mount the newrelic.ini file at run time. Add the -v switch below to your docker run command, replacing /PATH/TO/YOUR/APP with the absolute path to your app's base directory in the Docker image.

     $ docker run -v /local/path/to/newrelic.ini:/PATH/TO/YOUR/APP/newrelic.ini \
             -e NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY \
              INSTRUMENTED_IMAGE_NAME

     Copy