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.

final log = await Logger.getLog();

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.

final log = await Logger.getLog();

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`	🔵

BackgroundGeolocation.onLocation((Location location) {
  Logger.debug("Location received: " + location.uuid);
});

Examples¶

final log = await Logger.getLog();
print('[log] ${log}');

await Logger.uploadLog(
  "https://my.server.com/users/123/logs"
);

await Logger.emailLog("support@example.com");

Fetch and display the full log¶

final log = await Logger.getLog();
print('[log] ${log}');

Upload log to your server¶

await Logger.uploadLog(
  "https://my.server.com/users/123/logs"
);

Email log with a date range¶

await Logger.emailLog("support@example.com");

Members¶

debug¶

static Future<void> debug(String msg)

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

Logger.debug("This is a debug message");

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

destroyLog¶

static Future<bool> destroyLog()

Delete all records from the SDK's log database.

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

Logger.destroyLog();

emailLog¶

static Future<bool> emailLog(String email, [SQLQuery? query])

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

Logger.emailLog('foo@bar.com').then((bool success) {
  print('[emailLog] success');
}).catchError((error) {
  print('[emailLog] FAILURE: ${error}');
});

// Or constrain results by providing a [SQLQuery]:
Logger.emailLog('foo@bar.com', SQLQuery(
  start: DateTime.parse('2019-10-20 09:00'),
  end: DateTime.parse('2019-10-20 11:59')
)).then((bool success) {
  print('[emailLog] success');
}).catchError((error) {
  print('[emailLog] FAILURE: ${error}');
});

error¶

static Future<void> error(String msg)

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

Logger.error("Something BAD");

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

getLog¶

static Future<String> getLog([SQLQuery? query])

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

// Fetch entire contents of log.
String log = await Logger.getLog();
// Warning:  this string could be several megabytes.
print('[log] success: ${log}');

// Or constrain results between optionl start/end dates using a SQLQuery
String log = await Logger.getLog(SQLQuery(
  start: DateTime.parse('2019-10-21 13:00'),  // <-- optional HH:mm:ss
  end: DateTime.parse('2019-10-22')
));

// Or just a start date
String log = await Logger.getLog(SQLQuery(
  start: DateTime.parse('2019-10-21 13:00')
));

// Or just an end date
String log = await Logger.getLog(SQLQuery(
  end: DateTime.parse('2019-10-21')
));

info¶

static Future<void> info(String msg)

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

Logger.info("Something informative");

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

notice¶

static Future<void> notice(String msg)

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

Logger.notice("A Notice");

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

uploadLog¶

static Future<bool> uploadLog(String url, [SQLQuery? query])

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

Logger.uploadLog('https://my.server.com/users/123/logs').then((bool success) {
  print('[uploadLog] success');
}).catchError((error) {
  print('[uploadLog] FAILURE: ${error}');
});

// Or constrain results by providing a [SQLQuery]:
Logger.uploadLog('https://my.server.com/users/123/logs', SQLQuery(
  start: DateTime.parse('2019-10-20 09:00'),
  end: DateTime.parse('2019-10-20 11:59')
)).then((bool success) {
  print('[uploadLog] success');
}).catchError((error) {
  print('[uploadLog] FAILURE: ${error}');
});

warn¶

static Future<void> warn(String msg)

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

Logger.warn("Something WEIRD");

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