حالا که با سنتری و مفاهیم اصلی آن آشنا شده‌اید، می‌توانید اولین پروژه خود را بسازید، اپلیکیشن را به آن متصل کنید و یک خطای آزمایشی بفرستید.

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

مراحل راه‌اندازی

برای اتصال اپلیکیشن به سنتری باید این چهار مرحله را انجام دهید:

1. یک پروژه بسازید. هنگام ساخت پروژه، پلتفرمی را انتخاب کنید که با محل اجرای کد شما مطابقت دارد؛ برای مثال Node.js یا Python برای Backend و JavaScript برای مرورگر.

2. DSN پروژه را دریافت کنید. نام منبع داده (Data Source Name یا DSN) آدرسی است که به SDK می‌گوید رخدادها را برای کدام پروژه در سنتری ارسال کند.

3. SDK را نصب و راه‌اندازی کنید. کیت توسعه نرم‌افزار سنتری (Sentry SDK) را متناسب با زبان یا فریم‌ورک اپلیکیشن نصب و با DSN پروژه پیکربندی کنید.

4. یک رخداد آزمایشی بفرستید. پس از راه‌اندازی SDK، یک خطای عمدی ایجاد کنید و ثبت‌شدن آن را در بخش Issues بررسی کنید.

پس از انجام این مراحل، پروژه شما آماده دریافت خطاها و اطلاعات عملکردی اپلیکیشن است.

ساخت پروژه

وارد سازمان خود در سنتری شوید و از بخش Projects گزینه Create Project را انتخاب کنید.

در صفحه ساخت پروژه:

1. پلتفرم اپلیکیشن را انتخاب کنید.
2. نامی برای پروژه بنویسید.
3. تیم مرتبط با پروژه را مشخص کنید.
4. نحوه دریافت هشدارها را انتخاب کنید.
5. روی Create Project کلیک کنید.

بهتر است نام پروژه مشخص کند اطلاعات مربوط به کدام اپلیکیشن یا سرویس است؛ برای مثال payment-api یا store-frontend.

برای اپلیکیشن‌هایی که از چند سرویس مستقل تشکیل شده‌اند، می‌توانید برای هر سرویس پروژه جداگانه‌ای بسازید. این کار جست‌وجو، فیلترکردن و مدیریت رخدادها را ساده‌تر می‌کند.

دریافت DSN

پس از ساخت پروژه، سنتری DSN مربوط به آن را نمایش می‌دهد. برای پروژه‌های موجود نیز می‌توانید DSN را از بخش Settings، صفحه تنظیمات پروژه و قسمت Client Keys دریافت کنید.

ساختار DSN به‌صورت زیر است:

https://PUBLIC_KEY@sentry.hamravesh.com/PROJECT_ID

مقدار PUBLIC_KEY و PROJECT_ID برای هر پروژه متفاوت است. اگر DSN اشتباهی در تنظیمات SDK قرار دهید، رخدادها به پروژه موردنظر شما نمی‌رسند.

راه‌اندازی SDK

SDK باید در مراحل ابتدایی اجرای اپلیکیشن راه‌اندازی شود. اگر راه‌اندازی آن بعد از شروع پردازش درخواست‌ها یا اجرای Workerها انجام شود، ممکن است بعضی خطاها ثبت نشوند.

نمونه راه‌اندازی در Python:

import sentry_sdk

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

نمونه راه‌اندازی در JavaScript:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://PUBLIC_KEY@sentry.hamravesh.com/PROJECT_ID",
  tracesSampleRate: 1.0,
});

مقدار tracesSampleRate مشخص می‌کند چه نسبتی از Transactionها برای پایش عملکرد ارسال شوند. مقدار 1.0 به‌معنای ارسال همه Transactionها است و برای آزمایش در محیط توسعه یا محیط آزمایشی کم‌ترافیک مناسب است.

در محیط عملیاتی، این مقدار را متناسب با حجم ترافیک و محدودیت پلن تنظیم کنید. اگر در حال حاضر فقط به ردیابی خطا نیاز دارید، می‌توانید تنظیمات پایش عملکرد را بعداً تکمیل کنید.

ارسال خطای آزمایشی

برای اطمینان از صحت اتصال، منتظر وقوع یک خطای واقعی نمانید. پس از راه‌اندازی SDK، یک خطای آزمایشی ایجاد و آن را برای سنتری ارسال کنید.

نمونه در Python:

try:
    result = 1 / 0
except Exception as error:
    sentry_sdk.capture_exception(error)

نمونه در JavaScript:

try {
  throw new Error("Sentry test error");
} catch (error) {
  Sentry.captureException(error);
}

کد آزمایشی را یک بار اجرا کنید. سپس وارد پروژه شوید و بخش Issues را باز کنید. پس از مدت کوتاهی باید Issue جدیدی ببینید که خطای آزمایشی شما را نشان می‌دهد.

صفحه Issue می‌تواند شامل پیام خطا، پشته فراخوانی (Stack Trace)، زمان وقوع و اطلاعات محیط اجرا باشد. نمایش اطلاعاتی مانند کاربر، Release و Breadcrumbs به تنظیمات SDK و داده‌هایی بستگی دارد که اپلیکیشن ارسال می‌کند.

پس از پایان آزمایش، کد ایجاد خطای عمدی را حذف کنید.

اگر خطا ثبت نشد

اگر رخداد آزمایشی را در پروژه نمی‌بینید، این موارد را بررسی کنید:

1. مطمئن شوید DSN متعلق به همان پروژه است.
2. بررسی کنید SDK پیش از شروع اجرای اصلی برنامه راه‌اندازی شده باشد.
3. لاگ‌های اپلیکیشن را برای پیداکردن خطای ارتباط با سنتری ببینید.
4. دسترسی شبکه اپلیکیشن به دامنه سنتری را بررسی کنید.
5. در بخش Stats وضعیت رخدادهای دریافت‌شده و ردشده را ببینید.
6. اگر پاسخ 429 دریافت می‌کنید، ممکن است Quota تمام شده یا Spike Protection فعال شده باشد.
7. اگر در JavaScript محل خطا به‌درستی نمایش داده نمی‌شود، Source Mapها را هنگام Build تولید و برای سنتری بارگذاری کنید.

اگر فقط یک پروژه رخداد دریافت نمی‌کند و سایر پروژه‌ها مشکلی ندارند، ابتدا DSN و تنظیمات SDK همان پروژه را بررسی کنید.

نتیجه راه‌اندازی

راه‌اندازی زمانی کامل است که خطای آزمایشی در بخش Issues نمایش داده شود و بتوانید جزئیات آن را باز کنید.

از این مرحله به بعد، SDK رخدادهای اپلیکیشن را بر اساس تنظیمات شما جمع‌آوری می‌کند و برای پروژه می‌فرستد. سنتری نیز خطاهای مشابه را در قالب Issue گروه‌بندی می‌کند تا بتوانید آن‌ها را بررسی، اولویت‌بندی و مدیریت کنید.