ابرووا
شروع رایگان
☰ فهرست مستندات · لاگ در SDK اندروید

لاگ‌گیری با SDK اندروید

لاگ‌گیری ساختاریافته برای اپ‌های Android با ارسال دسته‌ای خودکار، تلاش مجدد با فاصله‌ی افزایشی و آگاهی از چرخه‌ی حیات اپ، با SDK بومی Kotlin.

به‌روزرسانی: ۵ آبان ۱۴۰۵

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

ارسال دسته‌ای خودکار

لاگ‌ها بافر می‌شوند و دسته‌ای فرستاده می‌شوند (پیش‌فرض: ۵۰)

تلاش مجدد با فاصله‌ی افزایشی

دسته‌های ناموفق با فاصله‌های بیشترشونده دوباره فرستاده می‌شوند (۲ ثانیه، ۴ ثانیه، ۸ ثانیه... تا ۶۰ ثانیه)

حداکثر اندازه‌ی بافر

وقتی بافر از ۱۰۰۰ لاگ بگذرد، قدیمی‌ترین لاگ‌ها حذف می‌شوند تا حافظه پر نشود

تایمر تنبل

تایمر فقط وقتی کار می‌کند که بافر لاگ داشته باشد — در حالت بیکار باتری مصرف نمی‌شود

اطلاعات کاربر

شناسه‌ی کاربری که با AbrovaTrace.setUserId() تنظیم شده خودکار پیوست می‌شود

Kotlin بومی

با Kotlin ساخته شده و از API 19 به بالا (Android 4.4 به بالا) پشتیبانی می‌کند

فعال کردن لاگ‌گیری#

بعد از راه‌اندازی AbrovaTrace در کلاس Application، سرویس لاگ‌گیری را فعال کنید:

kotlin
import android.app.Application
import ir.abrova.trace.sdk.AbrovaTrace
import ir.abrova.trace.sdk.AbrovaTraceConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize AbrovaTrace first
        val config = AbrovaTraceConfig.Builder("ab_live_YOUR_API_KEY")
            .environment("production")
            .release(BuildConfig.VERSION_NAME)
            .build()

        AbrovaTrace.init(this, config)

        // Enable logging with a source identifier
        AbrovaTrace.enableLogging(
            sourceId = "my-android-app",
            sourceName = "My Android App",
            batchSize = 50,
            flushIntervalMs = 5000L
        )
    }
}

ارسال لاگ#

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

kotlin
import ir.abrova.trace.sdk.AbrovaTrace

// Info log
AbrovaTrace.info("User login successful", mapOf(
    "user_id" to "user_123"
))

// Warning log
AbrovaTrace.warn("Slow API response", mapOf(
    "endpoint" to "/api/users",
    "duration_ms" to 2500
))

// Error log
AbrovaTrace.logError("Database query failed", mapOf(
    "query" to "SELECT * FROM users",
    "error" to "Connection timeout"
))

// Debug log
AbrovaTrace.logDebug("Cache hit for key: user_123")

// Trace log
AbrovaTrace.trace("Entering function processPayment()")

// Fatal log
AbrovaTrace.fatal("App crashed unexpectedly", mapOf(
    "last_screen" to "checkout"
))

متد عمومی log

kotlin
import ir.abrova.trace.sdk.models.LogLevel

// Generic log with explicit level
AbrovaTrace.log(
    "Custom event",
    LogLevel.INFO,
    mapOf("key" to "value")
)

سطح‌های لاگ#

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

استفاده در Activityها#

kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        AbrovaTrace.info("MainActivity created", mapOf("screen" to "main"))
    }

    private fun handlePurchase() {
        AbrovaTrace.info("Purchase initiated", mapOf(
            "product_id" to "premium_pack",
            "amount" to 99.99
        ))

        try {
            processPurchase()
            AbrovaTrace.info("Purchase completed", mapOf("amount" to 99.99))
        } catch (e: Exception) {
            AbrovaTrace.logError("Purchase failed", mapOf(
                "error" to e.message,
                "product_id" to "premium_pack"
            ))
            AbrovaTrace.captureException(e)
        }
    }

    override fun onDestroy() {
        if (isFinishing) {
            AbrovaTrace.flushLogs()
            AbrovaTrace.close()
        }
        super.onDestroy()
    }
}

عملیات دستی#

kotlin
// Force flush all buffered logs
AbrovaTrace.flushLogs { success ->
  if (success) {
      Log.d("AbrovaTrace", "Logs flushed successfully")
  }
}

// Check buffer status
val pendingCount = AbrovaTrace.getPendingLogCount()
Log.d("AbrovaTrace", "Pending logs: $pendingCount")

پیکربندی#

گزینهنوعاجباریتوضیح
sourceIdString?خیرشناسه برای ارسال دسته‌ای (مثلاً "my-android-app")
sourceNameString?خیرنام خوانا برای این منبع
batchSizeIntخیروقتی بافر به این اندازه برسد flush می‌شود (پیش‌فرض: ۵۰)
flushIntervalMsLongخیرحداکثر زمان تا flush به میلی‌ثانیه (پیش‌فرض: ۵۰۰۰)

اگر پیش از enableLogging() یکی از متدهای لاگ را صدا بزنید، لاگ‌گیری خودکار با پیش‌فرض‌های بالا (بدون sourceId) روشن می‌شود. بدون sourceId هر لاگ جداگانه به /api/logs/ingest فرستاده می‌شود و ارسال ناموفق دوباره امتحان نمی‌شود؛ با آن، لاگ‌های بافرشده در یک درخواست به /api/logs/ingest/batch می‌روند و دسته‌ی ناموفق دوباره فرستاده می‌شود. وقتی اپ به پس‌زمینه می‌رود هم لاگ‌ها flush می‌شوند. تا وقتی اپ در پس‌زمینه است تایمر flush کار نمی‌کند: لاگ‌ها وقتی فرستاده می‌شوند که به اندازه‌ی دسته برسند یا اپ به پیش‌زمینه برگردد.

توصیه‌ها#

زود فعالش کنید

لاگ‌گیری را درست بعد از AbrovaTrace.init() فعال کنید تا همه‌ی رویدادها ثبت شوند

از شناسه‌ی منبع استفاده کنید

یک sourceId معنادار بگذارید تا لاگ‌های این اپ در داشبورد مشخص باشد

متادیتا اضافه کنید

متادیتای ساختاریافته (شناسه‌ی کاربر، نام صفحه و…) بفرستید تا دیباگ ساده‌تر شود

سطح مناسب را انتخاب کنید

برای رویدادهای عادی info، برای مشکلات احتمالی warn و برای شکست‌ها error

هنگام بستن flush کنید

پیش از بسته شدن اپ AbrovaTrace.flushLogs() را صدا بزنید تا همه‌ی لاگ‌ها فرستاده شوند

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

در حلقه‌های پرتکرار لاگ نگیرید — بافر حداکثر اندازه دارد و قدیمی‌ترین لاگ‌ها را حذف می‌کند

این صفحه مفید بود؟
گزارش مشکل