تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

معلومات حول تتبُّع الآلات باستخدام OpenTelemetry

1. مقدمة

تاريخ آخر تعديل: 2021-03-05

إمكانية تتبّع التطبيق

قابلية الرصد وقياس OpenTelemetry

الملاحظة هي المصطلح المستخدم لوصف سمة أي نظام. يسمح النظام مع إمكانية الملاحظة للفرق بتصحيح أخطاء نظامهم بشكل نشط. وفي هذا السياق، توجد ثلاث ركائز للملاحظة؛ والسجلات والمقاييس والتتبعات هي الأدوات الأساسية التي يستخدمها النظام لاكتساب إمكانية الملاحظة.

خدمة OpenTelemetry هي مجموعة من المواصفات وحِزم تطوير البرامج (SDK) التي تتطلّب تسريع عملية قياس حالة بيانات القياس عن بُعد وتصديرها (السجلّات والمقاييس والتتبّعات) التي تتطلّبها إمكانية الملاحظة. OpenTelemetry هو مشروع بمعيار مفتوح يرتكز على المجتمع وبرنامج CNCF. من خلال استخدام المكتبات التي يوفرها المشروع ومنظومته المتكاملة، يستطيع المطوّرون قياس استخدامات تطبيقاتهم بطريقة محايدة من جانب البائع ومقابل بنيات متعددة.

تتبُّع الأداء الموزَّع

يُعد التتبع بين السجلات والمقاييس وعمليات التتبع، وهو القياس عن بُعد الذي يحدد وقت الاستجابة لجزء معين من العملية في النظام. وخاصة في عصر الخدمات المصغَّرة، تُعد عمليات التتبُّع الموزَّعة عاملاً قويًا في رصد المؤثِّرات السلبية في وقت الاستجابة في النظام الموزَّع بشكلٍ عام.

عند تحليل آثار الأنشطة الموزَّعة، يكون تمثيل بيانات التتبُّع هو المفتاح لفهم وقت الاستجابة العام للنظام بنظرة سريعة. في تقرير التتبُّع الموزع، نتعامل مع مجموعة من الطلبات لمعالجة طلب واحد لنقطة دخول النظام على شكل عملية تتبُّع تحتوي على عدة نطاقات.

يمثل المحيط وحدة فردية من العمل يتم إنجازه في نظام موزع، ويسجل أوقات البدء والتوقف. غالبًا ما يكون للامتدادات علاقات هرمية بين بعضها البعض - في الصورة أسفل كل امتدادات أصغر هي امتدادات فرعية لامتداد /رسائل كبير، ويتم تجميعها في تتبع واحد يُظهر مسار العمل من خلال أحد الأنظمة.

خدمة Google Cloud Trace هي أحد خيارات الواجهة الخلفية للتتبُّع الموزَّع، وهي متكاملة بشكلٍ جيد مع منتجات أخرى في Google Cloud.

ما الذي ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستتمكّن من تتبُّع معلومات تتبُّع الأدوات في الخدمات المسماة "Shakesapp". التي تعمل على مجموعة Kubernetes قيد التشغيل على Google Kubernetes Engine. يتم توضيح بنية Shakesapp أدناه:

يرسل العملاء سلسلة استعلام إلى الخادم
يقبل الخادم طلب البحث من العميل، ويجلب جميع أعمال Shakespare بتنسيق نصي من Google Cloud Storage، ويبحث في الأسطر التي تحتوي على طلب البحث ويعرض عدد السطر المتطابق مع العميل.

وستستخدم معلومات التتبع عبر الطلب.

المعلومات التي ستطّلع عليها

كيفية بدء استخدام مكتبات OpenTelemetry Trace في مشروع بايثون
كيفية إنشاء فاصل باستخدام المكتبة
كيفية نشر سياقات الامتداد عبر السلك بين مكونات التطبيق
كيفية إرسال بيانات التتبُّع إلى Google Cloud Trace
كيفية تحليل آثار الأنشطة على Google Cloud Trace

يشرح هذا الدرس التطبيقي كيفية إدارة الخدمات المصغَّرة. لتسهيل فهمه، يحتوي هذا المثال فقط على 3 مكونات (منشئ التحميل والعميل والخادم)، ولكن يمكنك تطبيق العملية نفسها الموضحة في هذا الدرس التطبيقي حول الترميز على أنظمة أكثر تعقيدًا وأكبر حجمًا.

المتطلبات

معرفة بايثون 3

2. الإعداد والمتطلبات

إعداد بيئة ذاتية

إذا لم يكن لديك حساب Google (Gmail أو Google Apps)، يجب عليك إنشاء حساب. سجِّل الدخول إلى وحدة تحكُّم Google Cloud Platform ( console.cloud.google.com) وأنشئ مشروعًا جديدًا.

إذا كان لديك مشروع بالفعل، فانقر فوق القائمة المنسدلة لاختيار المشروع في أعلى يسار وحدة التحكم:

وانقر على "مشروع جديد" في مربع الحوار الناتج لإنشاء مشروع جديد:

إذا لم يكن لديك مشروع، من المفترض أن يظهر لك مربع حوار مثل هذا لإنشاء مشروعك الأول:

