1~
2اولین باری که واقعاً به قابلیت مشاهده نیاز دارید زمانی نیست که با آرامش به داشبورد نگاه می کنید. زمانی است که کاربر می نویسد "تسویه حساب کند است"، نمودار خطا عادی به نظر می رسد و در گزارش ها فقط یک ردیف از پیام های قطع شده را پیدا می کنید.
3~
4OpenTelemetry برای جلوگیری از آن لحظه ایجاد شد: نه برای داشتن گرافیک بیشتر، بلکه برای اتصال قطعات. یک درخواست وارد API می‌شود، یک پایگاه داده را فراخوانی می‌کند، از یک ارائه‌دهنده خارجی عبور می‌کند، یک کار در صف ارسال می‌کند، و شاید بعداً سه سرویس از کار بیفتد. بدون ردیابی توزیع شده، آن داستان را با دست بازسازی می کنید. با OpenTelemetry حداقل یک نقشه دارید.
5~
6## نکته trace نیست، داستان است
7~
8A 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 بسیار کمتر مفید است. وقتی یک Deploy چیزی را خراب می کند، می خواهید بر اساس نسخه در دو ثانیه فیلتر کنید.
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~