Troubleshooting Python automatic instrumentation issues

Installation issues

Python package installation failure

The Python package installs require gcc and gcc-c++, which you may need to install if you’re running a slim version of Linux, such as CentOS.

• CentOS
• Debian/Ubuntu
• Alpine

yum -y install python3-devel
yum -y install gcc-c++

apt install -y python3-dev
apt install -y build-essential

apk add python3-dev
apk add build-base

Bootstrap using uv

Running opentelemetry-bootstrap -a install when using the uv package manager may result in errored or unexpected dependency setups.

Instead, you can generate OpenTelemetry requirements dynamically and install them using uv.

First, install the appropriate packages (or add them to your project file and run uv sync):

uv pip install opentelemetry-distro opentelemetry-exporter-otlp

Now, you can install the auto instrumentation:

uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -

Finally, use uv run to start your application (see Configuring the agent):

uv run opentelemetry-instrument python myapp.py

Please note that you have to reinstall the auto instrumentation every time you run uv sync or update existing packages. It is therefore recommended to make the installation part of your build pipeline.

Instrumentation issues

Flask debug mode with reloader breaks instrumentation

The debug mode can be enabled in the Flask app like this:

if __name__ == "__main__":
    app.run(port=8082, debug=True)

The debug mode can break instrumentation from happening because it enables a reloader. To run instrumentation while the debug mode is enabled, set the use_reloader option to False:

if __name__ == "__main__":
    app.run(port=8082, debug=True, use_reloader=False)

Connectivity issues

gRPC Connectivity

To debug Python gRPC connectivity issues, set the following gRPC debug environment variables:

export GRPC_VERBOSITY=debug
export GRPC_TRACE=http,call_error,connectivity_state
opentelemetry-instrument python YOUR_APP.py