LoggerConfig¶

public 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

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.logger.debug = true
    config.logger.logLevel = .verbose
    config.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¶

Disable all logging¶

let bgGeo = BGGeo.shared

bgGeo.config.batchUpdate { config in
    config.logger.logLevel = .off
}

Development profile (maximum visibility)¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.logger.debug = true
    config.logger.logLevel = .verbose
    config.logger.logMaxDays = 7
}

Production profile (quiet & conservative)¶

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.logger.debug = false
    config.logger.logLevel = .info
    config.logger.logMaxDays = 3
}

New compound Config¶

let bgGeo = BGGeo.shared

bgGeo.config.batchUpdate { config in
    config.logger.debug = true
    config.logger.logLevel = .verbose
    config.logger.logMaxDays = 3
}

Members¶

debug¶

public var debug: Bool

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¶

public 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

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.logger.logLevel = .verbose
}

logMaxDays¶

public 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

let bgGeo = BGGeo.shared

bgGeo.ready { config in
    config.logger.logMaxDays = 3
}