logger property

Logging / Diagnostics Configuration

The LoggerConfig group controls diagnostic logging for the SDK. Use it to adjust how much information is written to the internal log, whether to enable developer-friendly debug aids such as audible feedback, and how long logs are retained on the device.

Overview

Logging serves two purposes:

1. Development & QA: High-verbosity logs and optional debug soundFX help you verify configuration, observe lifecycle transitions, and confirm that events (such as location updates or geofences) are firing as expected.
2. Production diagnostics: Lower verbosity with conservative retention preserves meaningful traces while minimizing storage and privacy impact.

Configure LoggerConfig via Config.logger.

Log levels

Choose the level that matches your environment:

Debug behavior

When LoggerConfig.debug is true, the SDK provides audible soundFX cues and other developer-focused feedback to make debugging immediate and intuitive. Each key lifecycle and event trigger plays a distinct tone, including:

• Location recorded ✅
• Location error ⚠️
• onMotionChange (stationary ↔ moving)
• onGeofence (enter / exit / dwell)

These soundFX, controlled by LoggerConfig.debug, are invaluable when testing without looking at console output—particularly during field tests. In addition to audible cues, the plugin may display extra system notifications or toast messages to visualize state changes and activity transitions.

Important: Enable LoggerConfig.debug only during development and QA. In production, users should never hear these sounds or see debug notifications.

Retention

LoggerConfig.logMaxDays sets how many days of logs to keep on-device. Older entries are purged automatically on a rolling basis. Use shorter retention in production and longer retention when investigating field issues.

Retrieving Logs

You can retrieve or share log data for debugging or customer support using BackgroundGeolocation.log and BackgroundGeolocation.emailLog.

// Retrieve the current log as a String.
String log = await BackgroundGeolocation.log;
print(log);

// Email the current log (saves a file attachment).
await BackgroundGeolocation.emailLog('support@yourcompany.com');

The emailed log includes the SQLite-backed log database contents and diagnostic information useful for debugging or support cases.

See also:

• LoggerConfig.logMaxDays for controlling how long logs are retained.
• LoggerConfig.logLevel for controlling verbosity.

Examples

1) Development profile (maximum visibility)

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

final config = bg.Config(
  logger: bg.LoggerConfig(
    debug: true,
    logLevel: bg.LoggerConfig.LOG_LEVEL_VERBOSE,
    logMaxDays: 7,
  ),
);
await bg.BackgroundGeolocation.ready(config);

2) Production profile (quiet and conservative)

final config = bg.Config(
  logger: bg.LoggerConfig(
    debug: false,
    logLevel: bg.LoggerConfig.LOG_LEVEL_INFO,
    logMaxDays: 3,
  ),
);
await bg.BackgroundGeolocation.ready(config);

3) Disable all logging

await bg.BackgroundGeolocation.setConfig(bg.Config(
  logger: bg.LoggerConfig(
    logLevel: bg.LoggerConfig.LOG_LEVEL_OFF,
  ),
));

Migration from legacy flat Config

Previously, logging options were defined directly on Config:

// Legacy
Config(
  debug: true,
  logLevel: Config.LOG_LEVEL_VERBOSE,
  logMaxDays: 3,
);

They are now grouped under LoggerConfig via Config.logger:

// New
Config(
  logger: LoggerConfig(
    debug: true,
    logLevel: LoggerConfig.LOG_LEVEL_VERBOSE,
    logMaxDays: 3,
  ),
);

Legacy keys remain available but are marked @Deprecated. Prefer the compound form going forward.

Recommendations

• Use verbose + LoggerConfig.debug: true during active development.
• Drop to info (or warning) and set a short LoggerConfig.logMaxDays in production.
• Avoid off unless absolutely necessary; even minimal logs are invaluable when diagnosing field issues.