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

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

راه‌اندازی

پایتون

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

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

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

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

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

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

PHP و لاراول

کانال لاگ sentry را اضافه کنید (نگاه کنید به PHP و لاراول) و مثل همیشه از Log::info(...) استفاده کنید.

HTTP خام

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

{"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

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 لاگ‌ها را جست‌وجو کنند.

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

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

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

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

عیب‌یابی

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