جریان زنده لاگ (Live Log Streaming) در اندروید

ارسال لاگ‌های عملیاتی و تله‌متری زنده به دیدبان با استفاده از یک بافر حلقوی بهینه، ارسال دسته‌ای خودکار و بدون تأثیر بر عملکرد برنامه.

سطوح شدت لاگ

دیدبان چهار سطح شدت استاندارد را پشتیبانی می‌کند. از متدهای کوتاه یا متد عمومی log با LogLevel صریح استفاده کنید:

MyViewModel.ktkotlin
// Convenience methods — message is the first argument
Didban.debug("Refreshing access token", tag = "auth")
Didban.info("Item added to cart", tag = "cart", attributes = mapOf("sku" to "ABC-123", "qty" to 2))
Didban.warn("Retrying request after timeout", tag = "network", attributes = mapOf("attempt" to 2))
Didban.error("Failed to write user cache", tag = "database", attributes = mapOf("error" to "disk_full"))

// Or with explicit LogLevel:
Didban.log("Order submitted", level = LogLevel.INFO, tag = "checkout", attributes = mapOf("amount" to 49.99))

فلاش فوری (Flush)

برای ارسال فوری لاگ‌های معلق قبل از انتقال‌های مهم (مثل خروج از صفحه یا پایان تراکنش)، از flush استفاده کنید:

CheckoutActivity.ktkotlin
Didban.info("Payment confirmed", tag = "checkout", attributes = mapOf("orderId" to orderId))
Didban.flush() // ensure the log is uploaded before finishing the activity

نحوه کارکرد

  • بافر حلقوی (Ring Buffer): تمام لاگ‌ها در یک بافر حلقوی با ظرفیت ۲۰۰ مورد درون حافظه نگهداری می‌شوند. لاگ‌های قدیمی‌تر به صورت خودکار حذف می‌شوند.
  • ارسال دسته‌ای (Batching): هر بار که ۲۰ لاگ انباشته شود یا ۱۵ ثانیه بگذرد، ارسال به‌طور خودکار انجام می‌شود.
  • فلاش خودکار در پس‌زمینه: هنگامی که برنامه وارد پس‌زمینه می‌شود، تمام لاگ‌های معلق به‌طور خودکار ارسال می‌شوند.
  • غیر مسدودکننده: تمام ارسال‌ها در یک coroutine پس‌زمینه انجام می‌شوند و هیچ تأثیری بر thread اصلی ندارند.

ویژگی‌های ساختاریافته (Attributes)

پارامتر attributes یک Map اختیاری است که داده‌های ساختاریافته را به لاگ ضمیمه می‌کند. این داده‌ها در داشبورد در یک modal قابل بررسی هستند:

NetworkClient.ktkotlin
Didban.warn(
    "API request slow",
    tag = "network",
    attributes = mapOf(
        "endpoint" to "/v1/products",
        "latencyMs" to 3200,
        "statusCode" to 200,
        "retryCount" to 1
    )
)
یادداشت

لاگ‌ها با کلید Ingestion (didban_ing_...) احراز هویت می‌شوند — همان کلیدی که در Didban.init() ارائه می‌دهید. کلید Build / CI هرگز برای ارسال لاگ استفاده نمی‌شود.

حریم خصوصی

هشدار امنیتی

هرگز اطلاعات حساس را در لاگ‌ها قرار ندهید. از درج گذرواژه‌ها، توکن‌های احراز هویت، شماره کارت بانکی یا اطلاعات شخصی قابل شناسایی (PII) در پیام‌ها یا attributes خودداری کنید.