# رصد خطا (Issues)

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

خطاها هستهٔ ارورا هستند: هر استثنایی که برنامه‌تان پرتاب می‌کند نرمال‌سازی، اثرانگشت‌گیری و
گروه‌بندی می‌شود؛ پس هزار بار تکرار یک باگ، یک ردیف است که می‌شود رویش کاری کرد.

## راه‌اندازی

چیزی بیشتر از مقداردهی اولیهٔ SDK لازم نیست — استثناهای مدیریت‌نشده خودکار ثبت می‌شوند:

```python
import sentry_sdk
sentry_sdk.init(dsn="https://<public_key>@<host>/<project_id>", environment="production")
```

برای پلتفرم خودتان [راه‌اندازی SDK](/platforms/overview) را ببینید. برای ثبت خطایی که خودتان
گرفته‌اید:

```python
try:
    charge(order)
except PaymentError as exc:
    sentry_sdk.capture_exception(exc)
```

## گروه‌بندی چطور کار می‌کند

1. رویداد **نرمال‌سازی** می‌شود (فریم‌های ردپا، مقادیر استثنا، درخواست، زمینه‌ها و برچسب‌ها).
2. اگر جاوااسکریپت مینیفای‌شده باشد و [سورس‌مپ](/products/source-maps) بارگذاری کرده باشید،
   **اول نمادگشایی می‌شود** تا گروه‌بندی روی فریم‌های اصلی و پایدار انجام شود.
3. یک **اثر انگشت** از نوع استثنا به‌علاوهٔ فریم‌های معنادار ردپا محاسبه می‌شود.
4. رویدادهای هم‌اثرانگشت در یک **خطا** جمع می‌شوند که تعداد رخداد، کاربران یکتا، اولین/آخرین
   مشاهده و وضعیت را نگه می‌دارد.

رسیدن رویداد تازه برای خطایی که حل کرده‌اید، آن را **بازگشتی** می‌کند: دوباره باز می‌شود و
رویداد هشدار `issue.regressed` را فعال می‌کند.

## فهرست خطاها

**خطاها** در نوار کناری، خطاهای باز پروژهٔ انتخاب‌شده را به ترتیب آخرین فعالیت نشان می‌دهد؛ هر
کدام با یک نمودار کوچک ۲۴ ساعته.

- **جست‌وجو** — متن آزاد روی عنوان و پیام، با تطبیق ابتدای واژه: `time` واژهٔ `timeout` را هم
  پیدا می‌کند.
- **فیلترها** — وضعیت (باز، حل‌شده، نادیده‌گرفته)، محیط، سطح، بازهٔ زمانی و **کاربر**: با انتخاب
  یک کاربر، فهرست به خطاهایی که او دیده محدود می‌شود. همین فیلتر در درخواست‌ها، جاب‌ها و لاگ‌ها هم
  هست و صفحهٔ **کاربران** میان‌برهای مستقیم به همهٔ آن‌ها دارد.
- **مرتب‌سازی** — آخرین رخداد، اولین رخداد، **تعداد رخداد** (همان شمارنده‌ای که در هر سطر می‌بینید)
  یا تعداد کاربران متأثر، تا پرتأثیرترین خطاها اول بیایند.
- **محدودشدن به محیط** — فهرست فقط محیط انتخاب‌شده را نشان می‌دهد و صفحهٔ خطا بقیهٔ محیط‌های
  متأثر را فهرست می‌کند.
- **کارهای گروهی** — چند سطر را انتخاب کنید و یک‌جا حل، نادیده، بازگشایی، بایگانی، تغییر اولویت
  یا واگذار کنید.
- **روندها** — `GET /projects/{id}/issues/trends?period=24h|30d` پشت نمودارهای کوچک است.

## صفحهٔ خطا

- **ردپای فراخوانی** با رنگ‌آمیزی نحوی، برجسته‌کردن فریم مظنون و نمایش کد اطراف برای فریم‌های
  نمادگشایی‌شده.
- **نمودار روند** — ۲۴ ساعته و ۳۰ روزه.
- **بردکرامب‌ها** — از جمله عبارت‌های SQL همراه با مقادیرشان.
- **درخواست** — متد، آدرس، هدرها و ارجاع‌دهنده.
- **زمینه‌ها و برچسب‌ها** — رانتایم، سیستم‌عامل، مرورگر، نسخه، محیط و برچسب‌های خودتان.
- **دادهٔ پیوسته** — [بازپخش نشست](/products/session-replay)،
  [بازخورد کاربر](/products/user-feedback) و ترِیسی که این رویداد به آن تعلق دارد.

