OpenTelemetry cho Python

Python không cần sửa code: opentelemetry-instrument khởi động SDK trước app, gắn instrumentation cho các thư viện tìm thấy (Flask, Django, FastAPI, requests, httpx, SQLAlchemy, psycopg, …) và đọc bộ biến chuẩn.

Đã kiểm ngày 2026-10-25 với python 3.12.15, opentelemetry-distro 0.66b1, opentelemetry-sdk 1.45.1, flask 3.1.3: traces đạt, logs đạt, log mang trace/span của request.

Cài đặt#

pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-logging# instrumentation for the libraries you already use (Flask, Django, requests, …)opentelemetry-bootstrap -a install

opentelemetry-bootstrap -a install xem các gói đã cài và thêm gói instrumentation tương ứng. Muốn xem trước, chạy opentelemetry-bootstrap -a requirements rồi chép các dòng cần vào file requirements, ghim phiên bản như các gói khác.

Chạy#

Đặt opentelemetry-instrument trước lệnh khởi động app:

export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=trueexport OTEL_SEMCONV_STABILITY_OPT_IN=httpopentelemetry-instrument python app.py

Máy chủ cũng vậy: opentelemetry-instrument uvicorn main:app, opentelemetry-instrument flask run, hoặc opentelemetry-instrument python manage.py runserver --noreload với Django (Django vẫn cần DJANGO_SETTINGS_MODULE như thường lệ).

Logs#

OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true thêm một handler vào root logger, nên mọi bản ghi từ module logging chuẩn (và thư viện dựng trên nó, như structlog dùng backend stdlib) cũng được gửi thành bản ghi log OpenTelemetry mang trace ID và span ID đang chạy. Các handler sẵn có vẫn hoạt động. Bản ghi dưới mức của root logger không được gửi; đặt mức bạn muốn bằng logging.basicConfig(level=logging.INFO) hoặc cấu hình riêng.

Các biến ở trên làm gì#

OTEL_SEMCONV_STABILITY_OPT_IN=http cho span HTTP dùng tên thuộc tính ổn định (url.path, http.request.method, http.response.status_code) mà bộ lọc của Belvador dùng.

Máy chủ fork tiến trình (Gunicorn, uWSGI)#

Worker được fork từ tiến trình cha đã khởi động OpenTelemetry sẽ mất luồng nền của exporter, nên không gửi gì. Với Gunicorn, đừng dùng --preload cùng opentelemetry-instrument, hoặc tự khởi động SDK trong hook post_fork; uWSGI cần lazy-apps = true. Lần chạy của Belvador dùng một tiến trình Flask, nên cách chạy có fork không nằm trong phần đã kiểm.

Tắt bớt instrumentation#

export OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=urllib3,sqlite3

Cùng SDK Python của Sentry#

Giữ sentry-sdk cho lỗi và để tracing tắt (không đặt traces_sample_rate), để OpenTelemetry là bên duy nhất làm chủ tracing, và thêm OTLPIntegration để lỗi mang span đang chạy — cách cài ở Cùng SDK Sentry. Belvador chưa chạy app Python có cả hai, nên liên kết đó chưa được ghi là đã kiểm.