يتيح لك مربع الحوار اللاحق لإنشاء المشروع إدخال تفاصيل مشروعك الجديد:

يُرجى تذكُّر رقم تعريف المشروع، وهو اسم فريد في جميع مشاريع Google Cloud (سبق أن تم استخدام الاسم أعلاه ولن يكون مناسبًا لك). ستتم الإشارة إليه لاحقًا في هذا الدرس التطبيقي حول الترميز باسم PROJECT_ID.

بعد ذلك، عليك تفعيل الفوترة في Developers Console لاستخدام موارد Google Cloud وتفعيل Cloud Trace API إذا لم يسبق لك إجراء ذلك.

لا ينبغي أن يكلفك هذا الدرس التطبيقي أكثر من بضعة دولارات، ولكن قد تزيد التكاليف إذا قررت استخدام المزيد من الموارد أو إذا تركتها قيد التشغيل (راجع قسم "التنظيف" في نهاية هذا المستند). تشير المستندات الرسمية إلى أسعار Google Cloud Trace وGoogle Kubernetes Engine وGoogle Artifacat Registry.

إنّ مستخدمي Google Cloud Platform الجدد مؤهّلون للاستفادة من فترة تجريبية مجانية بقيمة 300 دولار أمريكي، ما يجعل هذا الدرس التطبيقي حول الترميز بدون أي تكلفة.

إعداد Google Cloud Shell

يمكن إدارة Google Cloud وGoogle Cloud Trace عن بُعد من الكمبيوتر المحمول، ولكن في هذا الدرس التطبيقي حول الترميز، سنستخدم Google Cloud Shell، وهي بيئة سطر أوامر يتم تشغيلها في السحابة الإلكترونية.

هذا الجهاز الافتراضي المستند إلى نظام دبيان محمل بكل أدوات التطوير التي ستحتاج إليها. وتوفّر هذه الشبكة دليلاً رئيسيًا دائمًا بسعة 5 غيغابايت ويتم تشغيله في Google Cloud، ما يحسّن بشكل كبير من أداء الشبكة والمصادقة. وهذا يعني أنّ كل ما ستحتاجه في هذا الدرس التطبيقي حول الترميز هو متصفّح (نعم، يعمل على جهاز Chromebook).

لتفعيل Cloud Shell من Cloud Console، ما عليك سوى النقر على رمز تفعيل Cloud Shell gcLMt5IuEcJJNnMId-Bcz3sxCd0rZn7IzT_r95C8UZeqML68Y1efBG_B0VRp7hc7qiZTLAF-TXD7SsOadxn8uadgHhaLeASnVS3ZHK39eOlKJOgj9SJua_oeGhMxRrbOg3qigddS2A (من المفترَض أن تستغرق عملية الإعداد والاتصال بالبيئة بضع دقائق فقط).

بعد الربط بتطبيق Cloud Shell، من المفترض أن يظهر لك أنّه قد تمت مصادقتك وأنّ المشروع سبق أن تم ضبطه على PROJECT_ID.

gcloud auth list

مخرجات الأمر

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)

gcloud config list project

مخرجات الأمر

[core]
project = <PROJECT_ID>

إذا لم يتم ضبط المشروع لسبب ما، ما عليك سوى إصدار الأمر التالي:

gcloud config set project <PROJECT_ID>

هل تبحث عن PROJECT_ID؟ تحقَّق من المعرّف الذي استخدمته في خطوات الإعداد أو ابحث عنه في لوحة بيانات Cloud Console:

تضبط Cloud Shell أيضًا بعض متغيرات البيئة تلقائيًا، وهو ما قد يكون مفيدًا عند تشغيل الأوامر المستقبلية.

echo $GOOGLE_CLOUD_PROJECT

ناتج الأوامر

<PROJECT_ID>

أخيرًا، قم بتعيين تهيئة المنطقة الافتراضية والمشروع.

gcloud config set compute/zone us-central1-f

يمكنك اختيار مجموعة متنوعة من المناطق المختلفة. لمزيد من المعلومات، راجع المناطق المناطق:

إعداد Python

نستخدم كلمة "شعر" في هذا الدرس التطبيقي حول الترميز. بإدارة إصدارات الحزمة بصرامة. شغّل الأمر التالي على Cloud Shell:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3 -
source $HOME/.poetry/env

إعداد مجموعة Google Kubernetes

في هذا الدرس التطبيقي حول الترميز، يمكنك تشغيل مجموعة من الخدمات المصغَّرة على Google Kubernetes Engine (GKE). في ما يلي خطوات هذا الدرس التطبيقي:

تنزيل المشروع الأساسي في Cloud Shell
إنشاء خدمات مصغّرة في حاويات
تحميل الحاويات إلى Google Artifact Registry (GAR)
نشر الحاويات على GKE
تعديل رمز المصدر للخدمات من أجل أداة التتبُّع
الانتقال إلى الخطوة 2

تفعيل Kubernetes Engine

