تربط وسوم DogStatsD الموحدة مقاييسك المخصصة بالتتبّعات والسجلات الخاصة بالخدمة نفسها عبر ثلاثة وسوم: env وservice وversion. وبدونها تبقى المقياس المرسَل عبر UDP إلى المنفذ 8125 يتيمًا: لا يمكن تصفيته حسب النشر ولا مقارنته بالإصدار السابق.
يتبع هذا الدرس وثائق Datadog: إرسال مقياس إلى DogStatsD، ثم وضع الوسوم على Kubernetes، ثم التحقق من وصولها فعلًا. وبالنسبة لفريق SRE فالرهان ملموس: أثناء حادثة، تخبرك التصفية على version:1.4.2 بسرعة ما إذا كان التراجع مرتبطًا بآخر نشر.
تتناول مدوّنتنا أيضًا كاردينالية المقاييس المخصصة ونموذج فوترة APM. أما هنا فنكتفي بالوسوم.
باختصار
- يستمع DogStatsD عبر UDP على المنفذ 8125 (الوكيل Agent v6 وما بعده). ولا ينتظر التطبيق أي رد.
- توصي Datadog بالوسوم المحجوزة
envوserviceوversionلربط المقاييس والتتبّعات والسجلات. - إذا رأت الخدمة المتغيرات
DD_ENVوDD_SERVICEوDD_VERSION، يضيف عميل DogStatsD هذه الوسوم إلى المقاييس المخصصة. وبحسب الوثائق، لا تفعل عملاء .NET وPHP ذلك. - على Kubernetes، يمكن لـ Admission Controller التابع لـ Cluster Agent حقن هذه المتغيرات انطلاقًا من تسميات (labels) الـ pods.
وسوم DogStatsD الموحدة: المشكلة المطلوب حلها
المقياس checkout.latency الصادر عن عشرين pod لا قيمة له إلا إذا عرفت من أي بيئة ومن أي إصدار جاء. يمكنك كتابة هذه الوسوم يدويًا في كل استدعاء، لكن ذلك هش: خطأ مطبعي واحد ينشئ وسمًا جديدًا، أي سلسلة جديدة.
تنقل الوسوم الموحدة القرار خارج الشيفرة. يحمل النشر القيم، ويقرأها التطبيق من بيئته، ويضيفها العميل. هدف هذا المقال: الحصول على هذا السلوك في خدمة على Kubernetes ثم فحصه من البداية إلى النهاية.
المتطلبات المسبقة بحسب وثائق Datadog: وكيل Agent بالإصدار 6.19.x أو 7.19.x على الأقل، وSDK أو عميل متوافق، وللحقن التلقائي Cluster Agent بالإصدار v7.40 أو أحدث. يتناول هذا المقال Datadog؛ ولا يقول شيئًا عن Dynatrace Managed أو SaaS.
الخطوة 1: إرسال مقياس إلى DogStatsD على المنفذ 8125
قبل الحديث عن الوسوم، تحقق من مسار الشبكة. صيغة الحزمة (datagram) هي: الاسم، ثم القيمة، ثم النوع، ثم معدل أخذ العينات الاختياري، ثم الوسوم مسبوقة بالرمز #. يقبل الاسم أحرف ASCII والأرقام والشرطة السفلية والنقاط. الأنواع هي c (عدّاد) وg (مقياس لحظي gauge) وms (مؤقّت) وh (مدرّج تكراري) وs (مجموعة set) وd (توزيع).

echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125
echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125
يحذف الخيار -n في echo سطر النهاية الأخير. ويفرض الخياران -4u في nc بروتوكول UDP عبر IPv4. وهذه الأوامر مأخوذة من صفحة الوثائق الخاصة بصيغة الحزم.
أين يستمع الوكيل
على مضيف، يُضبط المنفذ بالمعامل dogstatsd_port في datadog.yaml، والقيمة الافتراضية 8125. وفي حاوية، انشر 8125/udp وعرّف DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" إذا وصلت المقاييس من مصدر غير localhost. ومع Helm تقبل الكتلة dogstatsd الخيارات port وuseHostPort وnonLocalTraffic.
على Kubernetes، تقترح الوثائق تمرير عنوان IP الخاص بالعقدة إلى الـ pod عبر DD_AGENT_HOST، مقروءًا من status.hostIP. ثم يرسل الـ pod إلى المنفذ 8125 على هذا العنوان.
الخطوة 2: تهيئة عميل DogStatsD
في جهة التطبيق، يغلّف عميل DogStatsD عملية الإرسال عبر UDP. مثال بلغة Python مأخوذ من الوثائق (pip install datadog):

