Python

This guide walks you through setting up Application Performance Monitoring (APM) on a Python application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.

Prerequisites

1. Python Version 3.8+: Verify with python3 --version
2. Pip Version 23.1.2+: Verify with pip --version

Installation

python -m venv myenv
source myenv/bin/activate

pip install middleware-io

middleware-bootstrap -a install

pip list | grep -i flask

Flask                                        3.0.3
opentelemetry-instrumentation-flask          0.48b0

RUN middleware-bootstrap -a install

Instrumentation

To begin with instrumentation, you will need to obtain your API key from Middleware App. Additionally, ensure that the Middleware agent is installed and properly configured as per your application Host Platform and Operating System.

Based on your application requirements, you can choose one of the following methods for instrumentation:

1. Zero Code Instrumentation: This method allows you to instrument your application without modifying any code. It is ideal for quick setups and minimal code. It requires to set environments only.

2. Tracker Function Based Instrumentation: If you require more control over the instrumentation process, this method involves using a tracker function to integrate APM directly into your application’s code.

Method 1: Python Zero-Code Instrumentation

Zero code instrumentation allows you to monitor your Python application without modifying the application code. This can be achieved by setting environment variables that configure the application with Middleware Application Performance Monitoring (APM) tool.

Example:

You can set the following environment variables in your shell to auto instrument:

export MW_API_KEY='<MW_API_KEY>'
export MW_TARGET='https://<MW_UID>.middleware.io:443'
export MW_SERVICE_NAME='MyFlaskServer'
middleware-run python app.py

For Advanced Configuration explore all configuration options with environments for the Middleware APM.

Automatic instrumentation with Python uses a Python agent that can be attached to any Python application. This agent primarily uses monkey patching to modify library functions at runtime, allowing for the capture of telemetry data from many popular libraries and frameworks.

Method 2: Python Tracker Function Based Instrumentation

If you prefer more control and want to integrate APM directly into your application, you can use a middleware function like mw_tracker. This method requires adding a specific function call in your application's code .

Example: Using mw_tracker Function from Middleware

main.py

Python

Your API Keys

from flask import Flask