أولاً، أعددنا مجموعة Kubernetes حيث يتم تشغيل Shakesapp على GKE، لذلك نحتاج إلى تفعيل GKE. الانتقال إلى القائمة "Kubernetes Engine" والضغط على زر "تفعيل"

أصبحت الآن جاهزًا لإنشاء مجموعة Kubernetes.

إنشاء مجموعة Kubernetes

في Cloud Shell، شغِّل الأمر التالي لإنشاء مجموعة Kubernetes. يُرجى التأكُّد من أنّ قيمة المنطقة تقع ضمن المنطقة التي استخدمتها لإنشاء مستودع Artifact Registry. يمكنك تغيير قيمة المنطقة us-central1-f إذا لم تكن منطقة المستودع تغطيها.

gcloud container clusters create otel-trace-codelab --zone us-central1-f \
--num-nodes 1 \
--machine-type e2-highcpu-4

مخرجات الأمر

Creating cluster otel-trace-codelab in us-central1-f... Cluster is being health-checked (master is healthy)...done.
Created [https://container.googleapis.com/v1/projects/psychic-order-307806/zones/us-central1-f/clusters/otel-trace-codelab].
To inspect the contents of your cluster, go to: https://console.cloud.google.com/kubernetes/workload_/gcloud/us-central1-f/otel-trace-codelab?project=psychic-order-307806
kubeconfig entry generated for otel-trace-codelab.
NAME                LOCATION       MASTER_VERSION    MASTER_IP        MACHINE_TYPE  NODE_VERSION      NUM_NODES  STATUS
otel-trace-codelab  us-central1-f  1.18.12-gke.1210  104.154.162.176  e2-medium     1.18.12-gke.1210  3          RUNNING

إعداد Artifact Registry وSaffold

لدينا الآن مجموعة Kubernetes جاهزة للنشر. بعد ذلك، نستعد لسجل الحاويات للدفع ونشر الحاويات. لتنفيذ هذه الخطوة، نحتاج إلى إعداد GAR والأداة لاستخدامها.

إعداد Artifact Registry

الانتقال إلى قائمة Artifact Registry والضغط على زر "تفعيل"

بعد لحظات، سيظهر لك متصفّح مستودع GAR. انقر على "إنشاء مستودع" وإدخال اسم المستودع.

في هذا الدرس التطبيقي حول الترميز، أسمي المستودع الجديد باسم trace-codelab. تنسيق العنصر هو "Docker" ونوع الموقع الجغرافي هو "المنطقة". اختَر المنطقة القريبة من المنطقة التي ضبطتها للمنطقة التلقائية في Google Compute Engine. فعلى سبيل المثال، اختار هذا المثال "us-central1-f" أعلاه، لذلك نختار هنا "us-central1 (آيوا)". ثم انقر فوق زر "CREATE" .

ستظهر لك الآن رسالة "trace-codelab" على متصفح المستودع.

سنعود إلى هذه الصفحة لاحقًا للتحقّق من مسار السجلّ.

إعداد سافلات

تُعدّ خدمة Skaffold أداة مفيدة عند العمل على إنشاء خدمات مصغّرة يتم تشغيلها على Kubernetes. كما أنها تتعامل مع سير عمل إنشاء حاويات تطبيقات ودفعها ونشرها باستخدام مجموعة صغيرة من الأوامر. يستخدم Skaffold بشكل افتراضي Docker Registry كسجل للحاويات، لذا يجب إعداد skaffold للتعرّف على GAR عند إرسال الحاويات إليه.

افتح Cloud Shell مرة أخرى وتأكَّد مما إذا كان قد تم تثبيت skaffold. (تثبّت Cloud Shell برنامج التخزين في البيئة تلقائيًا.) شغّل الأمر التالي وشاهد إصدار skaffold.

skaffold version

مخرجات الأمر

v1.20.0

الآن، يمكنك تسجيل المستودع الافتراضي لاستخدام Saffold. للحصول على مسار السجلّ، انتقِل إلى لوحة بيانات Artifact Registry وانقر على اسم المستودع الذي أعددته للتو في الخطوة السابقة.

بعد ذلك، ستظهر لك مسارات التنقل في أعلى الصفحة. انقر على الرمز لنسخ مسار قاعدة بيانات المسجّلين إلى الحافظة.

عند النقر على الزر "نسخ"، يظهر مربّع حوار في أسفل المتصفّح يعرض رسالة مثل:

"us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab" تم نسخ

ارجع إلى هيكل السحابة الإلكترونية. نفِّذ الأمر skaffold config set default-repo بالقيمة التي نسختها للتو من لوحة البيانات.

skaffold config set default-repo us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab

مخرجات الأمر

set value default-repo to us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab for context gke_stackdriver-sandbox-3438851889_us-central1-b_stackdriver-sandbox

وعليك أيضًا ضبط السجلّ على ضبط Docker. شغِّل الأمر التالي:

gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

مخرجات الأمر

{
  "credHelpers": {
    "gcr.io": "gcloud",
    "us.gcr.io": "gcloud",
    "eu.gcr.io": "gcloud",
    "asia.gcr.io": "gcloud",
    "staging-k8s.gcr.io": "gcloud",
    "marketplace.gcr.io": "gcloud",
    "us-central1-docker.pkg.dev": "gcloud"
  }
}
Adding credentials for: us-central1-docker.pkg.dev

بإمكانك الآن الانتقال إلى الخطوة التالية لإعداد حاوية Kubernetes على GKE.

ملخّص

في هذه الخطوة، يمكنك إعداد بيئة الدرس التطبيقي حول الترميز:

إعداد Cloud Shell
تم إنشاء مستودع Artifact Registy لسجل الحاوية
إعداد skaffold لاستخدام سجلّ الحاوية
إنشاء مجموعة Kubernetes حيث يتم تشغيل الخدمات المصغَّرة للدروس التطبيقية حول الترميز

الخطوة التالية هي إنشاء الخدمات المصغَّرة ونشرها ونشرها على المجموعة

3- إنشاء الخدمات المصغَّرة ونشرها ونشرها

تنزيل مواد الدرس التطبيقي حول الترميز

في الخطوة السابقة، حدّدنا جميع المتطلّبات الأساسية لهذا الدرس التطبيقي حول الترميز. أنت الآن جاهز لتشغيل خدمات مصغّرة بالكامل فوقها. تتم استضافة مواد الدرس التطبيقي على GitHub، لذا يمكنك تنزيلها في بيئة Cloud Shell باستخدام أمر git التالي.

cd ~
git clone https://github.com/GoogleCloudPlatform/opentelemetry-trace-codelab-python.git

هيكل دليل المشروع هو كما يلي:

shakesapp-python
├── LICENSE
├── manifests
│   ├── client.yaml
│   ├── loadgen.yaml
│   └── server.yaml
├── proto
│   └── shakesapp.proto
├── skaffold.yaml
└── src
    ├── client
    ├── loadgen
    └── server

ملفات البيان: ملفات بيان Kubernetes
Proto: تعريف Proto للاتصال بين العميل والخادم
src: أدلة للرمز المصدر لكل عملية بحث
skaffold.yaml: ملف الإعداد لـ skaffold

تشغيل أمر skaffold

وأخيرًا، أصبحت جاهزًا لإنشاء المحتوى ونشره ونشره في مجموعة Kubernetes التي أنشأتها للتو. يحتوي هذا الصوت على خطوات متعددة ولكن العنصر الفعلي هو ساكسفون يقدم كل شيء نيابة عنك. لنجرب ذلك باستخدام الأمر التالي:

cd shakesapp-python
skaffold run --tail

فور تشغيل الأمر، يظهر ناتج السجلّ docker build ويمكنك التأكُّد من أنّه تم إرسال هذه الأوامر بنجاح إلى قاعدة بيانات المسجّلين.

مخرجات الأمر

...
---> Running in c39b3ea8692b
 ---> 90932a583ab6
Successfully built 90932a583ab6
Successfully tagged us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab/serverservice:step1
The push refers to repository [us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab/serverservice]
cc8f5a05df4a: Preparing
5bf719419ee2: Preparing
2901929ad341: Preparing
88d9943798ba: Preparing
b0fdf826a39a: Preparing
3c9c1e0b1647: Preparing
f3427ce9393d: Preparing
14a1ca976738: Preparing
f3427ce9393d: Waiting
14a1ca976738: Waiting
3c9c1e0b1647: Waiting
b0fdf826a39a: Layer already exists
88d9943798ba: Layer already exists
f3427ce9393d: Layer already exists
3c9c1e0b1647: Layer already exists
14a1ca976738: Layer already exists
2901929ad341: Pushed
5bf719419ee2: Pushed
cc8f5a05df4a: Pushed
step1: digest: sha256:8acdbe3a453001f120fb22c11c4f6d64c2451347732f4f271d746c2e4d193bbe size: 2001

بعد نشر كل حاويات الخدمات، تبدأ عمليات نشر Kubernetes تلقائيًا.

مخرجات الأمر

sha256:b71fce0a96cea08075dc20758ae561cf78c83ff656b04d211ffa00cedb77edf8 size: 1997
Tags used in deployment:
 - serverservice -> us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab/serverservice:step4@sha256:8acdbe3a453001f120fb22c11c4f6d64c2451347732f4f271d746c2e4d193bbe
 - clientservice -> us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab/clientservice:step4@sha256:b71fce0a96cea08075dc20758ae561cf78c83ff656b04d211ffa00cedb77edf8
 - loadgen -> us-central1-docker.pkg.dev/psychic-order-307806/trace-codelab/loadgen:step4@sha256:eea2e5bc8463ecf886f958a86906cab896e9e2e380a0eb143deaeaca40f7888a
Starting deploy...
 - deployment.apps/clientservice created
 - service/clientservice created
 - deployment.apps/loadgen created
 - deployment.apps/serverservice created
 - service/serverservice created

تنبيه: إذا ظهرت لك رسالة الخطأ مثل "لا يمكن الوصول السريع إلى مستودع الصور المحدّد"، تحقَّق مما إذا كان أمر skaffold يحاول إرسال الصور إلى Docker Hub (docker.io) بغض النظر عن الضبط على الريبو التلقائي في skaffold. في هذه الحالة، جرِّب إضافة " –default-repo" خيار "الجري" كما هو موضح أدناه.

$ skaffold run –tail –default-repo=us-central1-docker.pkg.dev/[project ID]/[اسم المستودع]

بعد النشر، سترى سجلات التطبيق الفعلية المنبعثة إلى تنسيق stdout في كل حاوية على النحو التالي:

مخرجات الأمر

[server] {"event": "starting server: 0.0.0.0:5050", "severity": "info", "timestamp": "2021-03-17T05:25:56.758575Z"}
[client] [2021-03-17 05:25:54 +0000] [1] [INFO] Starting gunicorn 20.0.4
[client] [2021-03-17 05:25:54 +0000] [1] [INFO] Listening at: http://0.0.0.0:8080 (1)
[client] [2021-03-17 05:25:54 +0000] [1] [INFO] Using worker: threads
[client] [2021-03-17 05:25:54 +0000] [7] [INFO] Booting worker with pid: 7
[client] {"event": "server address is serverservice:5050", "severity": "info", "timestamp": "2021-03-17T05:25:54.888627Z"}
[client] {"event": "request to server with query: world", "severity": "info", "timestamp": "2021-03-17T05:26:11.550923Z"}
[server] {"event": "query: world", "severity": "info", "timestamp": "2021-03-17T05:26:11.567048Z"}
[loadgen] {"event": "check connectivity: http://clientservice:8080/_healthz", "severity": "info", "timestamp": "2021-03-17T05:26:11.533605Z"}
[loadgen] {"event": "/_healthz response: ok", "severity": "info", "timestamp": "2021-03-17T05:26:11.544267Z"}
[loadgen] {"event": "confirmed connection ot clientservice", "severity": "info", "timestamp": "2021-03-17T05:26:11.544527Z"}

وأخيرًا، أصبحت جاهزًا لبدء تشغيل تطبيقك باستخدام OpenTelemetry لإجراء تتبُّع موزّع للخدمات.

ملخّص

في هذه الخطوة، تكون قد أعددت مواد التمرين المعملي حول الترميز في بيئتك وتأكدت من تشغيل سقالة على النحو المتوقع.

في الخطوة التالية، ستقوم بتعديل الرمز المصدر لخدمة التحميل لقياس معلومات التتبع.

4. قياس حالة HTTP

مفهوم أدوات التتبع والانتشار

قبل تعديل رمز المصدر، دعوني أشرح بإيجاز كيفية عمل إشارات التتبّع الموزعة في رسم تخطيطي بسيط.

في هذا المثال، نستخدم الرمز البرمجي لتصدير معلومات التتبع والمساحة إلى خدمة Cloud Trace وننشر سياقها عبر الطلب من خدمة مجموعة التحميل إلى خدمة الخادم.

يحتاج التطبيق إلى إرسال البيانات الوصفية للتتبُّع مثل "رقم تعريف التتبُّع" و"رقم تعريف النطاق" (Span ID) لتجميع جميع النطاقات التي تحتوي على "معرّف التتبُّع" (Trace) نفسه في عملية تتبُّع واحدة. كما يحتاج التطبيق إلى نشر سياقات التتبع (مزيج من معرّف التتبع ومعرّف Span للنطاق الرئيسي) عند طلب خدمات المراحل الأخيرة، حتى يكون على دراية بسياق التتبع الذي يعالجه.

يساعدك OpenTelemetry على:

لإنشاء رقم تعريف تتبّع فريد ومعرّف نطاق زمني
لتصدير "رقم تعريف التتبُّع" و"رقم تعريف النطاق" (Span ID) إلى الواجهة الخلفية
لنشر سياقات التتبع في الخدمات الأخرى

المسافة الأولى للأداة

خدمة إنشاء معدّات تحميل الآلات

افتح محرِّر Cloud Shell بالضغط على الزر في أعلى يسار Cloud Shell. افتح src/loadgen/loadgen.py من المستكشف في اللوحة اليمنى وابحث عن الدالة main.

src/loadgen/loadgen.py

def main():
    ...
    # start request loop to client service
    logger.info("start client request loop")
    addr = f"http://{target}"
    while True:
        logger.info("start request to client")
        call_client(addr)
        logger.info("end request to client")
        time.sleep(2.0)

في الدالة main، سترى الحلقة التي تستدعي الدالة call_client فيها. في التنفيذ الحالي، يحتوي sectoin على سطرَي سجلّ لتسجيل بداية استدعاء الدالة ونهايته. والآن، لنستخدم معلومات Span لتتبع وقت استجابة استدعاء الدالة.

أولاً، يجب إنشاء Span بمعرّف Trace ID فريد ومعرّف Span. يوفر OpenTelemetry مكتبة مفيدة. أضف الأسطر التالية لاستيراد مكتبات OpenTelemetry إلى التعليمة البرمجية.

 import structlog
+from opentelemetry import propagate, trace
+from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.propagators.cloud_trace_propagator import CloudTraceFormatPropagator

بما أنّ منشئ التحميل يستدعي تطبيق العميل في HTTP عبر وحدة requests، نستخدم حزمة الإضافة الخاصة بـ requests ونفعّل الأداة.

 from opentelemetry.propagators.cloud_trace_propagator import CloudTraceFormatPropagator
+
+RequestsInstrumentor().instrument()

بعد ذلك، يمكنك إعداد مثيل أداة التتبُّع الذي يعالج إعدادات جهة التصدير وإعدادات جهة الإصدار.

     target = os.environ.get("CLIENT_ADDR", "0.0.0.0:8080")

+    exporter = CloudTraceSpanExporter()
+    trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(exporter))
+    tracer = trace.get_tracer(__name__)
+    propagate.set_global_textmap(CloudTraceFormatPropagator())
+    trace.set_tracer_provider(TracerProvider())
+
     # connectivity check to client service
     healthz = f"http://{target}/_healthz"
     logger.info(f"check connectivity: {healthz}")

