لاگ‌گیری در SDK فلاتر

لاگ‌گیری کم‌مصرف برای اپ‌های Flutter با ارسال دسته‌ای خودکار، تلاش دوباره با فاصله‌ی افزایشی (exponential backoff) و توجه به چرخه‌ی حیات موبایل. لاگ‌ها در بافر نگه داشته و به‌صورت دسته‌ای ارسال می‌شوند تا مصرف شبکه کم بماند.

۱فعال‌سازی لاگ‌گیری#

پس از مقداردهی اولیه‌ی AbrovaTrace، سرویس لاگ‌گیری را فعال کنید:

import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Initialize AbrovaTrace first
await AbrovaTrace.init(AbrovaTraceConfig(
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
  release: '1.0.0',
));

// Enable logging with a source identifier
AbrovaTrace.enableLogging(
  sourceId: 'my-flutter-app',
  sourceName: 'My Flutter App',
  batchSize: 50,
  flushInterval: Duration(seconds: 5),
);

اگر یکی از متدهای لاگ را پیش از enableLogging() صدا بزنید، لاگ‌گیری خودکار با مقادیر پیش‌فرض و بدون sourceId فعال می‌شود. لاگ‌گیری به Flutter binding نیاز دارد، پس آن را پس از WidgetsFlutterBinding.ensureInitialized() فعال کنید (یا اولین لاگ را بعد از آن بفرستید).

۲ارسال لاگ‌ها#

متدهای کمکی

// Info log
AbrovaTrace.info('User login successful', metadata: {
  'user_id': 'user_123',
});

// Warning log
AbrovaTrace.warn('Slow API response', metadata: {
  'endpoint': '/api/users',
  'duration_ms': 2500,
});

// Error log
AbrovaTrace.logError('Database query failed', metadata: {
  'query': 'SELECT * FROM users',
  'error': 'Connection timeout',
});

// Debug log
AbrovaTrace.debug('Cache hit for key: user_123');

// Trace log
AbrovaTrace.trace('Entering function processPayment()');

// Fatal log
AbrovaTrace.fatal('App crashed unexpectedly', metadata: {
  'last_screen': 'checkout',
});

متد عمومی لاگ

import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Generic log with explicit level
AbrovaTrace.log(
  'Custom event',
  level: LogLevel.info,
  metadata: {'key': 'value'},
);

۳سطح‌های لاگ#

• trace — AbrovaTrace.trace() — دیباگ بسیار جزئی در سطح trace
• debug — AbrovaTrace.debug() — اطلاعات دیباگ هنگام توسعه
• info — AbrovaTrace.info() — اطلاعات عمومی اپلیکیشن
• warn — AbrovaTrace.warn() — هشدار درباره‌ی مشکلات احتمالی
• error — AbrovaTrace.logError() — خطاهایی که باید بررسی شوند
• fatal — AbrovaTrace.fatal() — خطاهای بحرانی و غیرقابل بازیابی

۴رفتار در چرخه‌ی حیات موبایل#

سرویس لاگ‌گیری رویدادهای چرخه‌ی حیات اپ را خودکار مدیریت می‌کند:

• توقف اپ / رفتن به پس‌زمینه — همه‌ی لاگ‌های بافر را فوراً ارسال می‌کند
• بازگشت اپ — شمارنده‌ی تلاش دوباره را صفر می‌کند و کار عادی ادامه پیدا می‌کند
• جدا شدن اپ (detached) — لاگ‌ها را ارسال می‌کند و ارسال را متوقف می‌کند
• پر شدن بافر — وقتی از سقف بافر (۱٬۰۰۰) بیشتر شود، قدیمی‌ترین لاگ‌ها حذف می‌شوند

۵عملیات دستی#

// Force flush all buffered logs
await AbrovaTrace.flushLogs();

// Check buffer status
print('Pending logs: ${AbrovaTrace.pendingLogCount}');

۶پیکربندی#

بافر حداکثر ۱٬۰۰۰ لاگ نگه می‌دارد (قدیمی‌ترین‌ها اول حذف می‌شوند). این سقف ثابت است و با enableLogging() تغییر نمی‌کند.

توصیه‌ها#