# Import the mw_tracker from middleware to your app
from middleware import mw_tracker, MWOptions, record_exception, DETECT_AWS_EC2
 mw_tracker(
     MWOptions(
         access_token="<MW_API_KEY>",
         target="https://<MW_UID>.middleware.io:443",
         console_exporter=True,
         debug_log_file=True,

View more

Run Your Application

To run your application, use the following command:

MW_TRACKER=True middleware-run python app.py

Configuration

Advanced Configuration

Use Attributes and Environment Variables to configure Middleware APM.
This table shows the available configuration settings along with the corresponding environment variables that can be used instead.

All OpenTelemetry environment variables are supported and take the highest priority.

Host Based Configuration

If you are deploying the host using Kubernetes or Docker you will need to set the mw_agent_service to the location of the mw-agent.

This variable can be ignored when the agent is running on the same host as the application.

Docker

Kubernetes

Add the mw_agent_service or export environment variable to your application:

Shell

docker run \
  -e MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS> \
  -p 8000:8000 -it --rm --name CONTAINER_NAME DOCKER_IMAGE:IMAGE_TAG

The DOCKER_BRIDGE_GATEWAY_ADDRESS is the IP address of the gateway between the Docker host and bridge network. This is 172.17.0.1 by default. Learn more about Docker bridge networking here

Add the following command to your Dockerfile after the pip install command:

Dockerfile

RUN middleware-bootstrap -a install

Identify the namespace where the Infra Agent is running:

Shell

kubectl get service --all-namespaces | grep mw-service

Then add the following environment variable to your application deployment YAML file:

Shell

MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

Serverless Configuration

If you are running your Python application in a serverless setup without the mw-agent, the MW_API_KEY and MW_TARGET variables are required when running the application:

export MW_API_KEY='<MW_API_KEY>' 
export MW_TARGET='https://<MW_UID>.middleware.io:443' 
middleware-run python app.py

Framework Specific Configurations

Specific frameworks require different configurations when being run, which can be found below:

export DJANGO_SETTINGS_MODULE='mysite.settings' 
middleware-run python manage.py runserver

export MW_API_KEY='<MW_API_KEY>' 
export MW_TARGET='https://<MW_UID>.middleware.io:443' 
export DJANGO_SETTINGS_MODULE='demo.settings' 
middleware-run gunicorn -c conf/gunicorn.conf.py --workers=4  --bind 0.0.0.0:8000 --timeout 120 demo.wsgi

export MW_API_KEY='<MW_API_KEY>' 
export MW_TARGET='https://<MW_UID>.middleware.io:443'
middleware-run uvicorn main:app --host localhost --port 5002

Explore more OpenTelemetry supported libraries here.

Sending Custom Data

Custom Metrics

Create and use a meter to send custom metrics:

main.py

Python

from opentelemetry.metrics import get_meter_provider

# Create a meter
meter = get_meter_provider().get_meter("custom_meter")

# Create a counter
request_counter = meter.create_counter(
    "request_counter", description="Counts the number of requests"
)

View more

Custom Traces

Create and use a tracer to send custom spans:

main.py

Python

from opentelemetry.trace import get_tracer

# Create a tracer
tracer = get_tracer("custom_tracer")

# Start a span
with tracer.start_as_current_span("custom_span"):
    print("Doing some work within the span")

Custom Logs

Utilize logging method to send logs with a given priority. It is recommended to integrate these calls function inside your existing logger:

main.py

Python

logging.info("info sample")
logging.warning("Sample Warning Log") 
logging.error("Sample Error Log.", extra={'tester': 'Alex'})

Custom Attributes

All custom attributes collected will be available as filtering and grouping functions inside of the Middleware platform.

Using similar methods from the above Traces and Logs sections you can attach custom attributes to any trace, span or log:

main.py

Python

from opentelemetry.trace import get_tracer

tracer = get_tracer("custom_tracer")

with tracer.start_as_current_span("span_with_attributes") as span:
    span.set_attribute("user.email", "[email protected]")
    span.set_attribute("user.id", 1234)

Adding Stack Traces

Use record_exception() method to record a stack trace when an exception occurs:

main.py

Python

from middleware import record_exception
    try:
        print("Divide by zero:",1/0)
    except Exception as e:
        record_exception(e)

Continuous Profiling

By default the Python APM captures Continuous Profiling data which provides real-time performance insights from your application to enable rapid identification of resource allocation, bottlenecks, and more. Navigate to the Continuous Profiling section to learn more about using Continuous Profiling with Middleware.

To enable continous profiling for your python application. Install required profiling dependencies with below command:

pip install middleware-io[profiling]

Enable profiling with collect_profiling or export MW_APM_COLLECT_PROFILING=True

Example application

Below is a sample python flask server application.

main.py

Python

Your API Keys

import logging
from middleware import mw_tracker, MWOptions, record_exception, DETECT_AWS_EC2
 mw_tracker(
     MWOptions(
         access_token="<MW_API_KEY>",
         target="https://<MW_UID>.middleware.io:443",
         console_exporter=True,
         debug_log_file=True,
         service_name="MyPythonServer",
         otel_propagators = "b3,tracecontext",

View more

Start the server

MW_SERVICE_NAME="flask-server" middleware-run python app.py

Troubleshooting and Debugging

To help troubleshoot and debug issues with your application's telemetry, you can enable specific settings in the mw_tracker function or use environment variables. These settings allow you to export telemetry data to the console, save them to log files, or debug basic information logs.

#in the `mw_tracker` function from middleware
log_level = "DEBUG"

#as an env variable
MW_LOG_LEVEL = "DEBUG"

#in the `mw_tracker` function from middleware
console_exporter = true

#as an env variable
MW_CONSOLE_EXPORTER = true

#in the `mw_tracker` function from middleware
debug_log_file = true

#as an env variable
MW_DEBUG_LOG_FILE = true

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

OTEL_BSP_SCHEDULE_DELAY = 100