بما أنّ هذا درس تطبيقي حول الترميز لفهم كيفية عمل أدوات التتبُّع، نضبط برنامج التتبُّع لتسجيل كل طلب وإرساله إلى الواجهة الخلفية. (SimpleSpanProcessor()) هذا القسم لا يتناسب مع بيئات الإنتاج، لذا يجب تغييره عند إعداد تطبيق الإنتاج.

يمكنك الآن استخدام أداة Spans باستخدام أداة التتبع. النقطة هنا هي أن ما عليك القيام به هو إنشاء Span بشكل صريح، وهذا كل شيء! وعلى الرغم من وجود سطرين يضيفان البيانات الوصفية للحدث إلى Span، لست بحاجة إلى إنشاء رقم تعريف تتبّع فريد ورقم تعريف Span يدويًا وتضمينهما في Span.

     logger.info("start client request loop")
     addr = f"http://{target}"
     while True:
-        logger.info("start request to client")
-        call_client(addr)
-        logger.info("end request to client")
+        with tracer.start_as_current_span("loadgen") as root_span:
+            root_span.add_event(name="request_start")
+            logger.info("start request to client")
+            call_client(addr)
+            root_span.add_event(name="request_end")
+            logger.info("end request to client")
         time.sleep(2.0)

لكي يجلب إصدار Docker حزم OpenTelemetry المطلوبة، شغّل الأمر التالي:

