پرش به مطلب اصلی

نصب SDK پایتون (Django / Flask / FastAPI)

سنتریخواندن 4 دقیقه

اکنون که با Sentry آشنا هستید، می‌توانید برنامه Python خود را برای ارسال گزارش‌ها به آن آماده کنید. این فرایند نصب حدود پنج دقیقه زمان می‌برد و باعث می‌شود خطاهای ثبت‌نشده محیط عملیاتی، همراه با رد پشته (stack trace)، درخواست منجر به خطا و اطلاعات کاربر، در داشبورد Sentry ثبت شوند.

کیت توسعه نرم‌افزار (SDK) Python یک بسته واحد است که افزونه‌های اختیاری چارچوب‌ها را نیز ارائه می‌کند. این SDK چارچوب وب، کوئری‌های پایگاه داده و پردازشگرهای پس‌زمینه را به‌طور خودکار ابزارگذاری می‌کند؛ بنابراین علاوه بر خطاها، ردیابی‌ها نیز ثبت می‌شوند.

قابلیت‌های قابل‌استفاده​

  • استثناهای مدیریت‌نشده به‌طور خودکار و همراه با رد پشته کامل و متغیرهای محلی هر فریم ثبت می‌شوند.
  • ردیابی عملکرد (performance trace) برای درخواست‌های HTTP، کوئری‌های پایگاه داده، فراخوانی‌های Redis و موارد دیگر ثبت می‌شود. پس از مقداردهی اولیه SDK، به کد اضافه‌ای نیاز نیست.
  • خرده‌مسیرها (breadcrumbs) رویدادهای پیش از هر خطا را نشان می‌دهند؛ از جمله مسیر درخواست، کوئری اجراشده و آخرین خط گزارش پیش از بروز خطا.
  • سلامت انتشار (release health) نرخ نشست‌های بدون خطا را برای هر نسخه انتشار نشان می‌دهد.

نصب​

# Django
pip install "sentry-sdk[django]"

# Flask
pip install "sentry-sdk[flask]"

# FastAPI (also covers Starlette / general ASGI)
pip install "sentry-sdk[fastapi]"

# Plain Python / anything else
pip install sentry-sdk

افزونه هر چارچوب، یکپارچه‌سازی مربوط به آن و وابستگی‌های موردنیاز را نصب می‌کند. SDK هنگام مقداردهی اولیه، Django، Flask و FastAPI را به‌طور خودکار تشخیص می‌دهد و هوک‌های مناسب را اعمال می‌کند.

مقداردهی اولیه​

کد مقداردهی اولیه را در نقطه شروع برنامه قرار دهید؛ برای Django در فایلی کنار manage.py، برای Flask در تابع سازنده برنامه و برای FastAPI در main.py. نکته اصلی این است که مقداردهی اولیه باید پیش از اجرای بخش‌های دیگر انجام شود تا هیچ درخواستی پیش از فعال‌شدن Sentry پردازش نشود.

Django​

# settings.py  (or a sentry.py you import from settings)
import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    # Set to 1.0 to capture 100% of transactions for performance.
    # Lower it in production to control volume/cost.
    traces_sample_rate=1.0,
    # Send user info (email, ip) with events. Off by default for privacy.
    send_default_pii=True,
    # Tag every event with the release so you can track regressions.
    release="my-app@1.4.2",
    environment="production",
)

برای تکمیل نصب در Django همین پیکربندی کافی است. پس از آن، خطاها و بازه‌های درخواست (request spans) ثبت می‌شوند. یکپارچه‌سازی Django همچنین django.template، django.db و میان‌افزارها را به‌طور خودکار پوشش می‌دهد.

Flask​

from flask import Flask
import sentry_sdk
from sentry_sdk.integrations.flask import FlaskIntegration

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    integrations=[FlaskIntegration()],
    traces_sample_rate=1.0,
)

app = Flask(__name__)

FastAPI​

from fastapi import FastAPI
import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    traces_sample_rate=1.0,
    send_default_pii=True,
)

app = FastAPI()

FastAPI بر پایه Starlette و ASGI اجرا می‌شود. SDK لایه ASGI را ابزارگذاری می‌کند؛ بنابراین مسیرها و وظایف پس‌زمینه به‌طور خودکار ردیابی می‌شوند.

ثبت دستی خطاها​

SDK استثناهای مدیریت‌نشده را به‌طور خودکار ثبت می‌کند. اگر استثنایی را در برنامه مدیریت می‌کنید و می‌خواهید آن را نیز ثبت کنید، از روش زیر استفاده کنید:

import sentry_sdk

try:
    risky_thing()
except Exception as e:
    # Records the exception. Re-raise if you still want it to propagate.
    sentry_sdk.capture_exception(e)
    raise

برای ثبت پیام‌ها به‌جای استثناها:

sentry_sdk.capture_message("Payment queue backed up", level="warning")

کاربردها​

  • بررسی خطا در Sentry همراه با رد پشته، متغیرهای محلی و درخواست منجر به خطا، بدون نیاز به بازتولید آن.
  • بررسی رد یک نقطه پایانی کند؛ نمودار آبشاری، بازه HTTP، کوئری‌های N+1 پایگاه داده و زمان اجرای هرکدام را نشان می‌دهد.
  • برچسب‌گذاری رویدادها متناسب با دامنه کسب‌وکار؛ برای اطلاعات بیشتر به برچسب‌ها و اثرانگشت‌گذاری برای دامنه کسب‌وکار مراجعه کنید.
  • افزودن بازه‌های سفارشی برای منطق‌های مهم کسب‌وکار؛ برای اطلاعات بیشتر به بازه‌های سفارشی برای کسب‌وکار مراجعه کنید.

بررسی نصب​

برای اطمینان از ثبت رویدادها، به‌صورت عمدی خطایی ایجاد کنید:

# any route
def boom():
    1 / 0

مسیر مربوط را فراخوانی کنید و سپس صفحه Issues پروژه را در Sentry بررسی کنید. رویداد ZeroDivisionError باید پس از چند ثانیه نمایش داده شود. اگر رویداد ثبت نشد، به عیب‌یابی نمایش‌داده‌نشدن رویدادها مراجعه کنید.

راهنمایی‌های مرتبط

سنتریSDK سنتریپایتونجنگوفلأسکFastAPI
این راهنمایی کاربردی بود؟

با ثبت بازخوردتان در بهبود کیفیت مستندات مشارکت داشته باشید.