react-native-background-geolocation@5.0.0-beta.1
    Preparing search index...

    Interface LoggerConfig

    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 (soundFX, notifications), and how long logs are retained on the device.

    Configure via: config.logger

    BackgroundGeolocation.ready({
      logger: {
        debug: true,
        logLevel: LogLevel.Verbose,
        logMaxDays: 7,
      }
    });

    Overview

    Logging serves two major purposes:

    1. Development & QA
      High-verbosity logs and optional audible soundFX make debugging intuitive. You can hear when locations are recorded, when motion changes occur, and when geofences trigger — without watching the console.

    2. Production diagnostics
      Lower verbosity preserves essential operational traces without excessive storage use or privacy impact.

    See also: Config.logger

    Area Keys Notes
    Verbosity logLevel off → verbose
    Debug aids debug Enables audible soundFX & debug indicators
    Retention logMaxDays Rolling on-device TTL

    Log Levels

    Choose the level appropriate for your environment:

    Level Value Description
    LogLevel.Off 0 Disable logging entirely
    LogLevel.Error 1 Failures & critical errors
    LogLevel.Warning 2 Problems that may affect behavior
    LogLevel.Info 3 Operational milestones (start/stop, HTTP, geofence state)
    LogLevel.Debug 4 Granular detail during integration
    LogLevel.Verbose 5 Maximum detail; full introspection

    SoundFX and debug indicators require debug = true.

    Debug Behavior

    When debug: true, the SDK plays short, distinct soundFX when key events occur:

    • Location recorded
    • Location error
    • onMotionChange transitions
    • Geofence enter / exit / dwell

    It may also show temporary developer notifications (Android) to visualize state transitions and background operation.

    ⚠️ Never enable debug in production.

    Retention

    Use logMaxDays to control how long logs remain on device. Old entries are purged automatically on a rolling basis.

    Recommended:

    • Development: 5–7 days
    • Production: 1–3 days

    Retrieving Logs

    // Retrieve full log as a string
    const log = await BackgroundGeolocation.logger.getLog({});

    // Email the log as an attachment
    await BackgroundGeolocation.logger.emailLog("support@yourcompany.com");

    Logs include:

    • SQLite-backed diagnostic history
    • Event traces
    • HTTP upload events
    • Configuration transitions

    See also: logMaxDays, logLevel

    Examples

    1) Development profile (maximum visibility)

    BackgroundGeolocation.ready({
      logger: {
        debug: true,
        logLevel: LogLevel.Verbose,
        logMaxDays: 7,
      }
    });

    2) Production profile (quiet & conservative)

    BackgroundGeolocation.ready({
      logger: {
        debug: false,
        logLevel: LogLevel.Info,
        logMaxDays: 3,
      }
    });

    3) Disable all logging

    BackgroundGeolocation.setConfig({
      logger: {
        logLevel: LogLevel.Off,
      }
    });

    Migration from legacy flat Config

    Legacy:

    Config({
      debug: true,
      logLevel: LogLevel.Verbose,
      logMaxDays: 3,
    });

    New (compound):

    Config({
      logger: {
        debug: true,
        logLevel: LogLevel.Verbose,
        logMaxDays: 3,
      }
    });

    Legacy keys are still supported (deprecated), but the compound form is recommended.

    Recommendations

    • Use Verbose + debug: true during active development.
    • Use Info or Warning in production.
    • Do not set Off unless required — logs are invaluable for field diagnostics.
    interface LoggerConfig {
        debug?: boolean;
        logLevel?: LogLevel;
        logMaxDays?: number;
    }
    Index

    Properties

    debug? logLevel? logMaxDays?

    Properties

    debug?: boolean

    Configure the plugin to emit sound effects and local-notifications during development.

    Defaults to false. When set to true, the plugin will emit debugging sounds and notifications for life-cycle events of [[BackgroundGeolocation | BackgroundGeolocation]].

    In you wish to hear debug sounds in the background, you must manually enable the background-mode:

    [x] Audio and Airplay background mode in Background Capabilities of XCode.

    Event iOS Android
    LOCATION_RECORDED
    LOCATION_SAMPLE
    LOCATION_ERROR
    LOCATION_SERVICES_ON n/a
    LOCATION_SERVICES_OFF n/a
    STATIONARY_GEOFENCE_EXIT
    MOTIONCHANGE_FALSE
    MOTIONCHANGE_TRUE
    MOTION_TRIGGER_DELAY_START n/a
    MOTION_TRIGGER_DELAY_CANCEL n/a
    STOP_DETECTION_DELAY_INITIATED n/a
    STOP_TIMER_ON
    STOP_TIMER_OFF
    HEARTBEAT
    GEOFENCE_ENTER
    GEOFENCE_EXIT
    GEOFENCE_DWELL_START n/a
    GEOFENCE_DWELL_CANCEL n/a
    GEOFENCE_DWELL GEOFENCE_ENTER after GEOFENCE_DWELL_START
    ERROR
    WARNING n/a
    BACKGROUND_FETCH n/a
    logLevel?: LogLevel

    Controls the volume of recorded events in the plugin's logging database.

    BackgroundGeolocation contains powerful logging features. By default, the plugin starts with LogLevel.Off, storing logMaxDays days worth of logs in its internal SQLite database (default: 3).

    The following log levels are defined as constants on BackgroundGeolocation:

    Label Value
    LogLevel.Off 0
    LogLevel.Error 1
    LogLevel.Warning 2
    LogLevel.Info 3
    LogLevel.Debug 4
    LogLevel.Verbose 5

    Example log data

    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 [c.t.l.BackgroundGeolocationService d]
