رفتن به مستندات
DIDBAN / SDK DOCUMENTATION

از نصب تا اولین رخدادِ قابل استفاده.

SDK را انتخاب کنید، یک مسیر کوتاه را جلو بروید و خطا را با زمینه‌ای بفرستید که به رفع آن کمک می‌کند.

  1. 1
    نصبافزودن پکیج یا Agent
  2. 2
    اتصالتنظیم کلید، اپ و release
  3. 3
    بررسیارسال یک خطای کنترل‌شده
QUICK START

SDK برنامه را انتخاب کنید

هر تب، پکیج و کد راه‌اندازی مخصوص همان زبان یا runtime را نشان می‌دهد.
01 / نصب
npm install @didban/browser-sdk
02 / راه‌اندازی
import { Didban } from '@didban/browser-sdk';

Didban.init({
  apiKey: "YOUR_API_KEY",
  appName: "checkout-service",
  config: {
    baseUrl: "https://api.getdidban.ir",
    environment: 'production',
    release: 'web@1.0.0',
  },
});
WEB SDK01

JavaScript / TypeScript

ثبت خودکار خطاهای مرورگر، درخواست‌های شبکه و ردپای رفتار کاربر.

@didban/browser-sdk

نصب SDK مرورگر

پکیج را با npm نصب کنید و آن را پیش از رندر اصلی برنامه مقداردهی کنید.

ترمینال
npm install @didban/browser-sdk

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

توکن اپلیکیشن، محیط و شناسهٔ یکتای build را مشخص کنید.

مقدار release باید با مقداری که هنگام آپلود source map می‌فرستید یکسان باشد.

ورودی برنامه
import Didban from '@didban/browser-sdk';

Didban.init({
  apiKey: 'YOUR_API_KEY',
  appName: 'storefront-web',
  config: {
    baseUrl: 'https://api.getdidban.ir',
    environment: 'production',
    release: 'web@1.4.0',
  },
});

کاربر، سرنخ و خطای دستی

برای اینکه گزارش خطا قابل اقدام باشد، زمینهٔ کسب‌وکار را کنار خطا بفرستید.

ثبت زمینه
Didban.setUser({ id: 'user-42' });
Didban.addClue('Checkout opened', { cartId: 'cart-8' });
await Didban.capture(new Error('Payment failed'));

شبکه و درخواست‌های کند

خطاهای fetch و XHR خودکار ثبت می‌شوند. آستانهٔ درخواست کند را متناسب با SLO سرویس تنظیم کنید.

به‌صورت پیش‌فرض شناسه‌های پویا در مسیر API برای گروه‌بندی نادیده گرفته می‌شوند. URLهایی که هر شناسهٔ آن‌ها باید issue جدا بسازد در separateHttpUrls قرار دهید. مقدارهای query وارد fingerprint نمی‌شوند.

تنظیمات شبکه
config: {
  reportSlowRequests: true,
  slowRequestThresholdMs: 3000,
  ignoreUrls: ['/health'],
  separateHttpUrls: [
    '/api/v1/maintenance/service/timeline/',
  ],
}

حریم خصوصی و داده‌های حساس

SDK فیلدهای رایج مانند password، token و apiKey را پاک‌سازی می‌کند؛ دادهٔ حساس اختصاصی محصول را هم پیش از ارسال فیلتر کنید.

بدنهٔ درخواست و پاسخ را فقط جایی فعال نگه دارید که سیاست نگهداری دادهٔ سازمان اجازه می‌دهد.

MOBILE SDK02

React Native / Expo

خطاهای JavaScript، مسیرهای اپ و شاخص‌های FPS در اپ موبایل.

@didban/react-native

نصب SDK موبایل

پکیج React Native را در پروژهٔ اپ نصب کنید.

ترمینال
npm install @didban/react-native

راه‌اندازی

مقداردهی را یک بار و در بالاترین نقطهٔ چرخهٔ اجرای اپ انجام دهید.

ورودی اپ
import Didban from '@didban/react-native';

Didban.init({
  apiKey: 'YOUR_API_KEY',
  appName: 'mobile-app',
  config: {
    baseUrl: 'https://api.getdidban.ir',
    environment: 'production',
    release: 'mobile@1.0.0',
  },
});

مسیر فعلی و زمینهٔ کاربر

در تغییر هر صفحه، مسیر فعلی را ثبت کنید تا breadcrumb ناوبری به خطا متصل شود.

زمینهٔ اپ
Didban.setUser({ id: 'user-42' });
Didban.setCurrentRoute('Checkout', { cartId: 'cart-8' });

کارایی صفحه و افت FPS

پروفایل صفحه و افت فریم را فعال کنید و نتیجه را همیشه روی build نوع release ارزیابی کنید.

تنظیمات کارایی
config: {
  enableScreenProfiling: true,
  reportFpsDrops: true,
  minimumFps: 50,
  slowFrameThresholdMs: 32,
}

محدودهٔ پوشش

نسخهٔ فعلی خطاهای thread جاوااسکریپت را پوشش می‌دهد. crash بومی iOS/Android یا توقف UI thread به ماژول native نیاز دارد.

