Logger¶
public 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. |
let bgGeo = BGGeo.shared
Task {
do {
let log = try await bgGeo.logger.getLog()
} catch {
print("[getLog] error: \(error)")
}
}
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.
let bgGeo = BGGeo.shared
let sub = bgGeo.onLocation { location in
bgGeo.logger.debug("Location received in Swift")
}
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 |
đĩ |
Examples¶
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¶
public func emailLog( to email: String, start: Int64 = 0, end: Int64 = 0, order: Int =Logger.ORDER_ASC, limit: Int = 0 ) async throws
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
let bgGeo = BGGeo.shared
Task {
do {
try await bgGeo.logger.emailLog(to: "foo@bar.com")
print("[emailLog] success")
} catch {
print("[emailLog] FAILURE: \(error)")
}
}
error¶
Insert an error-level message into the SDK's log database.
getLog¶
public func getLog( start: Int64 = 0, end: Int64 = 0, order: Int =Logger.ORDER_ASC, limit: Int = 0 ) async throws -> String
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
let bgGeo = BGGeo.shared
Task {
do {
// Warning: this string could be several megabytes.
let log = try await bgGeo.logger.getLog()
print("[log] success: \(log)")
} catch {
print("[getLog] error: \(error)")
}
}
info¶
Insert an info-level message into the SDK's log database.
notice¶
Insert a notice-level message into the SDK's log database.
playSound¶
Play a system sound.
iOS¶
Provide a numeric SystemSoundID.
Android¶
Provide a sound name string.
uploadLog¶
public func uploadLog( url: String, start: Int64 = 0, end: Int64 = 0, order: Int =Logger.ORDER_ASC, limit: Int = 0 ) async throws
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).