Home · Docs · Logging

Logging — mobile_field_service

Single standard for app logs and Couchbase Lite LogSinks. One style everywhere. No console.log in src/ops, src/db, or src/sync.

CBL sink API: Using logs. Travel sample: hooks/startLogging.ts.

TL;DR

1. App code logs through src/log/logger.ts (log.debug|info|warn|error).
2. CBL native logs through LogSinks.setConsole / setFile — never Database.setLogLevel (deprecated; cannot mix with LogSinks).
3. Four app levels: debug, info, warn, error. Production default info.
4. Structured key/value. Message is a stable event name. Fields are pairs, not JSON.stringify(doc).
5. Always "err" + error on failures. Never stringify the error into the message.
6. Never log secrets, PII, document bodies, blobs, session ids, passwords, Bearer tokens, encryption keys, street notes.
7. Configure once at process start (src/db/engine.ts after new CblReactNativeEngine()).

1. App logger (src/log/logger.ts)

Target shape (one JSON line):

{
  ts: number;          // unix seconds (same unit as audit.dt)
  level: 'debug' | 'info' | 'warn' | 'error';
  event: string;       // dotted, stable: mfs.wo.start, mfs.repl.auth_fail
  op?: string;         // catalog name: StartWork, SubmitOrder
  employeeId?: string; // never email/password
  collection?: string;
  docId?: string;      // id only
  durMs?: number;
  err?: string;        // err.message, not stack in production
  errCode?: string | number;
  appVer: string;      // same string as audit.*.ver
}

import { log } from '../log/logger';

log.info('mfs.wo.start', { op: 'StartWork', collection: 'workordersout', docId: outId, durMs });

if (err) {
  log.error('mfs.repl.auth_fail', { op: 'OnReplicatorAuthFailure', err, errCode: 401 });
}

Do

log.info('mfs.order.submit', { op: 'SubmitOrder', docId, syncState: 'ready_to_push' });

Don't

console.log('submitted', JSON.stringify(order));
log.info(`submitted ${id} for ${email}`);
log.info('fail ' + err);

Screens may console.warn only while prototyping; any merged src/ops/* / src/sync/* / src/db/* must use log.

2. Levels

3. Event names

Prefix mfs.. Keep a closed set; add in the same PR as the code.

4. What never to log

Allowed: docId, collection, employeeId, counts, errCode, durMs, syncState, HTTP status.

5. Couchbase Lite LogSinks

Configure immediately after the engine singleton (travel sample does this in initializeDatabase).

Development

import { LogSinks, LogLevel, LogDomain } from 'cbl-reactnative';

await LogSinks.setConsole({
  level: LogLevel.DEBUG,
  domains: [LogDomain.ALL],
});

Production

await LogSinks.setConsole({
  level: LogLevel.INFO,
  domains: [LogDomain.REPLICATOR, LogDomain.NETWORK, LogDomain.DATABASE],
});

VERBOSE / DEBUG + LogDomain.ALL — debug builds only. Official docs: do not ship VERBOSE in production.

Optional file sink for support bundles (LogSinks.setFile). Wrapper lines look like RN ::DEBUG:: database_Open — still no payloads.

Do not call deprecated Database.setLogLevel alongside LogSinks.

App messages can enter the same pipeline with LogSinks.write(LogLevel.WARNING, LogDomain.REPLICATOR, 'session refresh') — still no secrets in that string.

6. Replication errors

Map replicator status.getError() to app logs:

Log code + domain, not the session cookie that failed.

7. Version on every line

appVer is Application.nativeApplicationVersion + nativeBuildVersion (same as audit.*.ver). Operators match a support log to a store build without opening the binary.