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

نصب SDK جاوااسکریپت (مرورگر و Node)

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

JavaScript در دو محیط اجرا می‌شود: مرورگر، جایی که کاربر روی گزینه‌ای کلیک می‌کند و باندل برنامه با خطا مواجه می‌شود؛ و سرور، جایی که یک تابع ناهمگام (async) رد می‌شود و ممکن است کسی متوجه آن نشود. SDK جاوااسکریپت Sentry هر دو محیط را پوشش می‌دهد، اما برای هرکدام بسته و رویکرد متفاوتی دارد.

چه امکاناتی در اختیار دارید؟​

  • مرورگر: خطاهای مدیریت‌نشده، ردشدن‌های مدیریت‌نشده Promise، آخرین کلیک کاربر پیش از بروز خطا و ردگیری‌های عملکرد (performance traces) برای بارگذاری صفحه و فراخوانی‌های fetch/XHR.
  • Node: خطاهای سرور همراه با ردپای پشته (stack trace)، اسپن‌های (span) مربوط به HTTP و پایگاه داده و سلامت انتشار (release health) برای بک‌اند.
  • هر دو محیط: مسیر رویدادها تا خطا یا همان بردکرامب‌ها (breadcrumbs)، زمینه درخواست (request context) و امکان پیوست‌کردن اطلاعات کاربر برای شناسایی فردی که خطا برای او رخ داده است.

مرورگر​

نصب​

# framework-agnostic
npm install @sentry/browser

# or a framework-specific package (these re-export @sentry/browser
# and add framework integrations)
npm install @sentry/react
npm install @sentry/vue
npm install @sentry/angular

راه‌اندازی​

Sentry را در اولین فرصت ممکن و پیش از رندرشدن برنامه راه‌اندازی کنید تا کنترل‌کننده‌های سراسری خطا و Promise پیش از سایر بخش‌ها فعال شوند.

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // 1.0 = capture 100% of transactions; lower in production to control cost.
  tracesSampleRate: 1.0,
  // Group events by release so you can track regressions.
  release: "my-app@1.4.2",
  environment: "production",
});

با همین تنظیمات، خطاهای مدیریت‌نشده و ردشدن Promiseها به‌صورت خودکار ثبت می‌شوند و هر بارگذاری صفحه به یک تراکنش عملکرد تبدیل می‌شود.

برای React فقط import را تغییر دهید؛ سایر تنظیمات یکسان هستند:

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracesSampleRate: 1.0,
  // Optional: capture a DOM "replay" recording on errors
  integrations: [Sentry.replayIntegration()],
  replaysSessionSampleRate: 0.0,   // don't record healthy sessions
  replaysOnErrorSampleRate: 1.0,   // record every session that errors
});

بسته @sentry/react همچنین کامپوننت <ErrorBoundary> و قابلیت پروفایل‌گیری با Sentry.reactProfilerIntegration() را در اختیار شما قرار می‌دهد.

Node​

نصب​

npm install @sentry/node

راه‌اندازی​

// src/instrument.js — import this FIRST, before anything else.
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracesSampleRate: 1.0,
  // Node needs a release to attribute errors to a deploy.
  release: "my-service@1.4.2",
  environment: "production",
});

// require your app AFTER init, so the SDK sees every module load
require("./app");

در سرور مهم است که راه‌اندازی Sentry در فایلی انجام شود که پیش از همه فایل‌های دیگر وارد می‌کنید. SDK ماژول‌هایی مانند http، pg و mongodb را اصلاح می‌کند و فقط می‌تواند ماژول‌هایی را ابزارگذاری (instrument) کند که پس از آن بارگذاری شده‌اند.

SDK فریم‌ورک‌های Express، Fastify، Koa، Connect و NestJS را به‌صورت خودکار تشخیص می‌دهد و پردازش درخواست‌ها را ابزارگذاری می‌کند. در نسخه‌های فعلی به فراخوانی میان‌افزار دیگری نیاز نیست. تابع Sentry.setupExpressErrorHandler(app) کنترل‌کننده خطا را در محل مناسب، یعنی پس از سایر میان‌افزارها، اضافه می‌کند.

const Sentry = require("@sentry/node");
const express = require("express");
const app = express();

// ...your routes...

// The error handler must be registered AFTER all other middleware.
Sentry.setupExpressErrorHandler(app);

ثبت دستی رویدادها​

try {
  await flakyApi();
} catch (err) {
  Sentry.captureException(err);
  throw err;
}

// a plain message
Sentry.captureMessage("Cart total was negative", "error");

تنظیم اطلاعات کاربر​

پس از مشخص‌شدن کاربر واردشده، می‌توانید شناسه او را به همه فعالیت‌هایش پیوست کنید:

Sentry.setUser({ id: user.id, email: user.email, username: user.name });
// Sentry attaches this to every subsequent error and trace.

کاربردهای SDK​

  • مشاهده آخرین کلیک دقیق کاربر پیش از بروز خطا در فرانت‌اند، با استفاده از بردکرامب‌ها.
  • بررسی نمودار آبشاری بارگذاری صفحه برای یافتن اسکریپت شخص ثالثی که سرعت صفحه را کاهش داده است.
  • مرتبط‌کردن خطای فرانت‌اند با ردگیری بک‌اند از طریق ارسال هدر sentry-trace از مرورگر به API.
  • افزودن <ErrorBoundary> در React تا خطای یک کامپوننت باعث خالی‌شدن کل صفحه نشود و همچنان در Sentry گزارش شود.

بررسی عملکرد​

setTimeout(() => {
  throw new Error("Sentry browser test");
}, 500);

صفحه Issues را بررسی کنید. اگر رویدادی ثبت نشده است، به صفحه عیب‌یابی: چرا رویدادهای من نمایش داده نمی‌شوند؟ مراجعه کنید.

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

سنتریSDK سنتریجاوااسکریپتNodeReact
این راهنمایی کاربردی بود؟

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