عیب‌یابی سرویس‌های Python با OpenTelemetry

از «سرویس کند است» به مسیر دقیق درخواست

وقتی کاربر می‌گوید ثبت سفارش کند شده، میانگین زمان پاسخ سرور نمی‌گوید مشکل از پایگاه داده است، سرویس پرداخت یا صف پردازش. Trace یک درخواست را به چند مرحله مرتبط تقسیم می‌کند. هر مرحله span است و رابطه پدر و فرزند نشان می‌دهد زمان کجا صرف شده است. OpenTelemetry ابزار مشترکی برای تولید و انتقال این داده‌ها فراهم می‌کند. هدف این راهنما ساخت یک نقطه شروع کوچک برای Python است؛ اگر داده ثبت‌شده به یک تصمیم عیب‌یابی کمک نکند، زیاد شدن حجم آن ارزش مستقلی ندارد.

لاگ شرح یک رخداد است، metric اندازه‌گیری تجمیعی و trace مسیر یک کار مشخص. این سه مکمل هم هستند. برای نمونه، افزایش نرخ خطا در metric شما را به trace یک سفارش ناموفق می‌رساند و شناسه trace کمک می‌کند لاگ همان درخواست را پیدا کنید. بهتر است نام سرویس، محیط و نسخه انتشار روشن باشند تا داده آزمایش با تولید مخلوط نشود. در نمونه آموزشی از exporter کنسول استفاده می‌کنیم؛ این خروجی داشبورد یا سامانه نگهداری trace در تولید نیست.

چه داده‌ای را ثبت کنیم؟

از مسیر کسب‌وکاری مهم شروع کنید: دریافت درخواست، خواندن موجودی و ثبت سفارش. نام span باید ثابت و قابل مقایسه باشد، مثل inventory.lookup، نه عنوانی که شناسه هر مشتری را در خودش دارد. جزئیات کم‌تعداد و غیرحساس را در attribute بگذارید. شماره تماس، توکن، متن کامل سند و بدنه پرداخت نباید بدون بررسی وارد trace شوند. پیشنهاد تحریریه این است که یک فهرست مجاز برای attribute بسازید و هر فیلد تازه را پیش از جمع‌آوری از نظر کاربرد و حساسیت بررسی کنید.

در سرویس‌های چندمرحله‌ای، context باید همراه درخواست منتقل شود؛ وگرنه چند trace مستقل می‌بینید و مسیر واقعی قطع می‌شود. ابزارگذاری خودکار کتابخانه‌ها می‌تواند شروع را ساده کند، اما مرزهای کسب‌وکاری معمولاً به span دستی نیاز دارند. اگر هم خودکار و هم دستی ابزارگذاری می‌کنید، مراقب ثبت دو span برای یک کار باشید. در صف، پردازش ناهم‌زمان و retry مشخص کنید ارتباط میان تلاش‌ها چطور حفظ می‌شود. شکست یک وابستگی باید قابل مشاهده باشد، بدون آنکه داده ورود محرمانه در خروجی ثبت شود.

حجم telemetry را هم مانند هر سرویس دیگری مدیریت کنید. نمونه‌برداری، محدودیت اندازه attribute و سیاست نگهداری را براساس حجم واقعی انتخاب کنید. صرفاً کم کردن داده ممکن است درخواست‌های نادر اما مهم را حذف کند. در معماری تولید، Collector می‌تواند مسیر انتقال، پردازش و حذف فیلدها را متمرکز کند؛ تنظیم آن نیازمند آزمون صف، قطعی شبکه و فشار بار است. برای تیم پشتیبانی مهم است بداند اگر مقصد telemetry قطع شد، سرویس اصلی همچنان چه رفتاری دارد و داده تا چه حد از دست می‌رود.

نمونه کد و روش بررسی

این مثال آموزشی برای فهم مسیر پیاده‌سازی نوشته شده است. نسخه‌ها و پیش‌نیازهای ذکرشده را در محیط آزمایش بررسی کنید؛ نکات زیر مشخص می‌کنند برای استفاده عملی چه چیزهایی باید تکمیل شوند.

Python 3.11+؛ نصب opentelemetry-api و opentelemetry-sdk

# python -m pip install opentelemetry-api opentelemetry-sdk
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace.export import (
    SimpleSpanProcessor, ConsoleSpanExporter,
)

provider = TracerProvider(resource=Resource.create({
    "service.name": "order-demo",
    "deployment.environment.name": "test",
}))
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("liyan.order-demo")

with tracer.start_as_current_span("order.prepare"):
    with tracer.start_as_current_span("inventory.lookup") as span:
        span.set_attribute("inventory.available", True)
provider.shutdown()

دو span با trace_id مشترک و رابطه parent/child باید در کنسول دیده شوند. اجرای shutdown خروجی را کامل می‌کند. این نمونه شبکه یا دیتابیس واقعی ندارد. در تولید معمولاً BatchSpanProcessor و exporter متناسب با مقصد جایگزین می‌شوند؛ timeout، sampling و حذف اطلاعات حساس را قبل از اتصال به محیط واقعی تنظیم و آزمایش کنید.

پایلوتی که به رفع خطا کمک کند

پایلوت را با یک درخواست سالم و یک خطای عمدی در محیط آزمایش بسنجید. باید بتوانید span کند را پیدا کنید، نسخه سرویس را ببینید و از روی trace به لاگ مرتبط برسید. سپس زمان پاسخ و مصرف منابع را قبل و بعد از ابزارگذاری مقایسه کنید. معیار پذیرش را عملی بنویسید: «تیم می‌تواند علت تأخیر یک سفارش را از مسیر ثبت‌شده پیدا کند.» داشتن داشبورد شلوغ به‌تنهایی این معیار را تأمین نمی‌کند؛ مالکیت هشدار، دسترسی به داده و روش استفاده در رخداد نیز باید روشن باشند.