# لاگ ساخت‌یافته

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

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

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

### پایتون

```python
sentry_sdk.init(dsn="…", enable_logs=True)
```

لاگ‌های کتابخانهٔ استاندارد خودکار ارسال می‌شوند و فیلدهای `extra` به ویژگی‌های نوع‌دار تبدیل
می‌شوند:

```python
logger.warning("retrying payment", extra={"order_id": order.id, "attempt": 3})
```

### جاوااسکریپت / Node.js

```javascript
Sentry.init({ dsn: "…", _experiments: { enableLogs: true } });

const { logger } = Sentry;
logger.info("payment captured", { orderId, amount });
logger.error("gateway rejected", { orderId, code });
```

### PHP و لاراول

کانال لاگ `sentry` را اضافه کنید (نگاه کنید به [PHP و لاراول](/platforms/php-laravel#لاگ))
و مثل همیشه از `Log::info(...)` استفاده کنید.

### HTTP خام

لاگ‌ها در قالب آیتم پاکت `log` می‌آیند — یک ظرف دسته‌ای از آیتم‌های نوع‌دار:

```json
{"items":[{"timestamp":1767225600.0,"level":"info","body":"backup finished",
           "trace_id":"7b3f…","attributes":{"host":{"value":"db-1","type":"string"},
                                            "bytes":{"value":10485760,"type":"integer"}}}]}
```

## سطح‌ها

`trace`، `debug`، `info`، `warn`، `error`، `fatal`. سطح‌ها در پنل به‌صورت وجه (facet) نمایش
داده می‌شوند تا پیش از فیلترکردن، شکل کلی حجم لاگ‌هایتان را ببینید.

## جست‌وجو

صفحهٔ **لاگ‌ها** این امکانات را می‌دهد:

- **جست‌وجوی تمام‌متن** روی بدنهٔ لاگ، با تطبیق ابتدای واژه.
- **وجه‌های سطح** همراه با شمارش.
- **فیلتر ویژگی‌ها** — هر کلید ویژگی‌ای که SDK فرستاده از
  `GET /projects/{id}/logs/attribute-keys` پیشنهاد می‌شود.
- انتخاب **بازهٔ زمانی**.
- **فیلتر کاربر** — محدودکردن جریان لاگ به یک کاربر (تطبیق با ویژگی‌های `user.id`، `user.email`
  و `user.name`)؛ همان فیلتری که خطاها، درخواست‌ها و جاب‌ها هم دارند.
- **پیوند به ترِیس** — خط لاگی که `trace_id` دارد به تراکنش سازندهٔ خود وصل می‌شود و برعکس.

## API

```text
GET /api/v1/projects/{project_id}/logs?q=&level=&environment=&user=&stats_period=24h
GET /api/v1/projects/{project_id}/logs/attribute-keys
GET /api/v1/projects/{project_id}/logs/{log_id}
```

ایجنت‌های هوش مصنوعی می‌توانند با ابزار `search_logs` از راه [MCP](/products/mcp) لاگ‌ها را
جست‌وجو کنند.

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

لاگ‌ها همراه خطاها زیر سرویس **خطا/لاگ** محاسبه می‌شوند — نگاه کنید به
[کیف پول](/billing/wallet). حذفشان هم با همان کار شبانهٔ نگه‌داری رویدادها انجام می‌شود؛ بازهٔ
نگه‌داری هر سازمان در **تنظیمات ← نگه‌داری داده** تعیین می‌شود.

حجم را معقول نگه دارید:

- در تولید از سطح `info` به بالا لاگ بزنید؛ `debug` را برای کار محلی نگه دارید.
- شناسه‌ها را در **ویژگی‌ها** بگذارید، نه در متن پیام — ویژگی‌ها قابل فیلترند و بدنه‌های یکسان
  بهتر گروه می‌شوند.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| هیچ لاگی نمی‌رسد | یکپارچه‌سازی لاگ خاموش است (`enable_logs` / `enableLogs`) یا نسخهٔ SDK قدیمی‌تر از این قابلیت است |
| لاگ هست ولی پیوند ترِیس ندارد | لاگ بیرون از اسپن فعال ثبت شده — کار را داخل یک تراکنش بگذارید |
| ویژگی‌ها نیستند | به‌جای فیلد ساخت‌یافته، رشتهٔ قالب‌بندی‌شده فرستاده‌اید (از `extra=` یا آرگومان دوم استفاده کنید) |
| جست‌وجو چیزی پیدا نمی‌کند | جست‌وجو بر پایهٔ ابتدای واژه است — `time` را بجویید نه `imeou` |