لاگگیری با SDK اندروید
لاگگیری ساختاریافته برای اپهای Android با ارسال دستهای خودکار، تلاش مجدد با فاصلهی افزایشی و آگاهی از چرخهی حیات اپ، با SDK بومی Kotlin.
لاگگیری ساختاریافته برای اپهای Android با ارسال دستهای خودکار، تلاش مجدد با فاصلهی افزایشی (exponential backoff) و آگاهی از چرخهی حیات اپ. لاگها بافر میشوند و دستهای فرستاده میشوند تا مصرف اینترنت و باتری کم بماند.
لاگها بافر میشوند و دستهای فرستاده میشوند (پیشفرض: ۵۰)
دستههای ناموفق با فاصلههای بیشترشونده دوباره فرستاده میشوند (۲ ثانیه، ۴ ثانیه، ۸ ثانیه... تا ۶۰ ثانیه)
وقتی بافر از ۱۰۰۰ لاگ بگذرد، قدیمیترین لاگها حذف میشوند تا حافظه پر نشود
تایمر فقط وقتی کار میکند که بافر لاگ داشته باشد — در حالت بیکار باتری مصرف نمیشود
شناسهی کاربری که با AbrovaTrace.setUserId() تنظیم شده خودکار پیوست میشود
با Kotlin ساخته شده و از API 19 به بالا (Android 4.4 به بالا) پشتیبانی میکند
فعال کردن لاگگیری#
بعد از راهاندازی AbrovaTrace در کلاس Application، سرویس لاگگیری را فعال کنید:
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
)
}
}ارسال لاگ#
متدهای میانبر
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
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ها#
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()
}
}عملیات دستی#
// 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")پیکربندی#
| گزینه | نوع | اجباری | توضیح |
|---|---|---|---|
| sourceId | String? | خیر | شناسه برای ارسال دستهای (مثلاً "my-android-app") |
| sourceName | String? | خیر | نام خوانا برای این منبع |
| batchSize | Int | خیر | وقتی بافر به این اندازه برسد flush میشود (پیشفرض: ۵۰) |
| flushIntervalMs | Long | خیر | حداکثر زمان تا flush به میلیثانیه (پیشفرض: ۵۰۰۰) |
اگر پیش از enableLogging() یکی از متدهای لاگ را صدا بزنید، لاگگیری خودکار با پیشفرضهای بالا (بدون sourceId) روشن میشود. بدون sourceId هر لاگ جداگانه به /api/logs/ingest فرستاده میشود و ارسال ناموفق دوباره امتحان نمیشود؛ با آن، لاگهای بافرشده در یک درخواست به /api/logs/ingest/batch میروند و دستهی ناموفق دوباره فرستاده میشود. وقتی اپ به پسزمینه میرود هم لاگها flush میشوند. تا وقتی اپ در پسزمینه است تایمر flush کار نمیکند: لاگها وقتی فرستاده میشوند که به اندازهی دسته برسند یا اپ به پیشزمینه برگردد.
توصیهها#
لاگگیری را درست بعد از AbrovaTrace.init() فعال کنید تا همهی رویدادها ثبت شوند
یک sourceId معنادار بگذارید تا لاگهای این اپ در داشبورد مشخص باشد
متادیتای ساختاریافته (شناسهی کاربر، نام صفحه و…) بفرستید تا دیباگ سادهتر شود
برای رویدادهای عادی info، برای مشکلات احتمالی warn و برای شکستها error
پیش از بسته شدن اپ AbrovaTrace.flushLogs() را صدا بزنید تا همهی لاگها فرستاده شوند
در حلقههای پرتکرار لاگ نگیرید — بافر حداکثر اندازه دارد و قدیمیترین لاگها را حذف میکند