from datadog import initialize, statsd
options = {
'statsd_host':'127.0.0.1',
'statsd_port':8125
}
initialize(**options)
يوفّر عميل Python أيضًا statsd_constant_tags (وسوم تُطبَّق على كل المقاييس والأحداث وفحوص الخدمة) وstatsd_namespace (بادئة للاسم). وتوضح الوثائق أن عملاء Python آمنون بين الخيوط لكنهم لا يُشارَكون بين العمليات: تنشئ كل عملية فرعية عميلها الخاص، أو تفعّل disable_buffering.
تبقى الثوابت statsd_constant_tags مفيدة لوسم لا يعتمد على النشر. أما env وservice وversion ففضّل لها الآلية الموحدة الموصوفة أدناه.
الخطوة 3: ضبط env وservice وversion على Kubernetes
تصف وثائق الوسوم الموحدة الإعداد الكامل: ثلاث تسميات (labels) هي tags.datadoghq.com/env و/service و/version، توضع في آن واحد على المورد الأب (Deployment) وعلى قالب الـ pod. وفي APM تُضاف المتغيرات DD_ENV وDD_SERVICE وDD_VERSION، وتُقرأ عبر واجهة downward API (fieldRef) من هذه التسميات.

metadata:
labels:
tags.datadoghq.com/env: "prod"
tags.datadoghq.com/service: "checkout"
tags.datadoghq.com/version: "1.4.2"
env:
- name: DD_SERVICE
valueFrom:
fieldRef:
fieldPath: metadata.labels['tags.datadoghq.com/service']
بالنسبة للمقاييس والسجلات، تشير الوثائق إلى أن التسميات على مستوى الـ pod تكفي: فالمتغيرات DD_* مطلوبة لـ APM فقط. لكن كي يضيف عميل DogStatsD في عملية التطبيق الوسوم بنفسه، يجب أن ترى الخدمة المتغيرات الثلاثة. وهذا ما تقوله الصفحة: إذا كانت DD_ENV وDD_SERVICE وDD_VERSION مرئية، تُضاف الوسوم المقابلة إلى المقاييس المخصصة.
حاويات متعددة وDocker
لـ pod فيه عدة حاويات، استخدم tags.datadoghq.com/<NOM_CONTENEUR>.env (و.service و.version). وعلى Docker، التسميات المكافئة هي com.datadoghq.tags.env و.service و.version.
الخطوة 4: ترك Admission Controller يحقن المتغيرات
كتابة المتغيرات في كل manifest عمل متكرر. يقوم Admission Controller التابع لـ Cluster Agent بذلك نيابةً عنك. وبحسب وثائق Datadog، فهو يحقن DD_AGENT_HOST وDD_TRACE_AGENT_URL وDD_ENTITY_ID وDD_EXTERNAL_ENV، إضافةً إلى env وservice وversion المأخوذة من التسميات. وتتقدم تسميات الـ pod على تسميات المورد المالك، ولا يُستبدل أبدًا متغير DD_ENV أو DD_SERVICE أو DD_VERSION موجود مسبقًا.
خيارات التفعيل:
- Datadog Operator:
features.admissionController.enabledوfeatures.admissionController.mutateUnlabelled؛ - Helm:
clusterAgent.admissionController.enabledوclusterAgent.admissionController.mutateUnlabelled(مفعّل افتراضيًا منذ الإصدار 2.35.0 من الـ chart، بحسب الصفحة)؛ - DaemonSet: المتغيران
DD_ADMISSION_CONTROLLER_ENABLEDوDD_ADMISSION_CONTROLLER_MUTATE_UNLABELLEDعلى Cluster Agent.
الحدود التي ينبغي معرفتها
- إنه
MutatingAdmissionWebhook: لا يعدّل الـ pods إلا عند إنشائها. الـ pod العامل بالفعل لا يتلقى شيئًا؛ يجب إعادة إنشائه. - لا يغطي سوى متغيرات APM وDogStatsD والوسوم القياسية.
- مع
mutateUnlabelled: false(القيمة الافتراضية)، لا يُحقن الـ pod الذي لا يحمل تسمية. والـ pod الذي يحملadmission.datadoghq.com/enabled: "false"لا يُحقن أبدًا، حتى لو كانت قيمةmutateUnlabelledهيtrue.
يحدد نمط الاتصال (hostip افتراضيًا، service، socket، csi) كيفية تعبئة DD_AGENT_HOST أو الـ socket. ويتطلب النمط service إصدار Kubernetes 1.22 أو أحدث.
كيف تتحقق من أن كل شيء يعمل
- داخل الـ pod: يجب أن يعرض الأمر
kubectl exec <pod> -- env | grep DD_المتغيراتDD_ENVوDD_SERVICEوDD_VERSIONبقيمك. - في Datadog، افتح Metrics Explorer وصفِّ مقياسك المخصص: يجب أن تظهر الوسوم
envوserviceوversionكواجهات تصفية (facets). - انشر إصدارًا جديدًا: يجب أن تتغير قيمة
version. وتشدد الوثائق على هذه النقطة: يجب أن تتغيرversionمع كل نشر.
لم أنفّذ هذه الأوامر في عنقود (cluster) لأجل هذا المقال؛ فهي مستخلصة من الوثائق المذكورة. أعد قراءتها ضمن سياقك.
- لا تعرّف
envبقيمتين مختلفتين: وسوم StatsD تُضاف إلى بعضها، وقد يحمل المقياس القيمتين معًا. وينطبق ذلك أيضًا علىenvعام (datadog.tagsفي Helm) مع تسمية pod مختلفة. - تجنّب إضافة
versionإلى مقاييس النظام لمضيف غير مُحوَّل إلى حاويات: فهي لا تتغير مع كل استدعاء. - أبقِ قيم الوسوم منخفضة الكاردينالية؛
versionمقبولة، ومعرّف الطلب غير مقبول. - حركة UDP بلا إشعار استلام: المقياس المفقود لا يولّد أي خطأ في جهة التطبيق. راقب الوكيل Agent وليس الشيفرة فقط.
وماذا عن OpenTelemetry؟
بحسب الصفحة نفسها، لا تُدعم المتغيرات DD_* مباشرةً مع OpenTelemetry. يُستخدم OTEL_RESOURCE_ATTRIBUTES مع service.name وservice.version وdeployment.environment.name، ويتقدم OTEL_SERVICE_NAME على service.name. وإذا ترددت بين العالمين، فاقرأ مقارنتنا OpenTelemetry وPrometheus ومقارنة Dynatrace وDatadog. لدى Dynatrace منطقها الخاص في الوسم؛ ولا أصف هنا أي تكافؤ غير موثّق.
لنشر collector في العنقود نفسه، راجع Collector الخاص بـ OpenTelemetry على Kubernetes.
الأسئلة الشائعة
ما المنفذ الذي يستخدمه DogStatsD؟
UDP 8125 افتراضيًا للوكيل Agent v6 وما بعده. ويمكن تغييره بالمعامل dogstatsd_port في datadog.yaml أو بالمتغير DD_DOGSTATSD_PORT في حاوية.
لماذا لا تحمل مقاييس DogStatsD لديّ الوسم version؟
تحقق أولًا من أن العملية ترى DD_VERSION وأن عميلك يتعامل معه: بحسب الوثائق، لا يلتقط عملاء .NET وPHP هذه المتغيرات. ثم تحقق من أن الـ pod أُنشئ بعد تفعيل Admission Controller.
هل المتغيرات DD_* لازمة للمقاييس؟
بالنسبة للمقاييس والسجلات التي يراها الوكيل، تكفي تسميات الـ pod. ولكي يضيف عميل DogStatsD الوسوم داخل العملية، يجب أن تكون المتغيرات موجودة.
خلاصة
ثلاث تسميات وثلاثة متغيرات وAdmission Controller مضبوط جيدًا تكفي ليحمل كل مقياس مخصص بيئته وخدمته وإصداره. إنه استثمار صغير يسرّع التشخيص. وللتوسع في المنهجية، اقرأ قابلية الملاحظة والمراقبة.
المصادر
- DogStatsD، وثائق Datadog
- صيغة حزم DogStatsD، وثائق Datadog
- Unified Service Tagging، وثائق Datadog
- Admission Controller، وثائق Datadog
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لشركة Datadog Inc. Dynatrace علامة تجارية لشركة Dynatrace LLC. أسماء المنتجات تعود إلى مالكيها. مقتطفات الشيفرة مأخوذة من أمثلة الوثائق الرسمية؛ والقيم أمثلة. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.