Logging Good Practices

Overview

• Which log level to use in each situation
• How to write a useful log message
• TAG naming rules
• What not to log (security and performance)
• Examples of good and bad log statements

Log levels

Production default is ERROR only. When a customer shares a log, you will see ERROR and WARN lines. INFO is also always visible. If you want a statement to appear in a default support log, it must be log.e, log.w, or log.i.

One-shot variants

// fires once per session even if called repeatedly
log.wOnce(TAG, 'Page size exceeds 50 — consider reducing for offline sync performance');
Copy to clipboardCopied!

Choosing the right level

Use log.e when

• An exception is caught and the operation cannot complete
• A required configuration key is missing and the feature will not work
• An OIDC/auth callback returns an unexpected response
• A SQLite statement fails and data was not saved

// ✅ correct — save failed, data lost
try {
  await datasource.save();
} catch (err) {
  log.e(TAG, 'save failed for workorder ' + wonum, err);
  throw err;
}
Copy to clipboardCopied!

Use log.w when

• A fallback path was taken (e.g. silent token refresh failed, fell through to manual login)
• A configuration value was missing but a default was applied
• A non-critical resource (image, attachment) could not be loaded
• A slow request completed but exceeded the performance threshold
• A retry is about to happen

// ✅ correct — degraded path, app continues
if (!tokenValid) {
  log.w(TAG, 'generateToken failed — falling back to manual login');
}
Copy to clipboardCopied!

Use log.i when

• A user-visible lifecycle milestone completes: login started, login succeeded, sync complete, logout
• The auth path selected (loginType, isServerAuthenticated) — essential for support
• A long-running operation starts or finishes (data download, schema load)
• App version or configuration is read on startup

// ✅ correct — production-visible, one line, no noise
log.i(TAG, 'loginType', loginType);
log.i(TAG, 'isServerAuthenticated', isServerAuthenticated);
Copy to clipboardCopied!

Use log.d when

• Logging the parameters of a query or request
• Timing a sub-operation (SQL query time, fetch time)
• Logging the count of records received per page

// ✅ correct — debug only
log.d(TAG, 'performLoad query:', JSON.stringify(query));
log.d(TAG, 'page ' + pageno + ' received ' + records.length + ' records in ' + timeDiff + 'ms');
Copy to clipboardCopied!

Use log.t when

• Inside a loop body (per-record processing)
• In Cordova event callbacks (loadstop, loadstart, exit)
• In cryptographic helper functions
• Any message that fires more than once per user action

// ✅ correct — per-iteration, trace only
records.forEach(record => {
  log.t(TAG, 'processing record', record.href);
});
Copy to clipboardCopied!

TAG naming

Rules

1. Declare TAG as a module-level constant — never inline a string in a log call.
2. Format: framework + '-' + ClassName for framework code, appId + '-' + ClassName for app code.
3. Use the existing TAG constants from adjacent files — do not invent new formats.

// ✅ correct
import {framework} from '../../Constants';
const TAG = framework + '-DisconnectedDataAdapter';

log.e(TAG, 'Load Error', e);
Copy to clipboardCopied!

// ❌ wrong — inline string, no consistency
log.e('MyModule', 'something failed');
Copy to clipboardCopied!

Proposed renames

Message format

Do

• Start with a verb — 'Load failed', 'Token refresh succeeded', 'Schema not found for'
• Include the key identifier — record href, datasource name, object structure, username (hashed/partial only)
• Include timing when relevant — 'sync completed in ' + elapsed + 'ms'
• Pass the error object as the last argument — log.e(TAG, 'Save failed', err) — the framework serialises it

// ✅ good messages
log.e(TAG, 'Save failed for datasource ' + datasourceId, err);
log.w(TAG, 'login: server auth failed for loginType ' + loginType + ' — returning false');
log.i(TAG, 'sync complete — ' + records + ' records in ' + elapsed + 'ms');
Copy to clipboardCopied!

Do not

• Do not log raw sensitive data — passwords, access tokens, refresh tokens, full cookie values, PII
• Do not log large objects with JSON.stringify at INFO or above — this serialises entire datasource state and floods the log
• Do not use console.log — use log.d or log.t instead; console.log bypasses the level filter and appears in every log
• Do not leave unsubstituted format strings — 'Field %s not found' with no argument passed is a known existing issue; do not add new ones

// ❌ wrong — logs raw token
log.d(TAG, 'access_token', accessToken);

// ✅ correct — log presence only
log.d(TAG, 'access_token obtained');

// ❌ wrong — large object serialisation at INFO
log.i(TAG, 'datasource state:', JSON.stringify(datasource));

Copy to clipboardCopied!

Auth lifecycle — required log statements

Sync lifecycle — required log statements

Common anti-patterns

Silent return false

// ❌ wrong — completely silent failure
if (!isServerAuthenticated && loginType === LOGIN_TYPE_FIRSTUSER) {
  return false;
}

// ✅ correct
if (!isServerAuthenticated && loginType === LOGIN_TYPE_FIRSTUSER) {
  log.w(TAG, 'login: server auth failed for loginType ' + loginType + ' — returning false');
  return false;
Copy to clipboardCopied!

Swallowed catch with wrong level

// ❌ wrong — network error during token refresh logged at INFO, missed by support
} catch (err) {
  log.i(TAG, 'generateToken error', err);
}

// ✅ correct
} catch (err) {
  log.w(TAG, 'generateToken failed — will fall through to manual login:', err);
}
Copy to clipboardCopied!

High-volume log at INFO

// ❌ wrong — fires 200 times per sync page, floods log
records.forEach(record => {
  log.i(TAG, 'processing record', record.href);
});

// ✅ correct
records.forEach(record => {
  log.t(TAG, 'processing record', record.href);
});
Copy to clipboardCopied!

PR checklist

• Every new catch block has at least a log.w or log.e
• No silent return false without a preceding log.w
• No console.log calls — use log.d or log.t
• No sensitive data (tokens, passwords, PII) in any log message
• TAGs declared as module-level constants
• High-volume loop/callback logs use log.t not log.i/log.d
• One-shot warnings use log.wOnce / log.eOnce