این محدودیت را هنگام تعریف هشدار و انتظار تیم عملیات در نظر بگیرید.

SERVER AGENT03

Node.js و سرور

نبض CPU و RAM، رخدادهای سرویس و خطاهای شبکهٔ سمت سرور.

didban-server-agent

نصب Agent در Node.js

Agent را کنار سرویس Node.js نصب کنید.

ترمینال
npm install didban-server-agent

اتصال سرور به سازمان

برای هر سرور agentId یکتا و نامی قابل تشخیص بگذارید. کلید را از متغیر محیطی بخوانید.

راه‌اندازی Agent
import { DidbanServerAgent } from 'didban-server-agent';

const agent = new DidbanServerAgent({
  serverUrl: 'wss://api.getdidban.ir/api/v1/live',
  apiKey: process.env.DIDBAN_API_KEY,
  agentId: 'checkout-api-1',
  name: 'Checkout API',
});

agent.start();

خطای شبکه و سرور

فقط خطاهای زیرساختی مرتبط را با category مشخص بفرستید تا snapshot همان لحظه کنار رخداد نگهداری شود.

ثبت خطای شبکه
agent.captureException(error, {
  category: 'network',
  upstream: 'payments',
});

نمونهٔ CPU و RAM فقط برای خطاهای network/server نگهداری می‌شود تا مصرف فضای ذخیره‌سازی کنترل شود.

Agent مستقل Linux

برای سرویس‌های ASP.NET Core یا هر زبان دیگر، Agent مستقل را روی همان ماشین اجرا کنید؛ این روش زبان‌مستقل است.

نصب روی Linux
curl -fsSL https://raw.githubusercontent.com/GetDidban/didban-server-agent/master/install.sh \
  | sudo bash -s -- --api-key 'didban_...' \
  --server 'wss://api.getdidban.ir/api/v1/live' \
  --name 'Production API'
.NET SDK04

ASP.NET Core / C#

ثبت exception با stack کامل، route و شناسه‌های W3C distributed trace.

Didban.AspNetCore

نصب پکیج

SDK از ASP.NET Core 8 و 9 پشتیبانی می‌کند.

ترمینال
dotnet add package Didban.AspNetCore

تا زمان انتشار عمومی NuGet، پروژهٔ src/Didban.AspNetCore را مستقیماً reference کنید.

اتصال Middleware

UseDidban را نزدیک ابتدای pipeline بگذارید تا خطای middlewareها و endpointهای بعدی را ثبت کند.

Program.cs
using Didban.AspNetCore;

builder.Services.AddDidban(options =>
{
    options.ApiKey = builder.Configuration["Didban:ApiKey"]!;
    options.AppName = "checkout-api";
    options.Environment = builder.Environment.EnvironmentName;
    options.Release = builder.Configuration["Didban:Release"];
});

var app = builder.Build();
app.UseDidban();

تریس توزیع‌شدهٔ خطا

SDK از Activity.Current مقادیر traceId، spanId، parentSpanId، operation و duration را به همان رخداد خطا متصل می‌کند. هدر traceparent ورودی نیز زنجیرهٔ سرویس‌ها را حفظ می‌کند.

تریس HttpClient

برای ثبت method، host، path، status و زمان درخواست‌های خروجی، handler دیدبان را به HttpClient اضافه کنید.

ثبت HttpClient
builder.Services
  .AddHttpClient<PaymentsClient>(client =>
    client.BaseAddress = new Uri("https://payments.internal"))
  .AddDidbanTracing();

خطای مدیریت‌شده

برای خطاهایی که catch می‌شوند، کلاینت را تزریق و رخداد را دستی ثبت کنید.

ثبت دستی
didban.AddBreadcrumb("Payment rejected", new Dictionary<string, object?> {
  ["cartId"] = cartId,
});

await didban.CaptureExceptionAsync(exception, new DidbanCaptureContext {
  Tags = new Dictionary<string, string> { ["feature"] = "checkout" },
});

امنیت داده

SDK مقدار password، token، cookie، authorization و apiKey را فیلتر می‌کند و body، header و مقدار query را به‌طور پیش‌فرض نمی‌فرستد.

JVM SDK05

Java / Spring Boot

ثبت خودکار exceptionهای Java همراه با stack، route و تریس توزیع‌شدهٔ W3C.

ir.getdidban:didban-spring-boot-starter

نصب برای Spring Boot

Starter را به پروژهٔ Maven اضافه کنید؛ نسخهٔ فعلی به Java 17 یا جدیدتر نیاز دارد.

pom.xml
<dependency>
  <groupId>ir.getdidban</groupId>
  <artifactId>didban-spring-boot-starter</artifactId>
  <version>0.1.0</version>
</dependency>

تا زمان انتشار در Maven Central، ماژول didban-spring-boot-starter را از پروژهٔ SDK به repository داخلی خود منتشر کنید.

اتصال خودکار Spring Boot

تنظیمات را در application.yml قرار دهید. Filter دیدبان خودکار ثبت می‌شود و exception را پس از گزارش دوباره throw می‌کند.

