Logger¶

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

const Logger = BackgroundGeolocation.logger;
const 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.

const Logger = BackgroundGeolocation.logger;
const log = await Logger.getLog({
  start: Date.parse("2019-10-21 13:00"),
  end:   Date.parse("2019-10-22"),
  order: Logger.ORDER_ASC,
  limit: 100
});

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

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

Examples¶

const Logger = BackgroundGeolocation.logger;
const log = await Logger.getLog();
console.log("[log]", log);

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

const Logger = BackgroundGeolocation.logger;
await Logger.emailLog("support@example.com", {
  start: Date.parse("2019-09-19"),
  end:   Date.parse("2019-09-20"),
  order: Logger.ORDER_ASC
});

Fetch and display the full log¶

const Logger = BackgroundGeolocation.logger;
const log = await Logger.getLog();
console.log("[log]", log);

Upload log to your server¶

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

Email log with a date range¶

const Logger = BackgroundGeolocation.logger;
await Logger.emailLog("support@example.com", {
  start: Date.parse("2019-09-19"),
  end:   Date.parse("2019-09-20"),
  order: Logger.ORDER_ASC
});

Methods¶

debug¶

debug(message: string): void;

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

BackgroundGeolocation.logger.debug("This is a debug message");

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

destroyLog¶

destroyLog(): Promise<void>;

Delete all records from the SDK's log database.

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

await BackgroundGeolocation.logger.destroyLog();

emailLog¶

emailLog(email: string, query?:SQLQuery): Promise<boolean | void>;

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

const Logger = BackgroundGeolocation.logger;
await Logger.emailLog("foo@bar.com");

// Constrain by date range
await Logger.emailLog("foo@bar.com", {
  start: Date.parse("2019-09-19"),
  end:   Date.parse("2019-09-20"),
  order: Logger.ORDER_ASC,
  limit: 1000
});

error¶

error(message: string): void;

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

BackgroundGeolocation.logger.error("Something BAD");

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

getLog¶

getLog(query?:SQLQuery): Promise<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

// Fetch all logs
const log = await BackgroundGeolocation.logger.getLog();
console.log("[log]", log);

// Constrain by date range
const Logger = BackgroundGeolocation.logger;
const log = await Logger.getLog({
  start: Date.parse("2019-09-19 11:12"),
  end:   Date.parse("2019-09-19 11:13"),
  order: Logger.ORDER_ASC,
  limit: 100
});

info¶

info(message: string): void;

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

BackgroundGeolocation.logger.info("Something informative");

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

notice¶

notice(message: string): void;

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

BackgroundGeolocation.logger.notice("A Notice");

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

uploadLog¶

uploadLog(url: string, query?:SQLQuery): Promise<boolean | void>;

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

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

// Constrain by date range
await BackgroundGeolocation.logger.uploadLog(
  "https://my.server.com/users/123/logs",
  { start: Date.parse("2019-10-20 09:00"), end: Date.parse("2019-10-20 11:59") }
);

warn¶

warn(message: string): void;

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

BackgroundGeolocation.logger.warn("Something WEIRD");

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

Properties¶

ORDER_ASC¶

ORDER_ASC: 1;

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

ORDER_DESC¶

ORDER_DESC: -1;

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