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.

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:

npx @transistorsoft/loganalyzer background-geolocation.log.gz

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¶

public func debug(_ message: String)

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

let bgGeo = BGGeo.shared
bgGeo.logger.debug("This is a debug message")

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

destroyLog¶

public func destroyLog() async throws

Delete all records from the SDK's log database.

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

let bgGeo = BGGeo.shared
bgGeo.logger.destroyLog()

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¶

public func error(_ message: String)

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

let bgGeo = BGGeo.shared
bgGeo.logger.error("Something BAD")

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

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¶

public func info(_ message: String)

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

let bgGeo = BGGeo.shared
bgGeo.logger.info("Something informative")

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

logLevel¶

public var logLevel:BGGeo.LogLevel

Sets the LoggerConfig.logLevel.

notice¶

public func notice(_ message: String)

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

let bgGeo = BGGeo.shared
bgGeo.logger.notice("A Notice")

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

playSound¶

public func playSound(_ soundId: SystemSoundID)

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. 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

// Not available in native Swift API

warn¶

public func warn(_ message: String)

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

let bgGeo = BGGeo.shared
bgGeo.logger.warn("Something WEIRD")

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

Properties¶

ORDER_ASC¶

public static let ORDER_ASC = 1

Sort-order constant for ascending log queries (oldest first).

ORDER_DESC¶

public static let ORDER_DESC = -1

Sort-order constant for descending log queries (newest first).