LoggerConfig¶

classLoggerConfig

Logging and diagnostics configuration for the background geolocation SDK.

LoggerConfig controls how much the SDK writes to its internal log, how long entries are retained on device, and whether developer debug aids such as audible soundFX are active.

Contents¶

Overview
Log levels
Debug mode
Retention
Diagnostics
Examples

Overview¶

The SDK maintains a persistent, SQLite-backed log that survives app restarts. Logging serves two purposes:

Development & QA — High-verbosity logs and optional audible soundFX make it easy to follow SDK behaviour without watching a console. You can hear when locations are recorded, when motion transitions occur, and when geofences fire.
Production diagnostics — Lower verbosity preserves essential operational traces without excessive storage use or privacy impact.

Category	Properties	Notes
Verbosity	`logLevel`	`Off` → `Verbose`
Debug aids	`debug`	Audible soundFX and debug notifications
Retention	`logMaxDays`	Rolling on-device TTL

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 7
}

Log levels¶

Choose the level appropriate for your environment:

Level	Value	Description
LogLevel.Off	0	Disable logging entirely
LogLevel.Error	1	Failures and critical errors
LogLevel.Warning	2	Problems that may affect behaviour
LogLevel.Info	3	Operational milestones (start/stop, HTTP, geofence state)
LogLevel.Debug	4	Granular detail during integration
LogLevel.Verbose	5	Maximum detail; full introspection

Use Verbose during active development. Use Info or Warning in production. Avoid Off unless required — logs are invaluable for field diagnostics.

Debug mode¶

When debug is true, the SDK plays short, distinct soundFX as key events occur — location recorded, motion change, geofence enter/exit/dwell, HTTP upload — and may show transient developer notifications on Android to visualize state transitions.

Warning

Never enable debug in a production build. Disable it before submitting your app to the App Store or Google Play.

Retention¶

logMaxDays controls how long log entries remain on device. Entries older than the configured limit are purged automatically on a rolling basis.

Recommended values: - Development: 5–7 days - Production: 1–3 days

Diagnostics¶

Logs are your first resource when something unexpected happens. The SDK writes a detailed trace of every lifecycle event — location recording, motion transitions, HTTP uploads, geofence activity — to an internal SQLite database. When behaviour is unclear, set logLevel to LogLevel.Verbose and fetch the log before doing anything else:

await BackgroundGeolocation.setConfig({
  logger: { logLevel: BackgroundGeolocation.LogLevel.Verbose }
});

Use Logger.emailLog to send logMaxDays worth of logs as an email attachment directly from the device:

await BackgroundGeolocation.logger.emailLog("you@example.com");

Android¶

Stream live SDK output directly to your terminal with adb:

adb logcat "*:S" TSLocationManager:V

iOS¶

Run the app from Xcode to stream SDK output to the console in real time. For issues that only reproduce in the background, attach the device and monitor the Xcode console while the app runs in the background.

Examples¶

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

// Current compound config
bgGeo.ready {
    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 3
}

Development profile¶

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

bgGeo.ready {
    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 7
}

Production profile¶

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

bgGeo.ready {
    logger.debug = false
    logger.logLevel = LogLevel.INFO
    logger.logMaxDays = 3
}

Disable all logging¶

val bgGeo = BGGeo.instance
bgGeo.config.edit {
    logger.logLevel = LogLevel.OFF
}

Development profile (maximum visibility)¶

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 7
}

Production profile (quiet & conservative)¶

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    logger.debug = false
    logger.logLevel = LogLevel.INFO
    logger.logMaxDays = 3
}

New compound Config¶

val bgGeo = BGGeo.instance
bgGeo.config.edit {
    logger.debug = true
    logger.logLevel = LogLevel.VERBOSE
    logger.logMaxDays = 3
}

Members¶

debug¶

var debug: Boolean

Enables audible soundFX and debug notifications during development.

When true, the SDK plays a distinct sound for each key lifecycle event so you can follow SDK activity without watching the console. It may also display transient notifications on Android to visualize background state transitions.

Defaults to false.

iOS¶

To hear debug sounds while the app is in the background, enable the Audio and AirPlay background mode in Xcode under Signing & Capabilities → Background Modes.

Debug sound events¶

Event	iOS	Android
`LOCATION_RECORDED`
`LOCATION_SAMPLE`
`LOCATION_ERROR`
`LOCATION_SERVICES_ON`		n/a
`LOCATION_SERVICES_OFF`		n/a
`STATIONARY_GEOFENCE_EXIT`
`MOTIONCHANGE_FALSE`
`MOTIONCHANGE_TRUE`
`MOTION_TRIGGER_DELAY_START`	n/a
`MOTION_TRIGGER_DELAY_CANCEL`	n/a
`STOP_DETECTION_DELAY_INITIATED`		n/a
`STOP_TIMER_ON`
`STOP_TIMER_OFF`
`HEARTBEAT`
`GEOFENCE_ENTER`
`GEOFENCE_EXIT`
`GEOFENCE_DWELL_START`		n/a
`GEOFENCE_DWELL_CANCEL`		n/a
`GEOFENCE_DWELL`	`GEOFENCE_ENTER` after `GEOFENCE_DWELL_START`
`ERROR`
`WARNING`	n/a
`BACKGROUND_FETCH`		n/a

Warning

Never enable debug in a production build.

logLevel¶

var logLevel:LogLevel

Controls the verbosity of the SDK's internal log.

Defaults to LogLevel.Off. The log is stored in an internal SQLite database and retained for logMaxDays days (default: 3).

Level	Value	Description
LogLevel.Off	0	Disable logging entirely
LogLevel.Error	1	Failures and critical errors
LogLevel.Warning	2	Problems that may affect behaviour
LogLevel.Info	3	Operational milestones (start/stop, HTTP, geofence state)
LogLevel.Debug	4	Granular detail during integration
LogLevel.Verbose	5	Maximum detail; full introspection

Example 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:18.778   🔵  setPace: null → false
09-19 11:12:21.405   ✅  INSERT: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:21.446   ✅  Locked 1 records
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

Warning

Set logLevel to LogLevel.Error or lower before submitting to production. At Verbose, logs can grow to several megabytes over logMaxDays days.

See also - logMaxDays - Logger.getLog - Logger.emailLog - Logger.destroyLog

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    logger.logLevel = LogLevel.VERBOSE
}

logMaxDays¶

var logMaxDays: Int

Number of days to retain log entries in the internal SQLite database.

Defaults to 3 days. Entries older than this limit are purged automatically on a rolling basis.

See also - logLevel - Logger.emailLog

// Within a coroutine scope
val bgGeo = BGGeo.instance
bgGeo.ready {
    logger.logMaxDays = 3
}