Logger¶

classLogger

SDK logging API — access via BGGeo.logger.

The SDK writes structured log entries to an internal SQLite database for up to LoggerConfig.logMaxDays days (default 3). Log volume is controlled by LoggerConfig.logLevel (default LogLevel.Off). Logs can be fetched as a string, emailed from the device, or uploaded to a URL.

Overview¶

Method	Description
`getLog`	Fetch all log entries as a string.
`emailLog`	Send logs via the device mail client.
`uploadLog`	Upload logs to a URL as a gzipped multipart file.
`destroyLog`	Clear the log database.
`debug`, `info`, `warn`, `error`, `notice`	Write custom log entries.

val bgGeo = BGGeo.instance
// Within a coroutine scope
val log = bgGeo.logger.getLog()

Retrieving logs¶

All three retrieval methods accept an optional SQLQuery to constrain results by date range, sort order, and record count. Without a query, all records up to LoggerConfig.logMaxDays days old are returned.

val bgGeo = BGGeo.instance
bgGeo.onLocation { location ->
    bgGeo.logger.log("debug", "Location received in Kotlin: ${location.extras}")
}

Sample log output:

09-19 11:12:18.716 ╔═════════════════════════════════════════════
09-19 11:12:18.716 ║ BackgroundGeolocation Service started
09-19 11:12:18.716 ╠═════════════════════════════════════════════
09-19 11:12:18.723   ✅  Started in foreground
09-19 11:12:18.737   🎾  Start activity updates: 10000
09-19 11:12:21.405   ✅  INSERT: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:21.454   🔵  HTTP POST: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:22.083   🔵  Response: 200
09-19 11:12:22.100   ✅  DESTROY: bca5acc8-e358-4d8f-827f-b8c0d556b7bb

Analyzing a log¶

A multi-day capture runs to hundreds of thousands of lines. loganalyzer reads one and produces a triage digest — what the SDK did and what went wrong — plus an interactive map of where it did it:

npx @transistorsoft/loganalyzer background-geolocation.log.gz

It accepts the exports produced by getLog, emailLog and uploadLog — .log or .log.gz, one file or several.

digest.md is pseudonymized (coordinates become COORD-A, geofences GF-1), which makes it the artifact to attach to a support issue. map.html plots full-precision coordinates and is a local instrument — do not share it.

See Debugging → Log Analyzer for the full walkthrough.

Writing log entries¶

Insert custom messages into the SDK's log database at any severity level. Custom entries appear inline with SDK entries, making it easy to correlate your app's actions with location events.

Method	Level	Icon
`error`	`ERROR`	❗️
`warn`	`WARNING`	⚠️
`debug`	`DEBUG`	🐞
`info`	`INFO`	ℹ️
`notice`	`INFO`	🔵

val bgGeo = BGGeo.instance

bgGeo.onLocation { location ->
    bgGeo.logger.log("debug", "Location received: ${location.uuid}")
}

Examples¶

Fetch and display the full log¶

// Within a coroutine scope
val bgGeo = BGGeo.instance

val log = bgGeo.logger.getLog()
Log.d(TAG, "[log] $log")

Upload log to your server¶

// Not available in native Kotlin API

Email log with a date range¶

// Within a coroutine scope
val bgGeo = BGGeo.instance
val activity = android.app.Activity()

// Requires an Activity reference
bgGeo.logger.emailLog("support@example.com", activity)

Methods¶

debug¶

fun debug(message: String)

Insert a debug-level message into the SDK's log database.

val bgGeo = BGGeo.instance
bgGeo.logger.log("debug", "This is a debug message")

D TSLocationManager: [c.t.l.logger.TSLog log] This is a debug message

destroyLog¶

suspend fun destroyLog()

Delete all records from the SDK's log database.

See also - LoggerConfig.logLevel - getLog - emailLog - uploadLog - 📘Debugging Guide

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.logger.destroyLog()

emailLog¶

suspend fun emailLog( email: String, activity: Activity, start: Long = 0, end: Long = 0, order: Int = ORDER_ASC, limit: Int = 0 )

Send the SDK's log database to an email address via the device mail client.

Provide an optional SQLQuery to constrain which records are included.

See also - LoggerConfig.logLevel - getLog - uploadLog - 📘Debugging Guide - 🔎Analyzing a log

val bgGeo = BGGeo.instance
// Within a coroutine scope
// Requires an Activity reference
// bgGeo.logger.emailLog("foo@bar.com", activity)

error¶

fun error(message: String)

Insert an error-level message into the SDK's log database.

val bgGeo = BGGeo.instance
bgGeo.logger.log("error", "Something BAD")

E TSLocationManager: [c.t.l.logger.TSLog log]
E TSLocationManager: ‼ Something BAD

getLog¶

suspend fun getLog( start: Long = 0, end: Long = 0, order: Int = ORDER_ASC, limit: Int = 0 )

Fetch the SDK's log database as a string.

Provide an optional SQLQuery to constrain results by date range, sort order, and record count. Depending on LoggerConfig.logLevel, the result may be several megabytes.

See also - LoggerConfig.logMaxDays - LoggerConfig.logLevel - emailLog - uploadLog - 📘Debugging Guide

val bgGeo = BGGeo.instance
// Within a coroutine scope
val log = bgGeo.logger.getLog()
// Warning: this string could be several megabytes.
Log.d(TAG, "[log] success: $log")

info¶

fun info(message: String)

Insert an info-level message into the SDK's log database.

val bgGeo = BGGeo.instance
bgGeo.logger.log("info", "Something informative")

I TSLocationManager: [c.t.l.logger.TSLog log]
I TSLocationManager:   ℹ️  Something informative

logLevel¶

var logLevel:LogLevel

Sets the LoggerConfig.logLevel.

notice¶

fun notice(message: String)

Insert a notice-level message into the SDK's log database.

val bgGeo = BGGeo.instance
// No "notice" level in Kotlin — use "info" instead
bgGeo.logger.log("info", "A Notice")

I TSLocationManager: [c.t.l.logger.TSLog log]
I TSLocationManager:   🔵  A Notice

playSound¶

fun playSound(soundId: Int)

Play a system sound.

iOS¶

Provide a numeric SystemSoundID.

Android¶

Provide a sound name string.

uploadLog¶

suspend fun uploadLog( url: String, start: Long = 0, end: Long = 0, order: Int = ORDER_ASC, limit: Int = 0 )

Upload the SDK's log database to a URL as a gzipped multipart file.

Provide an optional SQLQuery to constrain which records are included. The upload includes your configured HttpConfig.headers for authentication.

Multipart upload¶

The log is posted as a gzipped multipart file — the same file produced by emailLog. The request body also includes a form with the following fields:

Key	Value
`state`	JSON-encoded result of `getState`
`model`	Device model
`manufacturer`	Device manufacturer
`platform`	`iOS` or `Android`
`version`	OS version

See also - LoggerConfig.logLevel - getLog - emailLog - destroyLog - 📘Debugging Guide

// Not available in native Kotlin API

warn¶

fun warn(message: String)

Insert a warning-level message into the SDK's log database.

val bgGeo = BGGeo.instance
bgGeo.logger.log("warn", "Something WEIRD")

E TSLocationManager: [c.t.l.logger.TSLog log]
E TSLocationManager: ⚠️  Something WEIRD

Properties¶

ORDER_ASC¶

const val ORDER_ASC = 1

Sort-order constant for ascending log queries (oldest first).

ORDER_DESC¶

const val ORDER_DESC = -1

Sort-order constant for descending log queries (newest first).