09-19 11:12:18.723   ✅  Started in foreground
09-19 11:12:18.737 [c.t.l.ActivityRecognitionService a]
09-19 11:12:18.737   🎾  Start activity updates: 10000
09-19 11:12:18.761 [c.t.l.BackgroundGeolocationService k]
09-19 11:12:18.761   🔴  Stop heartbeat
09-19 11:12:18.768 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.768   🎾  Start heartbeat (60)
09-19 11:12:18.778 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.778   🔵  setPace: null → false
09-19 11:12:18.781 [c.t.l.adapter.TSConfig c] ℹ️   Persist config
09-19 11:12:18.794 [c.t.locationmanager.util.b a]
09-19 11:12:18.794   ℹ️  LocationAuthorization: Permission granted
09-19 11:12:18.842 [c.t.l.http.HttpService flush]
09-19 11:12:18.842 ╔═════════════════════════════════════════════
09-19 11:12:18.842 ║ HTTP Service
09-19 11:12:18.842 ╠═════════════════════════════════════════════
09-19 11:12:19.000 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)
09-19 11:12:21.314 [c.t.l.l.SingleLocationRequest$2 onLocationResult]
09-19 11:12:21.314 ╔═════════════════════════════════════════════
09-19 11:12:21.314 ║ SingleLocationRequest: 1
09-19 11:12:21.314 ╠═════════════════════════════════════════════
09-19 11:12:21.314 ╟─ 📍  Location[fused 45.519239,-73.617058 hAcc=15]999923706055 vAcc=2 sAcc=??? bAcc=???
09-19 11:12:21.327 [c.t.l.l.TSLocationManager onSingleLocationResult]
09-19 11:12:21.327   🔵  Acquired motionchange position, isMoving: false
09-19 11:12:21.342 [c.t.l.l.TSLocationManager a] 15.243
09-19 11:12:21.405 [c.t.locationmanager.data.a.c persist]
09-19 11:12:21.405   ✅  INSERT: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:21.423 [c.t.l.http.HttpService flush]
09-19 11:12:21.423 ╔═════════════════════════════════════════════
09-19 11:12:21.423 ║ HTTP Service
09-19 11:12:21.423 ╠═════════════════════════════════════════════
09-19 11:12:21.446 [c.t.locationmanager.data.a.c first]
09-19 11:12:21.446   ✅  Locked 1 records
09-19 11:12:21.454 [c.t.l.http.HttpService a]
09-19 11:12:21.454   🔵  HTTP POST: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:22.083 [c.t.l.http.HttpService$a onResponse]
09-19 11:12:22.083   🔵  Response: 200
09-19 11:12:22.100 [c.t.locationmanager.data.a.c destroy]
09-19 11:12:22.100   ✅  DESTROY: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:55.226 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)

    BackgroundGeolocation.ready({
      logger: {
        logLevel: LogLevel.Verbose
      },
    });

    See also

    ⚠️ Warning When submitting your app to production, configure logLevel appropriately (for example, LogLevel.Error), since logs can grow to several megabytes over logMaxDays.

    logMaxDays?: number

    Maximum number of days to persist a log-entry in database.

    Defaults to 3 days.

    BackgroundGeolocation.ready({
      logger: {
        logMaxDays: 3
      }
    });

    See also:

    Settings

    Member Visibility

    On This Page

    Properties