logger property

  1. @override
LoggerConfig get logger
override

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.

Area Keys Notes
Verbosity LoggerConfig.logLevel off, error, warning, info, debug, verbose.
Debug aids LoggerConfig.debug Enables audible and visual developer feedback.
Retention LoggerConfig.logMaxDays Rolling window of on-device logs.

Log levels

Choose the level that matches your environment:

Level Value Typical use
off 0 Disable logging entirely.
error 1 Only failures and critical errors.
warning 2 Errors + warnings about potential problems.
info 3 Operational milestones (start/stop, schedule changes, HTTP outcomes).
debug 4 Adds granular detail helpful during integration.
verbose 5 Maximum detail; best for deep troubleshooting.

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:

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.

Implementation

@override
LoggerConfig get logger => super.logger ?? const LoggerConfig();