# متریک برنامه

> https://docs.errora.org/products/metrics

متریک‌ها همان عددهایی هستند که برنامه‌تان تولید می‌کند و خطا نیستند: تعداد سفارش، عمق صف،
تأخیر پرداخت، بازدیدکنندهٔ یکتا. ارورا هر دو قالب سیمی‌ای را که SDKهای Sentry می‌فرستند
می‌پذیرد.

## انواع متریک

| نوع | برای چه | توابع تجمیع |
| --- | --- | --- |
| **شمارنده** (`c`) | چیزهایی که رخ می‌دهند | `sum`، `count` |
| **توزیع** (`d`) | مقادیر اندازه‌گیری‌شده (تأخیر، اندازه) | `avg`، `min`، `max`، `p50` تا `p99` |
| **گیج** (`g`) | یک سطح در یک لحظه | `last`، `min`، `max`، `avg` |
| **مجموعه** (`s`) | چیزهای متمایز | `count_unique` |

## راه‌اندازی — با SDK

```javascript
Sentry.metrics.increment("checkout.attempt", 1, { tags: { plan: "pro" } });
Sentry.metrics.distribution("checkout.latency", 421, { unit: "millisecond", tags: { route: "/pay" } });
Sentry.metrics.gauge("queue.depth", 128, { tags: { queue: "ingest" } });
Sentry.metrics.set("visitors", userId);
```

```python
sentry_sdk.metrics.incr("orders.created", 1, tags={"plan": "pro"})
sentry_sdk.metrics.distribution("orders.total", order.total, unit="none")
sentry_sdk.metrics.gauge("queue.depth", depth, tags={"queue": "ingest"})
sentry_sdk.metrics.set("visitors", user_id)
```

SDKها پیش از ارسال **پیش‌تجمیع** می‌کنند: آنچه می‌رسد یک سطل به ازای هر متریک در هر پنجرهٔ
زمانی است، نه یک پیام به ازای هر فراخوانی. توزیع‌ها نمونه‌ای از مقادیر خام را نگه می‌دارند تا
صدک‌ها قابل پاسخ بمانند، و مجموعه‌ها اعضای متمایز را به‌صورت اجتماع میان سطل‌ها می‌شمارند نه
جمع ساده.

## راه‌اندازی — قالب‌های خام

**۱. آیتم‌های `trace_metric`** (SDKهای امروزی) — همان ظرف دسته‌ای لاگ:

```json
{"items":[{"timestamp":1767225600.0,"name":"checkout.latency","type":"distribution",
           "value":42.0,"unit":"millisecond","trace_id":"7b3f…",
           "attributes":{"route":{"value":"/pay","type":"string"}}}]}
```

**۲. متن statsd** (پروتکل اصلی)، خط‌به‌خط:

```text
<name>[@<unit>]:<v1>[:<v2>…]|<type>|#<tag>:<value>,…|T<unix_seconds>

endpoint.response_time@millisecond:57:92|d|#route:/pay,method:POST|T1615889449
button_click@none:1|c|#browser:firefox
```

یک **گیج statsd با دقیقاً پنج مقدار** شکل پیش‌تجمیع‌شدهٔ `last:min:max:sum:count` است، نه پنج
اندازه‌گیری جدا.

محدودیت هر دسته: ۱۰۰۰ آیتم، ۳۰ برچسب برای هر متریک، ۲۰۰ نویسه برای هر نام یا مقدار برچسب.

## کوئری‌گرفتن

صفحهٔ **متریک‌ها** نام متریک‌هایی را که پروژه فرستاده فهرست می‌کند. یکی را انتخاب کنید و
بردارید:

- یک **تابع تجمیع** — `sum`، `avg`، `min`، `max`، `p50`، `p75`، `p90`، `p95`، `p99`،
  `count_unique`
- یک **برچسب برای تفکیک**، تا سری شکسته شود
- یک **محیط** و یک **بازهٔ زمانی**

مقدار `avg` همیشه `sum / count` واقعی روی کل بازه است، نه میانگین میانگین سطل‌ها.

```text
GET /api/v1/projects/{project_id}/metrics?q=&stats_period=24h
GET /api/v1/projects/{project_id}/metrics/series?name=&op=&group_by=&environment=&stats_period=24h
GET /api/v1/projects/{project_id}/metrics/summary?name=&environment=&stats_period=24h
GET /api/v1/projects/{project_id}/metrics/tags?name=&stats_period=24h
```

## نام‌گذاری‌ای که به درد بخورد

- `domain.thing.measure` — مثل `checkout.latency`، `queue.depth`، `sms.sent`.
- مقادیر متغیر را در **برچسب** بگذارید، هرگز در نام. `orders.created` با برچسب `plan:pro`
  بهتر از `orders.created.pro` است.
- کاردینالیتی برچسب‌ها را پایین نگه دارید: `route` بله، `user_id` نه. هر ترکیب متمایز برچسب،
  سطل جداگانهٔ خودش است و هزینه به ازای سطل متریک حساب می‌شود.

## داشبورد

متریک‌ها یکی از مجموعه‌داده‌های [داشبورد](/products/dashboards) هستند — سری متریک را کنار
تعداد خطاها و تأخیر تراکنش‌ها روی یک صفحه بگذارید.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| نام متریک در فهرست نیست | در بازهٔ انتخاب‌شده چیزی نرسیده — بازه را بازتر کنید |
| صدک‌ها تقریبی به نظر می‌رسند | هر سطل نمونهٔ کران‌دار (۱۰۰ مقدار) نگه می‌دارد؛ این عمدی است |
| `count_unique` کمتر از انتظار است | اعضای مجموعه هش می‌شوند و در هر سطل کران دارند (۵۰۰) |
| یک برچسب نیست | از سقف ۳۰ برچسب یا ۲۰۰ نویسه گذشته و حذف شده |
| هزینه بالا می‌رود | کاردینالیتی برچسب — یک برچسب پرتنوع تعداد سطل‌هایتان را چند برابر می‌کند |