Logger¶

SDK logging API — access via BackgroundGeolocation.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.

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.

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

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.

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

destroyLog¶

Delete all records from the SDK's log database.

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

emailLog¶

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

error¶

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

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

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

info¶

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

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

notice¶

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

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

uploadLog¶

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

warn¶

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

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