بايثون

بايثون لـ ClickStack - حزمة ClickHouse للرصد

تستخدم 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

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

ClickStack Open Source

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

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

uWSGI

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

uvicorn

لا يعمل 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/