بايثون - ClickHouse Documentation

تستخدم ClickStack معيار OpenTelemetry لجمع بيانات القياس عن بُعد (السجلات والتتبعات). ويتم إنشاء التتبعات تلقائيًا عبر التضمين التلقائي، لذلك لا حاجة إلى التضمين اليدوي للاستفادة من التتبّع. يغطي هذا الدليل تكامل ما يلي:

السجلات
المقاييس
التتبعات

البدء

تثبيت حزمة التضمين لـ ClickStack OpenTelemetry

استخدم الأمر التالي لتثبيت حزمة التضمين الخاصة بـ ClickStack OpenTelemetry.

pip install hyperdx-opentelemetry

ثبّت مكتبات OpenTelemetry الخاصة بالتتبّع التلقائي للحزم التي يستخدمها تطبيق بايثون. نوصي باستخدام أداة opentelemetry-bootstrap المرفقة مع OpenTelemetry Python SDK لفحص حزم تطبيقك وإنشاء قائمة بالمكتبات المتاحة.

opentelemetry-bootstrap -a install

تكوين متغيرات البيئة

بعد ذلك، ستحتاج إلى تكوين متغيرات البيئة التالية في الـ shell لديك لإرسال بيانات القياس عن بُعد إلى ClickStack عبر OpenTelemetry Collector:

Managed ClickStack
ClickStack Open Source

OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

يُستخدم متغير البيئة OTEL_SERVICE_NAME للتعرّف على خدمتك في تطبيق HyperDX، ويمكن أن يكون أي اسم تريده.

شغّل التطبيق باستخدام وكيل OpenTelemetry لبايثون

يمكنك الآن تشغيل التطبيق باستخدام وكيل OpenTelemetry لبايثون (opentelemetry-instrument).

opentelemetry-instrument python app.py

إذا كنت تستخدم `Gunicorn` أو `uWSGI` أو `uvicorn`

في هذه الحالة، سيتطلب وكيل OpenTelemetry لبايثون بعض التغييرات الإضافية لكي يعمل. لتهيئة OpenTelemetry لخوادم التطبيقات التي تستخدم وضع خادم الويب pre-fork، تأكد من استدعاء الدالة configure_opentelemetry داخل hook ما بعد التفرّع.

Gunicorn
uWSGI
uvicorn

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

لا يعمل OpenTelemetry حاليًا مع uvicorn عند تشغيله باستخدام الخيار --reload أو مع عدة workers (--workers). نوصي بتعطيل هذين الخيارين أثناء الاختبار، أو باستخدام Gunicorn.

الإعدادات المتقدمة

التقاط الشبكة

من خلال تمكين ميزات التقاط الشبكة، يصبح بإمكان المطورين تصحيح أخطاء رؤوس طلبات HTTP وحمولات المتن بفعالية. ويمكن تحقيق ذلك ببساطة عبر ضبط العلامة HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE على 1.

export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1

استكشاف الأخطاء وإصلاحها

عدم ظهور السجلات بسبب مستوى التسجيل

يستخدم معالج logging في OpenTelemetry، افتراضيًا، المستوى logging.NOTSET، والذي يُعيَّن افتراضيًا إلى مستوى WARNING. يمكنك تحديد مستوى logging عند إنشاء logger:

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

التصدير إلى وحدة التحكم

تعرض حزمة OpenTelemetry SDK الخاصة بـ بايثون عادةً الأخطاء في وحدة التحكم عند حدوثها. ومع ذلك، إذا لم تواجه أي أخطاء ولكن لاحظت أن بياناتك لا تظهر في HyperDX كما هو متوقع، فيمكنك تفعيل وضع Debug. عند تفعيل وضع Debug، ستُطبع جميع بيانات القياس عن بُعد في وحدة التحكم، مما يتيح لك التحقق مما إذا كان تطبيقك مهيأً بشكل صحيح لإرسال البيانات المتوقعة.

export DEBUG=true

اطّلع هنا على مزيد من المعلومات حول التضمين في OpenTelemetry لبايثون: https://opentelemetry.io/docs/instrumentation/python/manual/

​البدء

​تثبيت حزمة التضمين لـ ClickStack OpenTelemetry

​تكوين متغيرات البيئة

​شغّل التطبيق باستخدام وكيل OpenTelemetry لبايثون

​إذا كنت تستخدم Gunicorn أو uWSGI أو uvicorn

​الإعدادات المتقدمة

​التقاط الشبكة

​استكشاف الأخطاء وإصلاحها

​عدم ظهور السجلات بسبب مستوى التسجيل

​التصدير إلى وحدة التحكم