poetry add "opentelemetry-exporter-gcp-trace=^1.0.0rc0"
poetry add "opentelemetry-propagator-gcp=^1.0.0rc0"
poetry add "opentelemetry-instrumentation-requests=^0.20b0"

يمكنك التأكّد من كتابة وصف التبعية المقابل باللغة pyproject.toml.

خدمة عملاء الأدوات

في القسم السابق، قمنا بقياس الجزء المحصور في المستطيل الأحمر في الرسم أدناه. قمنا بتجهيز معلومات الامتداد في خدمة منشئ الحمولة. على غرار خدمة منشئ التحميل، نحتاج الآن إلى ضبط خدمة العميل. الاختلاف عن خدمة منشئ التحميل هو أن خدمة العميل تحتاج إلى استخراج معلومات معرف التتبع التي تم نشرها من خدمة منشئ التحميل في رأس HTTP واستخدام المعرف لإنشاء Spans.

افتح محرِّر Cloud Shell وأضِف الوحدات المطلوبة كما فعلنا مع خدمة منشئ الحِمل.

src/client/client.py

 import flask
 import grpc
 import structlog
+from opentelemetry import propagate, trace
+from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+from opentelemetry.instrumentation.flask import FlaskInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.propagators.cloud_trace_propagator import \
+    CloudTraceFormatPropagator

 import shakesapp_pb2
 import shakesapp_pb2_grpc