application.yml
didban:
  api-key: ${DIDBAN_API_KEY}
  app-name: checkout-api
  environment: production
  release: ${GIT_SHA}

تریس خطا بین سرویس‌ها

هدر traceparent ورودی اعتبارسنجی و ادامه داده می‌شود. traceId، spanId، parentSpanId، operation و duration به رخداد خطا متصل می‌شوند.

ارسال trace به سرویس بعدی
try (DidbanTraceScope span = didban.startSpan("payments.authorize")) {
  HttpRequest request = HttpRequest.newBuilder(paymentsUrl)
      .header("traceparent", span.traceParent())
      .build();
  httpClient.send(request, HttpResponse.BodyHandlers.discarding());
}

Java خالص و خطای مدیریت‌شده

در برنامه‌های بدون Spring، client را یک‌بار بسازید و خطاهای catch‌شده را دستی ثبت کنید.

راه‌اندازی client
DidbanClient didban = new DidbanClient(DidbanOptions.builder()
    .apiKey(System.getenv("DIDBAN_API_KEY"))
    .appName("checkout-api")
    .environment("production")
    .release(System.getenv("GIT_SHA"))
    .build());
ثبت خطا
didban.addBreadcrumb("Payment started", Map.of("cartId", "cart-8"));
didban.capture(error, new DidbanCaptureContext()
    .tag("feature", "checkout"));

حجم و امنیت داده

body، header و مقدار query ارسال نمی‌شوند؛ حداکثر ۳۰ breadcrumb فقط هنگام خطا همراه رخداد می‌رود و spanهای موفق دائماً ذخیره نمی‌شوند.

password، token، cookie، authorization، apiKey و اطلاعات کارت پیش از ارسال فیلتر می‌شوند.

KOTLIN SDK06

Kotlin / JVM

DSL بومی Kotlin برای ثبت خطا و حفظ trace در coroutineها و تغییر thread.

ir.getdidban:didban-kotlin

نصب SDK کاتلین

artifact کاتلین شامل هستهٔ مشترک Java و پشتیبانی coroutine است.

pom.xml
<dependency>
  <groupId>ir.getdidban</groupId>
  <artifactId>didban-kotlin</artifactId>
  <version>0.1.0</version>
</dependency>

تا زمان انتشار عمومی، artifact را از پروژهٔ didban-jvm-sdk در repository داخلی نصب کنید.

راه‌اندازی با DSL

کلاینت را یک‌بار در سطح application بسازید و کلید را از متغیر محیطی بخوانید.

راه‌اندازی
val didban = didban {
    apiKey = System.getenv("DIDBAN_API_KEY")
    appName = "checkout-api"
    environment = "production"
    release = System.getenv("GIT_SHA")
}

تریس امن در Coroutine

برای کد suspend از traceSuspending استفاده کنید؛ context دیدبان با ThreadContextElement هنگام تعویض dispatcher حفظ می‌شود.

تابع suspend
didban.traceSuspending("POST /checkout", incomingTraceParent) {
  withContext(Dispatchers.IO) {
    checkout.submitSuspending()
  }
}

breadcrumb و ثبت دستی

برای خطاهای مدیریت‌شده از extensionهای Kotlin استفاده کنید و فقط زمینهٔ لازم برای رفع خطا را بفرستید.

ثبت خطای مدیریت‌شده
didban.breadcrumb("Payment rejected", mapOf("cartId" to "cart-8"))

runCatching { checkout.submit() }
  .onFailure {
    it.captureWith(didban, tags = mapOf("feature" to "checkout"))
  }
  .getOrThrow()

Kotlin با Spring Boot

در پروژه‌های Kotlin/Spring همان starter جاوا را اضافه کنید؛ filter مستقل از زبان JVM است و exceptionهای Java و Kotlin را یکسان تریس می‌کند.

RELEASE TOOLING07

CI/CD و Source Map

تبدیل stack فشرده به فایل و خط واقعی همان release.

@getdidban/cli

توکن محدود CI

از تنظیمات اپلیکیشن یک توکن با دسترسی source_maps:write بسازید و آن را در secretهای CI نگه دارید.

متغیر محیطی
DIDBAN_TOKEN=didban_sm_...

آپلود پس از build

فرمان آپلود را بلافاصله بعد از build و پیش از deploy اجرا کنید.

پایپ‌لاین CI
npx @getdidban/cli sourcemaps upload \
  --directory dist \
  --release "$GITHUB_SHA" \
  --url-prefix /assets \
  --delete-after-upload

تا زمان انتشار عمومی CLI، این فرمان را با نسخهٔ داخلی pipeline اجرا کنید.

تطبیق release

شناسهٔ release در SDK و فرمان آپلود باید دقیقاً برابر باشد. commit SHA انتخاب مطمئنی برای CI است.

  • source map را عمومی deploy نکنید؛ پس از آپلود حذفش کنید.

  • artifact هر release را مستقل نگه دارید.

  • شکست آپلود را باعث توقف pipeline کنید.