Objective

This article will guide you to installing the Python agent in cases where you have an application utilizing gunicorn and multiple worker processes. 

Prerequisites

• Ensure you have installed a Traceable Platform Agent (TPA) before continuing. 
• Note: The TPA host needs to be accessible to the Python agent. We highly recommend registering the TPA with your DNS provider. In the case where the TPA is deployed to the same Kubernetes cluster as the python agent, the hostname for the TPA will be agent.traceableai

Python 3.7+

For applications running Python 3.7 and above, no extra configuration is required. Simply run:

pip install hypertrace-agent

create a config file like the following:

service_name: "example-service-name"
reporting:
 endpoint: http://hostname:4317
 trace_reporter_type: "OTLP"

pass the following environment variable to specify the location of the config file:

export HT_CONFIG_FILE=./config.yaml

and then start your application with the agent, like so:

hypertrace-instrument python app.py

Python 3.6.x and under

For versions of Python under 3.7 there's a little more legwork needed to be done with regards to applications using gunicorn+multiple worker processes.

In addition to all the steps outlined above you'll need to create another file with the following contents:

import hypertrace

def post_fork(server, worker): 
    hypertrace.post_fork(server, worker)

we'll call it gunicorn_config.py (the name of the file doesn't actually matter)

Then, update your application startup command to reference the config file:

hypertrace-instrument gunicorn <all your existing gunicorn options> -c path/to/gunicorn_config.py

The -c path/to/gunicorn_config.py is the important addition, if for whatever reason you notice that the agent is still not properly exporting spans you may want to try appending the -c path/to/gunicorn_config.py flag to the following environment variable: GUNICORN_CMD_ARGS

export GUNICORN_CMD_ARGS=$GUNICORN_CMD_ARGS -c path/to/gunicorn_config.py

once that's complete you should see spans reporting in the Traceable UI. This can be confirmed by looking at the application logs and finding Add post hook <process_id>

The reason this is required for python 3.6.x is that the python function os.register_at_fork was only added as of python 3.7)