متریک‌های اپلیکیشن (Application Metrics) اعدادی هستند که کد شما به‌صورت عمدی به سنتری گزارش می‌کند؛ مانند checkout.failed، queue.depth و cart.amount_usd. خطاها و traceها زمانی ثبت می‌شوند که مشکلی پیش بیاید یا چیزی کند باشد؛ اما متریک‌ها ثبت می‌شوند چون شما تصمیم گرفته‌اید آن عدد ارزش پیگیری دارد.

هر متریک دارای trace_id درخواستی است که در آن ثبت شده است؛ بنابراین می‌توان یک متریک را در کنار traceها، لاگ‌ها و خطاهای همان درخواست مشاهده کرد.

متریک، خطا و trace

یک خطا یک شکست واحد را ثبت می‌کند. یک trace یک درخواست واحد را ثبت می‌کند. اما یک متریک مقداری را در طول زمان و در میان درخواست‌های متعدد ثبت می‌کند:

• نرخ checkoutهای ناموفق در یک ساعت گذشته. هیچ رخداد خطای منفردی نرخی را نشان نمی‌دهد؛ این نرخ فقط در میان رخدادهای متعدد وجود دارد.
• عمق صف jobها. هیچ چیزی شکست نخورده و هیچ exceptionای پرتاب نشده؛ صف صرفاً در حال بزرگ‌تر شدن است.
• توزیع مقادیر سبد خرید قبل و بعد از یک تغییر قیمت‌گذاری.

وقتی پرسش شما درباره مقداری در میان درخواست‌های متعدد است، از متریک استفاده کنید. وقتی پرسش درباره یک درخواست مشخص است، از خطا یا trace استفاده کنید.

سه نوع متریک

نوعی که استفاده می‌کنید به ماهیت عددی که گزارش می‌کنید بستگی دارد.

Counter — مقداری تجمعی. هر بار که اتفاقی رخ می‌دهد آن را افزایش می‌دهید و سنتری می‌تواند مجموع یا نرخ بر ثانیه یا دقیقه را نشان دهد. برای مثال email.sent، checkout.failed و cache.miss.

Gauge — مقدار فعلی. هر خواندن جدید جایگزین مقدار قبلی می‌شود و سنتری می‌تواند کمینه، بیشینه و میانگین را در یک بازه زمانی نشان دهد. برای مثال queue.depth، pool.in_use و active_connections.

Distribution — مجموعه‌ای از مقادیر که به‌صورت آماری تحلیل می‌شوند: صدک‌ها، میانگین، مجموع و تعداد. برای مثال cart.amount_usd، query.duration_ms و image.size_bytes.

Sentry.metrics.count("checkout.failed", 1, {
  attributes: { user_tier: "premium", failure_reason: "payment_declined" },
});

Sentry.metrics.gauge("queue.depth", await queue.size(), {
  attributes: { queue_name: "notifications" },
});

Sentry.metrics.distribution("api.latency", responseTimeMs, {
  unit: "millisecond",
  attributes: { endpoint: "/api/orders", method: "POST" },
});

نحوه ارسال متریک (Python)

برخلاف spanها و خطاها، متریک‌ها به‌صورت خودکار جمع‌آوری نمی‌شوند. SDK فقط به این دلیل که یک کوئری دیتابیس اجرا شده یا یک درخواست HTTP انجام شده است، هیچ متریکی ارسال نمی‌کند. متریک تنها در جایی ثبت می‌شود که شما آگاهانه API متریک را در کد خود فراخوانی کنید. spanها و خطاها به‌صورت خودکار ابزارگذاری می‌شوند (Auto-Instrumentation)؛ اما برای ثبت یک متریک، هر بار که قرار است مقداری ثبت شود، به یک فراخوانی صریح نیاز است.

SDK را همان‌طور که همیشه انجام می‌دهید راه‌اندازی (Initialize) کنید. متریک‌ها از طریق sentry_sdk.metrics در دسترس‌اند و به نسخه 2.44.0 یا جدیدتر Sentry Python SDK نیاز دارند.

import sentry_sdk

sentry_sdk.init(
    dsn="https://PUBLIC_KEY@sentry.hamravesh.com/PROJECT_ID",
)

# Counter — increment by one for every database query that runs.
sentry_sdk.metrics.count(
    "db.queries.total",
    1,
    attributes={
        "operation": "select",
        "table": "orders",
    },
)

هر فراخوانی sentry_sdk.metrics.count یک رخداد متریک به سنتری ارسال می‌کند. آن را هر بار که چیزی که اندازه‌گیری می‌کنید رخ می‌دهد فراخوانی کنید؛ در این مثال، یک بار برای هر کوئری دیتابیس. به مرور زمان سنتری این رخدادها را در قالب یک نرخ (بر ثانیه یا دقیقه) و یک مجموع تجمیع می‌کند که می‌توانید برای آن نمودار رسم کنید و هشدار (Alert) تنظیم کنید.

تصویر زیر متریک db.queries.total را در رابط کاربری سنتری پس از چند فراخوانی نشان می‌دهد.

ویژگی‌ها (Attributes)

هر فراخوانی متریک ویژگی‌هایی (Attributes) می‌پذیرد: تگ‌های کلید-مقدار مانند region، plan_type یا endpoint. این ویژگی‌ها را در محل فراخوانی تعیین می‌کنید و پس از آن می‌توانید متریک را با هر ترکیبی از آن‌ها تفکیک کنید، بدون آنکه نیاز به تغییر دوباره کد باشد.

مقادیر ویژگی‌ها را به مجموعه‌ای محدود و شناخته‌شده محدود نگه دارید. شناسه‌هایی مانند user ID یا request ID برای هر رخداد یک سری داده جداگانه تولید می‌کنند که ذخیره‌سازی آن پرهزینه است و تجمیع مفیدی نیز ندارد.

ارتباط با traceها

هر رخداد متریک با trace_id و span_id کاری که در آن لحظه در جریان است ثبت می‌شود. وقتی یک متریک تغییر می‌کند، می‌توانید یکی از traceهای پشت آن را باز کنید و spanها، لاگ‌ها و خطاهای آن درخواست را ببینید.

نمونه‌برداری (Sampling)

متریک‌های اپلیکیشن به‌صورت پیش‌فرض بدون نمونه‌برداری ارسال می‌شوند، در حالی که traceها معمولاً با نرخ بسیار پایین‌تری نمونه‌برداری می‌شوند. بنابراین ممکن است یک متریک تغییر کند بدون آنکه trace متناظری در داده‌های نمونه‌برداری‌شده شما وجود داشته باشد.

این رفتار عمدی است: رخداد متریک یک عدد و چند ویژگی است و نیازی به نمونه‌برداری spanها ندارد. اگر نمونه‌ای از متریک trace متصل‌شده نداشت، از ویژگی‌های همان متریک برای یافتن trace مشابه استفاده کنید.

کاربردها

• پیگیری مقداری که هیچ خطا یا trace منفردی ثبت نمی‌کند: نرخ شکست، عمق صف و توزیع درآمد.
• ایجاد هشدار (Alert) روی یک متریک؛ برای مثال وقتی checkout.failed در هر دقیقه از آستانه‌ای عبور کند.
• افزودن متریک به داشبورد تا کل تیم آن را ببیند.