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.
Contents¶
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. |
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:
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¶
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¶
Insert a debug-level message into the SDK's log database.
destroyLog¶
Delete all records from the SDK's log database.
See also
- LoggerConfig.logLevel
- getLog
- emailLog
- uploadLog
- đDebugging Guide
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¶
Insert an error-level message into the SDK's log database.
getLog¶
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¶
Insert an info-level message into the SDK's log database.
notice¶
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")
playSound¶
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.
Authentication¶
The upload carries the same credentials as a location upload: your
configured HttpConfig.headers, then the authorization access token
as an Authorization header. When both supply an Authorization header,
the access token wins. A Content-Type or Content-Length in
http.headers is not sent: the multipart body sets its own.
The upload does not refresh an expired access token: a 401 response
rejects it. Token refresh on a 401 applies to location uploads only.
The headers go to whatever URL you pass, including the URL of an RPC
uploadLog command. A pre-signed storage URL may refuse a request that
carries an Authorization header.
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 |
Warning
The upload does not follow HTTP redirects: any 3xx response rejects it,
so pass the URL your server answers directly. When your server redirects
an unauthenticated upload to a login page, the promise rejects instead of
resolving on the login page's 200.
See also
- LoggerConfig.logLevel
- getLog
- emailLog
- destroyLog
- đDebugging Guide
warn¶
Insert a warning-level message into the SDK's log database.
Properties¶
ORDER_ASC¶
Sort-order constant for ascending log queries (oldest first).
ORDER_DESC¶
Sort-order constant for descending log queries (newest first).