1 
2المرة الأولى التي تحتاج فيها حقًا إلى إمكانية الملاحظة ليست عندما تنظر بهدوء إلى لوحة القيادة. يحدث ذلك عندما يكتب المستخدم "الخروج بطيء"، ويبدو الرسم البياني للخطأ طبيعيًا وفي السجلات لا تجد سوى صف من الرسائل غير المتصلة.
3 
4تم إنشاء OpenTelemetry لتجنب تلك اللحظة: ليس للحصول على المزيد من الرسومات، ولكن لربط القطع. يدخل الطلب إلى API، ويستدعي قاعدة بيانات، ويمر عبر موفر خارجي، وينشر مهمة في قائمة الانتظار، وربما يفشل ثلاث خدمات لاحقًا. وبدون التتبع الموزع، يمكنك إعادة بناء تلك القصة يدويًا. مع OpenTelemetry على الأقل لديك خريطة.
5 
6## المغزى ليس trace، بل القصة
7 
8أ trace هو تسلسل من span. ضع مثل هذا يبدو باردا. عمليًا، كل span جزء من القصة: `POST /checkout`، `SELECT inventory`، `call payment provider`، `publish order.created`.
9 
10القيمة تأتي عندما تبدأ في الإجابة على الأسئلة الحقيقية:
11 
12- ما هي الخدمة الخارجية التي تتباطأ؟
13- هل الأخطاء تأتي من إصدار معين؟
14- هل المشكلة تؤثر على الجميع أم على مستأجر واحد فقط؟
15- هل إعادة المحاولة تخفي المهلة؟
16- المهمة غير المتزامنة تبدأ ثم تنتهي في مكان آخر؟
17 
18لا يمكن حل هذه الأسئلة بإلقاء `console.log` على عجل. في الواقع، غالبًا ما يساعدك السجل المُضاف في حالات الطوارئ اليوم ويصبح ضجيجًا غدًا.
19 
20## كيف أضع هذا في التطبيق Node.js
21 
22الإعداد الأكثر صحة بسيط: ينتج التطبيق القياس عن بعد، ويقرر Collector مكان إرساله.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28لماذا لا يتم التصدير مباشرة إلى البائع؟ لأنه في البداية يبدو الأمر أسرع، ثم تدرك أن كل خدمة لها تكوينات مختلفة، وعمليات إعادة محاولة مختلفة، ومرشحات مختلفة، ولا توجد نقطة مركزية لإزالة البيانات الحساسة أو تغيير الوجهة.
29 
30Collector ممل بكل الطرق الصحيحة. يتلقى OTLP، ويقوم بالدفع، ويمكنه التصفية، ويمكنه أخذ العينات، ويمكنه إضافة سمات مشتركة ويمكنه التصدير إلى أنظمة متعددة.
31 
32## القياس الذاتي: جيد، لكنه ليس كافياً
33 
34في Node.js سأبدأ بالأجهزة التلقائية. فهو يمنحك رؤية فورية لـ HTTP والأطر المدعومة وقواعد البيانات والمكتبات العامة.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42ثم تقوم بتهيئة SDK قبل بقية التطبيق:
43 
44```typescript
45import { NodeSDK } from '@opentelemetry/sdk-node';
46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
48 
49const sdk = new NodeSDK({
50  traceExporter: new OTLPTraceExporter({
51    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
52  }),
53  instrumentations: [getNodeAutoInstrumentations()],
54});
55 
56sdk.start();
57```
58 
59ومع ذلك، هذا يرى الإطار، وليس المنتج الخاص بك. إنه يعرف أنك قمت بإجراء استعلام، لكنه لا يعرف أن الاستعلام كان في "إنشاء أمر" أو "تجديد الاشتراك". لذلك تحتاج إلى span أدلة في النقاط التي تكون فيها الهيمنة مهمة.
60 
61```typescript
62const span = tracer.startSpan('checkout.create_order');
63 
64try {
65  span.setAttribute('cart.items_count', input.items.length);
66  const order = await createOrder(input);
67  span.setAttribute('order.id', order.id);
68  return order;
69} catch (error) {
70  span.recordException(error as Error);
71  throw error;
72} finally {
73  span.end();
74}
75```
76 
77لن أضع أدلة span في أي مكان. أود أن أضعهم في المكان الذي أرغب في فهم ما حدث فيه، في الساعة الثالثة صباحًا، دون قراءة نصف قاعدة التعليمات البرمجية.
78 
79## ثلاث قواعد تجنبك الكثير من الفوضى
80 
81القاعدة الأولى: يجب أن تحتوي كل خدمة على `service.name` والبيئة والإصدار. يبدو الأمر تافهًا، ولكن بدون هذه السمات، يكون trace أقل فائدة بكثير. عندما يعطل النشر شيئًا ما، فأنت تريد التصفية حسب الإصدار خلال ثانيتين.
82 
83القاعدة الثانية: لا تضع بيانات حساسة في السمات. يجب ألا تنتهي رسائل البريد الإلكتروني والرموز المميزة والحمولات الصحيحة والعناوين في واجهة خلفية قابلة للملاحظة عن طريق الصدفة. إذا كنت بحاجة إلى تحديد هوية مستخدم، ففكر في المعرفات الداخلية أو التجزئة أو الحقول الأقل حساسية.
84 
85القاعدة الثالثة: الانتباه إلى الأصل. `user.id` كخاصية لـ trace يمكن أن يكون له معنى. كتسمية مترية، يمكن أن تدمر تكاليفك وأدائك.
86 
87## المقاييس: قليلة، لكنها جيدة
88 
89سأبدأ بمقاييس عملية للغاية:
90 
91- معدلات والأخطاء ومدة الطلبات؛
92- الكمون من التبعيات الخارجية؛
93- عدد المهلات وإعادة المحاولة؛
94- عمق ذيول.
95- مدة الوظيفة؛
96- نسبة الأخطاء لكل إصدار.
97 
98ويتم إضافة الباقي عند الحاجة. لوحات المعلومات المليئة بالرسوم البيانية التي لا ينظر إليها أحد هي أثاث وليست إمكانية للملاحظة.
99 
100## السجلات: لا تزال مفيدة، ولكنها مرتبطة
101 
102السجلات لا تختفي. إنها ببساطة تصبح أكثر فائدة عندما تحمل `trace_id` و`span_id`. لذا يمكنك البدء من سجل الأخطاء وفتح trace، أو البدء من trace البطيء وقراءة السجلات المنتجة في هذا المسار فقط.
103 
104دون الارتباط، كنت تبحث عن الإبر. مع الارتباط، على الأقل أنت تعرف أي درج يجب أن تنظر إليه.
105 
106## القائمة المرجعية التي سأستخدمها قبل أن أقول "لقد قمنا بالتغطية"
107 
108- إن trace يعبر في الواقع خدمات متعددة.
109- تتضمن السجلات `trace_id` و`span_id`.
110- تم تكوين Collector بحدود الدفع والذاكرة.
111- يتم تسجيل الأخطاء في span.
112- هناك سياسة أخذ العينات.
113- المقاييس تسيطر على العلاقة الأساسية.
114- تتم تصفية البيانات الحساسة.
115- التنبيهات تبدأ من أعراض المستخدم، وليس من الرسوم البيانية العشوائية.
116 
117## الخلاصة
118 
119OpenTelemetry لا يحل مشاكل الإنتاج من تلقاء نفسه. لكن طريقة تعاملك معهم تتغير. بدلاً من إضافة السجلات بشكل أعمى، يمكنك البدء باتباع المسار الفعلي للطلب.
120 
121بالنسبة لي، علامة نجاح الأمر بسيطة: عندما يحدث شيء ما، يتوقف الفريق عن التساؤل "أين نبحث؟" ويبدأ بالتساؤل "لماذا هذه القطعة بطيئة؟". وهنا تصبح إمكانية الملاحظة أداة، وليست مجموعة من لوحات المعلومات.
122 
123## المصادر
124 
125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)
126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)
127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)
128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
129