نصب SDK مرورگر
پکیج را با npm نصب کنید و آن را پیش از رندر اصلی برنامه مقداردهی کنید.
npm install @didban/browser-sdkانتخاب SDK
SDK را انتخاب کنید، یک مسیر کوتاه را جلو بروید و خطا را با زمینهای بفرستید که به رفع آن کمک میکند.
01 / نصبnpm install @didban/browser-sdk02 / راهاندازی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',
},
});ثبت خودکار خطاهای مرورگر، درخواستهای شبکه و ردپای رفتار کاربر.
@didban/browser-sdkپکیج را با npm نصب کنید و آن را پیش از رندر اصلی برنامه مقداردهی کنید.
npm install @didban/browser-sdkتوکن اپلیکیشن، محیط و شناسهٔ یکتای 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 را پاکسازی میکند؛ دادهٔ حساس اختصاصی محصول را هم پیش از ارسال فیلتر کنید.
بدنهٔ درخواست و پاسخ را فقط جایی فعال نگه دارید که سیاست نگهداری دادهٔ سازمان اجازه میدهد.
خطاهای JavaScript، مسیرهای اپ و شاخصهای FPS در اپ موبایل.
@didban/react-nativeپکیج 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' });پروفایل صفحه و افت فریم را فعال کنید و نتیجه را همیشه روی build نوع release ارزیابی کنید.
config: {
enableScreenProfiling: true,
reportFpsDrops: true,
minimumFps: 50,
slowFrameThresholdMs: 32,
}نسخهٔ فعلی خطاهای thread جاوااسکریپت را پوشش میدهد. crash بومی iOS/Android یا توقف UI thread به ماژول native نیاز دارد.
این محدودیت را هنگام تعریف هشدار و انتظار تیم عملیات در نظر بگیرید.
نبض CPU و RAM، رخدادهای سرویس و خطاهای شبکهٔ سمت سرور.
didban-server-agentAgent را کنار سرویس Node.js نصب کنید.
npm install didban-server-agentبرای هر سرور agentId یکتا و نامی قابل تشخیص بگذارید. کلید را از متغیر محیطی بخوانید.
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 نگهداری میشود تا مصرف فضای ذخیرهسازی کنترل شود.
برای سرویسهای ASP.NET Core یا هر زبان دیگر، Agent مستقل را روی همان ماشین اجرا کنید؛ این روش زبانمستقل است.
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'ثبت exception با stack کامل، route و شناسههای W3C distributed trace.
Didban.AspNetCoreSDK از ASP.NET Core 8 و 9 پشتیبانی میکند.
dotnet add package Didban.AspNetCoreتا زمان انتشار عمومی NuGet، پروژهٔ src/Didban.AspNetCore را مستقیماً reference کنید.
UseDidban را نزدیک ابتدای pipeline بگذارید تا خطای middlewareها و endpointهای بعدی را ثبت کند.
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 ورودی نیز زنجیرهٔ سرویسها را حفظ میکند.
برای ثبت method، host، path، status و زمان درخواستهای خروجی، handler دیدبان را به 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 را بهطور پیشفرض نمیفرستد.
ثبت خودکار exceptionهای Java همراه با stack، route و تریس توزیعشدهٔ W3C.
ir.getdidban:didban-spring-boot-starterStarter را به پروژهٔ Maven اضافه کنید؛ نسخهٔ فعلی به Java 17 یا جدیدتر نیاز دارد.
<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 داخلی خود منتشر کنید.
تنظیمات را در application.yml قرار دهید. Filter دیدبان خودکار ثبت میشود و exception را پس از گزارش دوباره throw میکند.
didban:
api-key: ${DIDBAN_API_KEY}
app-name: checkout-api
environment: production
release: ${GIT_SHA}هدر traceparent ورودی اعتبارسنجی و ادامه داده میشود. traceId، spanId، parentSpanId، operation و duration به رخداد خطا متصل میشوند.
try (DidbanTraceScope span = didban.startSpan("payments.authorize")) {
HttpRequest request = HttpRequest.newBuilder(paymentsUrl)
.header("traceparent", span.traceParent())
.build();
httpClient.send(request, HttpResponse.BodyHandlers.discarding());
}در برنامههای بدون Spring، client را یکبار بسازید و خطاهای catchشده را دستی ثبت کنید.
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 و اطلاعات کارت پیش از ارسال فیلتر میشوند.
DSL بومی Kotlin برای ثبت خطا و حفظ trace در coroutineها و تغییر thread.
ir.getdidban:didban-kotlinartifact کاتلین شامل هستهٔ مشترک Java و پشتیبانی coroutine است.
<dependency>
<groupId>ir.getdidban</groupId>
<artifactId>didban-kotlin</artifactId>
<version>0.1.0</version>
</dependency>تا زمان انتشار عمومی، artifact را از پروژهٔ didban-jvm-sdk در repository داخلی نصب کنید.
کلاینت را یکبار در سطح application بسازید و کلید را از متغیر محیطی بخوانید.
val didban = didban {
apiKey = System.getenv("DIDBAN_API_KEY")
appName = "checkout-api"
environment = "production"
release = System.getenv("GIT_SHA")
}برای کد suspend از traceSuspending استفاده کنید؛ context دیدبان با ThreadContextElement هنگام تعویض dispatcher حفظ میشود.
didban.traceSuspending("POST /checkout", incomingTraceParent) {
withContext(Dispatchers.IO) {
checkout.submitSuspending()
}
}برای خطاهای مدیریتشده از 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 همان starter جاوا را اضافه کنید؛ filter مستقل از زبان JVM است و exceptionهای Java و Kotlin را یکسان تریس میکند.
تبدیل stack فشرده به فایل و خط واقعی همان release.
@getdidban/cliاز تنظیمات اپلیکیشن یک توکن با دسترسی source_maps:write بسازید و آن را در secretهای CI نگه دارید.
DIDBAN_TOKEN=didban_sm_...فرمان آپلود را بلافاصله بعد از build و پیش از deploy اجرا کنید.
npx @getdidban/cli sourcemaps upload \
--directory dist \
--release "$GITHUB_SHA" \
--url-prefix /assets \
--delete-after-uploadتا زمان انتشار عمومی CLI، این فرمان را با نسخهٔ داخلی pipeline اجرا کنید.
شناسهٔ release در SDK و فرمان آپلود باید دقیقاً برابر باشد. commit SHA انتخاب مطمئنی برای CI است.
source map را عمومی deploy نکنید؛ پس از آپلود حذفش کنید.
artifact هر release را مستقل نگه دارید.
شکست آپلود را باعث توقف pipeline کنید.