Python Instrumentation in Containers

Instrumentation of Python applications in containers with the OpenTelemetry agent

This documentation explains how to instrument Python applications in containers using the zero-code model, with the official OpenTelemetry agent, adapted for use with Elven Observability. The idea is to ensure the collection of traces (and optionally metrics) without code changes, only by adjusting the Dockerfile and environment variables.

Agent installation in the Dockerfile

Add only the necessary packages to the Dockerfile according to your framework. See below for the common packages and those specific to each framework:

Common packages (always install):

RUN pip install \
    opentelemetry-distro \
    opentelemetry-exporter-otlp \
    opentelemetry-instrumentation-requests

FastAPI:

RUN pip install opentelemetry-instrumentation-fastapi

Flask:

RUN pip install opentelemetry-instrumentation-flask

Django:

RUN pip install opentelemetry-instrumentation-django

Important: Do not install unnecessary instrumentations. Ex: apps using Django do not need opentelemetry-instrumentation-fastapi.

Example Dockerfile:

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV DJANGO_SETTINGS_MODULE=config.settings.base

WORKDIR /app

RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    netcat-openbsd \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install OpenTelemetry   
RUN pip install opentelemetry-distro \
    opentelemetry-exporter-otlp \
    opentelemetry-instrumentation \
    opentelemetry-instrumentation-django \
    opentelemetry-instrumentation-requests

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["opentelemetry-instrument", "--", "gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]

Environment Variables Configuration

Set the following variables to enable automatic instrumentation and send data to the Elven collector:

- name: OTEL_SERVICE_NAME
  value: "python-app"

- name: OTEL_RESOURCE_ATTRIBUTES
  value: "service=python-app,environment=production"

- name: OTEL_TRACES_EXPORTER
  value: "otlp"

- name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  value: "http://your_collector_endpoint.com:4317/v1/traces"

- name: OTEL_METRICS_EXPORTER
  value: "otlp"

- name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
  value: "http://your_collector_endpoint.com:4317/v1/metrics"

Explanation:

• OTEL_SERVICE_NAME: name of the service displayed in Grafana/Tempo.

• OTEL_RESOURCE_ATTRIBUTES: extra tags to enrich the traces.

• OTEL_EXPORTER_OTLP_*: endpoints for sending the data.

How to start the app with the agent (CMD)

Use the opentelemetry-instrument command as a wrapper for the application. See below for examples by framework:

FastAPI (with Uvicorn)

CMD ["opentelemetry-instrument", "--", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Flask

CMD ["opentelemetry-instrument", "--", "python", "app.py"]

Django

CMD ["opentelemetry-instrument", "--", "python", "manage.py", "runserver", "0.0.0.0:8000"]

Info: You can adapt the command according to your entrypoint: gunicorn, uvicorn, waitress, etc.

Examples by Environment

Docker Compose

services:
  api:
    build: .
    environment:
      - OTEL_SERVICE_NAME=python-app
      - OTEL_RESOURCE_ATTRIBUTES=service=python-app,environment=production
      - OTEL_TRACES_EXPORTER=otlp
      - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://your_collector_endpoint.com:4317/v1/traces
      - OTEL_METRICS_EXPORTER=otlp
      - OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://your_collector_endpoint.com:4317/v1/metrics

Kubernetes

spec:
  containers:
    - name: python-app
      image: python-app:latest
      env:
        - name: OTEL_SERVICE_NAME
          value: "python-app"
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: "service=python-app,environment=production"
        - name: OTEL_TRACES_EXPORTER
          value: "otlp"
        - name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
          value: "http://your_collector_endpoint.com:4317/v1/traces"
        - name: OTEL_METRICS_EXPORTER
          value: "otlp"
        - name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
          value: "http://your_collector_endpoint.com:4317/v1/metrics" 

ECS (Fargate ou EC2)

"environment": [
  { "name": "OTEL_SERVICE_NAME", "value": "python-app" },
  { "name": "OTEL_RESOURCE_ATTRIBUTES", "value": "service=python-app,environment=production" },
  { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://your_collector_endpoint.com:4317/v1/traces" },
  { "name": "OTEL_TRACES_EXPORTER", "value": "otlp" },
  { "name": "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "value": "http://your_collector_endpoint.com:4317/v1/metrics" },
  { "name": "OTEL_METRICS_EXPORTER", "value": "otlp" }
]

Troubleshooting

• Traces not showing: check if the endpoint is accessible and if the CMD uses opentelemetry-instrument correctly.

• Application timeout: verify if the collector is online and responding on port 4318.

• Duplicate instrumentation: avoid mixing manual instrumentation with the automatic mode.

• Dependency error: each framework requires its specific instrumentation, review the pip install.

Best Practices

• Give meaningful names to services (OTEL_SERVICE_NAME=projeto-env-modulo).

• Separate environments (environment=dev, staging, production).

• Do not expose credentials in environment variables.

• Do not use OTEL_LOG_LEVEL=debug in production.

• Test locally with otel-cli ou curl to validate the collector.

Example of .env

OTEL_SERVICE_NAME=python-app
OTEL_RESOURCE_ATTRIBUTES=service=python-app,environment=production
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://your_collector_endpoint.com:4317/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://your_collector_endpoint.com:4317/v1/metrics
OTEL_METRICS_EXPORTER=otlp

Your Python app is now instrumented with Elven Observability, using auto-instrumentation based on OpenTelemetry.