لاحظت أنّك استوردت للتو FlaskInstrumentor التي تفعِّل الأداة التلقائية لتطبيق Flask نيابةً عن المستخدمين من أجل استخراج عناوين HTTP للحصول على سياقات التتبُّع باستخدام سطر واحد من الرمز. يوفّر منتدى OpenTelemetry عمليات دمج مفيدة مماثلة مع المكتبات الرئيسية الأخرى. لمزيد من المعلومات، يمكنك الرجوع إلى المستندات الرسمية.

 app = flask.Flask(__name__)
+FlaskInstrumentor().instrument_app(app)

قبل بدء قياس حالة الأداة، مجددًا، تحتاج إلى إعداد مثيل أداة التتبع بشكل مشابه لما قمنا به في خدمة منشئ الحمولة.

 logger.info(f"server address is {SERVER_ADDR}")

+exporter = CloudTraceSpanExporter()
+trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(exporter))
+propagate.set_global_textmap(CloudTraceFormatPropagator())
+trace.set_tracer_provider(TracerProvider())

 @app.route("/")
 def main_handler():
    ....

ويمكن الآن إضافة أدوات إلى المعالج. ابحث عن main_handler() وعدِّل الجزء الذي يعرض طلب gRPC إلى خدمة الخادم.

@app.route("/")
def main_handler():
    q, count = random.choice(list(queries.items()))

    # get Tracer
    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("client") as cur_span:
        channel = grpc.insecure_channel(SERVER_ADDR)
        stub = shakesapp_pb2_grpc.ShakespeareServiceStub(channel)
        logger.info(f"request to server with query: {q}")
        cur_span.add_event("server_call_start")
        resp = stub.GetMatchCount(shakesapp_pb2.ShakespeareRequest(query=q))
        cur_span.add_event("server_call_end")
        if count != resp.match_count:
            raise UnexpectedResultError(
                f"The expected count for '{q}' was {count}, but result was {resp.match_count } obtained"
            )
        result = str(resp.match_count)
        logger.info(f"matched count for '{q}' is {result}")
    return result

