دنبال کردن یک درخواست و گروه‌بندی خطاها

دو پرسش در عیب‌یابی بیش از همه تکرار می‌شوند: «در همین درخواست دیگر چه اتفاقی افتاد؟» و «این خطا چند بار و برای چه کسانی رخ داده؟». LogMug برای هر کدام یک دکمه در جزئیات لاگ دارد. این برگه توضیح می‌دهد هر کدام چطور کار می‌کند و برای اینکه درست کار کند چه چیزی باید در برنامه برقرار باشد.

trace_id چیست

trace_id یک شناسهٔ ۳۲ رقمی هگز است که در شروع یک درخواست ساخته می‌شود و روی همهٔ لاگ‌های همان درخواست می‌نشیند. اگر سرویس شما سرویس دیگری را صدا بزند و شناسه را با هدر استاندارد W3C به نام traceparent منتقل کند، لاگ‌های سرویس دوم هم همان trace_id را می‌گیرند. شرح کامل این مفهوم و تفاوتش با correlation id را در مقالهٔ trace_id و correlation id نوشته‌ام.

«همهٔ لاگ‌های این درخواست»

1. یک لاگ، مثلاً یک خطا، را باز کنید.
2. اگر لاگ trace_id داشته باشد، دکمهٔ «همهٔ لاگ‌های این درخواست» نمایش داده می‌شود. آن را بزنید.
3. فهرست به همهٔ خطوطی که همین trace_id را دارند محدود می‌شود، در همهٔ سرویس‌های پروژه و به ترتیب زمان. بازه خودکار به ۲۴ ساعت گسترش می‌یابد تا خطوط ابتدای درخواست جا نمانند.
4. حالا می‌بینید پیش از خطا چه گذشت: کدام endpoint صدا زده شد، کدام کوئری کند بود و کدام سرویس پایین‌دست پاسخ بد داد.

این فیلتر هم مثل بقیه در نشانی صفحه است، پس لینک آن را می‌توانید در تیکت بگذارید.

چه چیزی trace_id را می‌سازد

• ⁦ASP.NET Core⁩: برای هر درخواست HTTP خودکار ساخته می‌شود، چه با OpenTelemetry وصل شده باشید چه با Serilog (نسخهٔ 3.1 به بعد). HttpClient در ⁦.NET⁩ هدر traceparent را خودکار به درخواست‌های خروجی اضافه می‌کند.
• Java: OpenTelemetry Java Agent برای درخواست‌های ورودی span می‌سازد و هدر را در فراخوانی‌های خروجی منتقل می‌کند؛ حتی وقتی exporter trace را none گذاشته‌اید.
• ⁦Node.js⁩ و Python: auto-instrumentation چارچوب‌های وب رایج همین کار را می‌کند.
• JSON ساده: فیلد trace_id یا traceparent را خودتان بفرستید؛ مرجع API را ببینید.

LogMug خود trace را ذخیره نمی‌کند و ابزار APM نیست؛ trace_id فقط برای پیوند دادن لاگ‌ها به هم به کار می‌رود.

trace_id را به کاربر و پشتیبانی بدهید

یک عادت کوچک که زمان عیب‌یابی را بسیار کم می‌کند: در پاسخ خطا (مثلاً در بدنهٔ ProblemDetails یا یک هدر پاسخ) شناسهٔ trace را برگردانید و در صفحهٔ خطا به کاربر نشان دهید. وقتی پشتیبانی آن را گرفت، کافی است در نشانی صفحهٔ لاگ‌ها پارامتر trace_id را با همان مقدار بگذارد، چون همهٔ فیلترها در نشانی‌اند. مقالهٔ خطای ۵۰۰ در پروداکشن این مسیر را با مثال نشان می‌دهد.

«همهٔ رخدادهای این خطا»

هر لاگی که استثنا دارد، هنگام دریافت یک اثرانگشت (fingerprint) می‌گیرد. اثرانگشت از نوع استثنا و چند فریم بالای stack که در کد خود برنامه هستند ساخته می‌شود:

• شمارهٔ خط در آن نیست، پس با یک تغییر کوچک در فایل، گروه خطا عوض نمی‌شود.
• فریم‌های چارچوب (مثل System.*، Microsoft.*، java.* و org.springframework.*) کنار گذاشته می‌شوند تا دو باگ متفاوت که هر دو به یک متد کتابخانه می‌رسند یکی نشوند.
• شناسه‌های متغیر و متن پیام در آن نیستند، پس «Order 991 not found» و «Order 1204 not found» یک گروه‌اند.

با زدن دکمهٔ «همهٔ رخدادهای این خطا» در جزئیات لاگ، فهرست به همهٔ رخدادهای همان گروه محدود می‌شود. از آنجا:

1. نمودار بالای صفحه نشان می‌دهد خطا از کِی شروع شده و آیا پس از استقرار آخر تکرار می‌شود.
2. فیلتر سرویس و محیط نشان می‌دهد خطا فقط در یک سرور یا محیط است یا همه‌جا.
3. با «فیلتر» روی ویژگی‌هایی مثل user_id می‌بینید چند کاربر درگیرند.

صفحهٔ جداگانه‌ای برای فهرست خطاها با وضعیت باز و حل‌شده، و اعلان هنگام رخداد خطای تازه، در حال ساخت است؛ فعلاً گروه‌بندی از همین دکمه در دسترس است.

اگر دکمه‌ها دیده نمی‌شوند

• دکمهٔ درخواست نیست: لاگ trace_id ندارد؛ مثلاً در کار پس‌زمینه‌ای نوشته شده که داخل هیچ درخواستی نیست.
• لاگ‌های سرویس دوم در یک درخواست نمی‌آیند: هدر traceparent بین دو سرویس منتقل نمی‌شود؛ مثلاً یک پراکسی آن را حذف می‌کند یا فراخوانی با کلاینتی است که instrument نشده است.
• دکمهٔ خطا نیست: لاگ استثنا ندارد. استثنا را به‌عنوان آرگومان به logger بدهید، نه فقط متن ex.Message را در پیام.

برای تصویر بزرگ‌تر از لاگ، trace و جایگاه هر کدام، مقالهٔ OpenTelemetry به زبان ساده را ببینید.