### کارها

| کار | اثر |
| --- | --- |
| حل‌شده | خطا را می‌بندد. رویداد بعدی آن را بازگشتی می‌کند. |
| نادیده گرفتن | هشدار را قطع می‌کند، بدون ادعای اینکه رفع شده است. |
| بایگانی | از فهرست پیش‌فرض پنهانش می‌کند. |
| نشان‌گذاری | ستارهٔ شخصی هر کاربر. |
| واگذاری | سپردن به یکی از اعضای سازمان. |
| کپی پیوند اشتراک | لینک مستقیم به همین خطا. |
| ساخت/پیوند تیکت گیت‌لب | [یکپارچه‌سازی‌ها](/products/integrations) را ببینید. |
| رفع خودکار با هوش مصنوعی | نوشتن وصله و باز کردن مرج‌ریکوئست — [رفع خودکار](/products/ai-autofix). |

## کم‌کردن نویز

- **`before_send`** در SDK — حذف یا پاک‌سازی رویدادها در سمت کلاینت.
- **`ignore_errors` / `denyUrls`** — رد کردن استثناهای بی‌ضرر شناخته‌شده و اسکریپت‌های شخص ثالث.
- **نرخ نمونه‌برداری پروژه** — ذخیرهٔ فقط کسری از رویدادهای رسیده (در تنظیمات پروژه).
- به‌جای حل‌کردن، خطای نویزی‌ای را که فعلاً نمی‌توانید حذف کنید **نادیده** بگیرید.
- **بستن خودکار خطاهای راکد** — در تنظیمات پروژه، خطاها پس از ۷، ۱۴ یا ۳۰ روز بدون رویداد جدید
  خودکار حل‌شده می‌شوند. رویداد بعدی دوباره بازشان می‌کند، مثل حل‌کردن دستی.

## API

```text
GET  /api/v1/projects/{project_id}/issues?q=&status=&environment=&user=&ordering=-times_seen
GET  /api/v1/projects/{project_id}/issues/{issue_id}
GET  /api/v1/projects/{project_id}/issues/environments
GET  /api/v1/projects/{project_id}/issues/users?q=&stats_period=7d
GET  /api/v1/projects/{project_id}/issues/trends?period=24h|30d
POST /api/v1/projects/{project_id}/issues/bulk
GET  /api/v1/projects/{project_id}/issues/{issue_id}/series
POST /api/v1/projects/{project_id}/issues/{issue_id}/resolve|ignore|archive|bookmark|assign
GET  /api/v1/projects/{project_id}/events/{event_id}
```

مقدار `user` می‌تواند `id:42`، `email:…`، `username:…`، `ip:…` یا مقداری ساده باشد که با هرکدام
مطابقت کند.

ایجنت‌های هوش مصنوعی همین کارها را از راه [MCP](/products/mcp) با ابزارهای `list_issues`،
`get_issue` و `update_issue_status` انجام می‌دهند و با `list_performance_issues` /
`get_performance_issue` به ایشوهای کارایی می‌رسند.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| دو باگ در یک خطا جمع شده‌اند | اثر انگشت آن‌ها را یکی کرده — زمینهٔ متمایزکننده اضافه کنید یا در SDK `fingerprint` صریح بگذارید |
| یک باگ در چند خطا پخش شده | فریم‌ها در هر اجرا فرق می‌کنند (مسیرهای حاوی شناسه، باندل مینیفای) — سورس‌مپ بفرستید و مسیرها را یکدست کنید |
| فریم‌های جاوااسکریپت مینیفای‌اند | برای همان `release` دقیقاً [سورس‌مپ](/products/source-maps) بارگذاری کنید |
| رویداد پذیرفته می‌شود ولی ذخیره نمی‌شود | نرخ نمونه‌برداری پروژه کمتر از `1.0` است یا کیف پول از خط اعتبار گذشته |
| اصلاً هیچ داده‌ای نمی‌رسد | SDK به ارورا نمی‌رسد — پاسخ `202` را بررسی کنید و [راه‌اندازی SDK](/platforms/overview) را ببینید |