على نحو مشابه لتحميل خدمة المنشئ، أضِف الحِزم المطلوبة إلى pyproject.toml باستخدام الأمر التالي.

poetry add "opentelemetry-exporter-gcp-trace=^1.0.0rc0"
poetry add "opentelemetry-propagator-gcp=^1.0.0rc0"
poetry add "opentelemetry-instrumentation-flask=^0.20b0"

بعد ذلك، جرِّب تشغيل التطبيق من خلال الأمر skaffold run واطّلِع على ما تعرضه لوحة بيانات Cloud Trace:

skaffold run --tail

بعد رؤية بعض الرسائل التي يتم إنشاؤها وإرسالها ونشرها، ستظهر لك سجلّات التطبيق بتنسيقات JSON. الانتقال بنفسك إلى Cloud Trace > قائمة التتبُّع للتأكُّد من حصولك على معلومات التتبُّع. ولأنّ خدمة منشئ التحميل ترسل الطلبات إلى خدمة العميل بشكل دوري ولأنك فعّلت عمليات التتبّع لجميع الطلبات، ستبدأ في رؤية الكثير من النقاط في قائمة التتبّع.

عند النقر على أحد تلك الخيارات، سيظهر لك رسم بياني بدون انقطاع، كما هو موضّح أدناه، يشرح وقت الاستجابة لكل جزء من أجزاء عملية الطلب والاستجابة. ابحث عن مربّع الاختيار بجانب "عرض الأحداث"، وستظهر لك التعليقات التوضيحية داخل الرسم البياني الانحداري. هذه التعليقات التوضيحية هي تلك التي أدخلتها في الرمز باستخدام طريقة span.add_event().

قد تلاحظ أنك لا ترى امتدادات من خدمة الخادم. هذا صحيح لأننا لم نضبط Spans في خدمة الخادم على الإطلاق.

ملخّص

في هذه الخطوة، تكون قد أعددت خدمة منشئ التحميل وخدمة العميل وتأكدت من إمكانية نشر Trace Context عبر الخدمات وتصدير معلومات Span من كلتا الخدمتين إلى Cloud Trace.

في الخطوة التالية، ستستعين بخدمة العميل وخدمة الخادم لتأكيد كيفية نشر Trace Context عبر gRPC.

5- قياس حالة gRPC

في الخطوة السابقة، تم قياس النصف الأول من الطلب في هذه الخدمات المصغَّرة. في هذه الخطوة، نحاول استخدام اتصال gRPC بين خدمة العميل وخدمة الخادم. (مستطيل أخضر وأرجواني في الصورة أدناه)

أدوات تلقائية لعميل gRPC

يوفر نظام OpenTelemetry الشامل الكثير من المكتبات المفيدة التي تساعد مطوري البرامج في قياس أداء التطبيقات. في الخطوة السابقة، استخدمنا أداة تلقائية لـ "الطلبات" واحدة. في هذه الخطوة، بينما نحاول نشر سياق "Trace Context" من خلال gRPC، نستخدم المكتبة لذلك.

src/client/client.py

 import flask
 import grpc
 import structlog
 from opentelemetry import propagate, trace
 from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
 from opentelemetry.instrumentation.flask import FlaskInstrumentor
+from opentelemetry.instrumentation.grpc import GrpcInstrumentorClient
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import SimpleSpanProcessor
 from opentelemetry.propagators.cloud_trace_propagator import \
     CloudTraceFormatPropagator
 import shakesapp_pb2
 import shakesapp_pb2_grpc


 app = flask.Flask(__name__)
 FlaskInstrumentor().instrument_app(app)
+GrpcInstrumentorClient().instrument()

بالنسبة إلى خدمة العملاء، فإن ما نحتاج إلى القيام به بالنسبة إلى الأدوات صغير جدًا. ما نريد القيام به هو نشر سياق التتبع، وهو تركيبة من معرّف التتبع ومعرّف Span للنطاق الحالي عبر gRPC. لذا، نستدعي GrpcInstrumentatorClient.instrument() ليتمكّن عميل gRPC في دالة المعالج من تضمين سياق التتبع في عنوان HTTP أسفله.

تأكَّد من إضافة تبعيات جديدة إلى pyproject.toml باستخدام الأمر poetry add:

poetry add "opentelemetry-instrumentation-grpc=^0.20b0"

أدوات تلقائية لخادم gRPC

مثلما فعلنا مع عميل gRPC، نطلق على الأداة التلقائية لخادم gRPC. أضِف عمليات استيراد، مثل المتابعات، واستدعِ GrpcInstrumentationServer().instrument() في أعلى الملف.

تنبيه: تأكَّد من الاتصال.

GrpcInstrumentationServe()

في هذه الخطوة، وليس

GrpcInstrumentationClient()

src/server/server.py

 import grpc
 import structlog
 from google.cloud import storage
 from grpc_health.v1 import health_pb2, health_pb2_grpc
+from opentelemetry import propagate, trace
+from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+from opentelemetry.instrumentation.grpc import GrpcInstrumentorServer
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.propagators.cloud_trace_propagator import CloudTraceFormatPropagator

 import shakesapp_pb2
 import shakesapp_pb2_grpc


 BUCKET_NAME = "dataflow-samples"
 BUCKET_PREFIX = "shakespeare/"

+# enable auto gRPC server trace instrumentation
+GrpcInstrumentorServer().instrument()
+

وبعد ذلك، عليك إضافة المُصدِّر لإرسال معلومات التتبُّع إلى الواجهة الخلفية Cloud Trace. أضف الرمز التالي في الدالة serve().

def serve():
+    # start trace exporter
+    trace.set_tracer_provider(TracerProvider())
+    trace.get_tracer_provider().add_span_processor(
+        SimpleSpanProcessor(CloudTraceSpanExporter())
+    )
+    propagators.set_global_textmap(CloudTraceFormatPropagator())
+
+    # add gRPC services to server
     server = grpc.server(futures.ThreadPoolExecutor(max_workers=4))
     service = ShakesappService()
     shakesapp_pb2_grpc.add_ShakespeareServiceServicer_to_server(service, server)
     health_pb2_grpc.add_HealthServicer_to_server(service, server)

تأكَّد من إضافة الحزم المضافة حديثًا في خدمة الخادم.

poetry add "opentelemetry-exporter-gcp-trace=^1.0.0rc0"
poetry add "opentelemetry-instrumentation-grpc=^0.20b0"
poetry add "opentelemetry-propagator-gcp=^1.0.0rc0"
poetry add "opentelemetry-instrumentation=^0.20b0"

تشغيل الخدمة المصغّرة وتأكيد عملية التتبُّع

ثم قم بتشغيل التعليمة البرمجية المعدّلة باستخدام الأمر skaffold.

skaffold run --tail

ومرة أخرى، سترى مجموعة من آثار الأنشطة في صفحة قائمة التتبُّع ضمن Cloud Trace. انقر على أحد التتبعات لتجد الآن أنه يمتد عبر الطلب من خدمة منشئ الحمولة إلى خدمة الخادم.

ملخّص

في هذه الخطوة، تم قياس الاتصال المستند إلى gRPC بدعم من مكتبات المنظومة المتكاملة OpenTelemetry. وقد تأكّدت أيضًا من أنّ "سياق التتبّع" الذي تمّ إنشاؤه في خدمة منشئ الحمولة قد تمّ تسليمه بنجاح إلى خدمة الخادم.

6- تهانينا

لقد أنشأت بنجاح عمليات تتبُّع موزَّعة باستخدام OpenTelemery، وأكِّدت أوقات استجابة الطلبات على مستوى الخدمة المصغَّرة على Google Cloud Trace.

بالنسبة إلى التمارين الممتدة، يمكنك تجربة الموضوعات التالية بنفسك.

ترسل عملية التنفيذ الحالية جميع النطاقات التي تم إنشاؤها من خلال التحقّق من الصحة. كيف يمكنك فلترة هذه المسافات من "تتبُّع السحابة الإلكترونية"؟ يمكنك الاطّلاع على التلميح هنا.
يمكنك ربط سجلات الأحداث بالامتدادات ومعرفة كيفية عملها على Google Cloud Trace وGoogle Cloud Logging. يمكنك الاطّلاع على التلميح هنا.
استبدِل بعض الخدمات بالخدمة بلغة أخرى، وجرِّب الأداة باستخدام OpenTelemetry لتلك اللغة.

تنبيه: تستهلك Google Kubernetes Engine وGoogle Artifact Registry المورد باستمرار.

إخلاء مساحة

بعد إكمال هذا الدرس التطبيقي حول الترميز، يُرجى إيقاف مجموعة Kubernetes والتأكّد من حذف المشروع حتى لا يتم تحصيل رسوم غير متوقعة من Google Kubernetes Engine أو Google Cloud Trace أو Google Artifact Registry.

أولاً، احذف المجموعة باستخدام الأمر التالي:

skaffold delete

مخرجات الأمر

Cleaning up...
 - deployment.apps "clientservice" deleted
 - service "clientservice" deleted
 - deployment.apps "loadgen" deleted
 - deployment.apps "serverservice" deleted
 - service "serverservice" deleted

بعد حذف المجموعة، حدِّد "إدارة الهوية وإمكانية الوصول المشرف" > "الإعدادات"، ثم النقر على "إيقاف الصوت" .

بعد ذلك، أدخِل رقم تعريف المشروع (وليس اسم المشروع) في النموذج الوارد في مربّع الحوار وأكِّد إيقاف التشغيل.