Logger

A structured, level-aware logging system with history tracking, custom transports, tagged sub-loggers, and deep integration with the Aura event bus. Access it through Aura.log.

Quick Start

Start logging immediately. Messages are printed to the console, stored in history, and optionally emitted as events.

js
Aura.log.info('App started');
Aura.log.debug('Loading config', { env: 'production' });
Aura.log.warn('Cache miss', '/api/users');
Aura.log.error('Failed to connect', err);

// Set minimum level to suppress debug messages
Aura.log.setLevel('warn');

// Create a tagged sub-logger
const db = Aura.log.tag('DB');
db.info('Connected'); // [INFO][DB] Connected

Log Levels

The logger uses five ordered levels. When you set a minimum level, all messages below that threshold are silently discarded.

Level	Priority	Description
debug	0	Verbose diagnostics. Disabled in production.
info	1	General operational messages.
warn	2	Potential issues that deserve attention.
error	3	Failures that need immediate action.
silent	4	Suppresses all output. Nothing is logged.

setLevel()

Sets the minimum log level. Any message with a level below this threshold is ignored.

Aura.log.setLevel(level: LogLevel): void

Param	Type	Description
level	'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'	The minimum level to allow.

js
// Only show warnings and errors
Aura.log.setLevel('warn');

Aura.log.debug('This is hidden');  // suppressed
Aura.log.info('This is hidden');   // suppressed
Aura.log.warn('This is visible');  // printed
Aura.log.error('This is visible'); // printed

// Silence everything
Aura.log.setLevel('silent');

getLevel()

Returns the current minimum log level.

Aura.log.getLevel(): LogLevel

js
console.log(Aura.log.getLevel()); // 'debug' (default)

setMaxHistory()

Sets the maximum number of log entries kept in memory. When the limit is exceeded, the oldest entry is dropped. The default is 500.

Aura.log.setMaxHistory(max: number): void

Param	Type	Description
max	number	Maximum number of history entries to retain.

js
// Keep only the last 100 entries
Aura.log.setMaxHistory(100);

debug()

Logs a message at the debug level. Accepts optional extra data arguments that are passed through to the console and stored in history.

Aura.log.debug(message: string, ...data: unknown[]): void

Param	Type	Description
message	string	The log message.
...data	unknown[]	Optional additional data to attach.

js
Aura.log.debug('Render cycle', { component: 'Header', ms: 12 });

info()

Logs a message at the info level.

Aura.log.info(message: string, ...data: unknown[]): void

Param	Type	Description
message	string	The log message.
...data	unknown[]	Optional additional data to attach.

js
Aura.log.info('User signed in', { userId: 42 });

warn()

Logs a message at the warn level.

Aura.log.warn(message: string, ...data: unknown[]): void

Param	Type	Description
message	string	The log message.
...data	unknown[]	Optional additional data to attach.

js
Aura.log.warn('Deprecated method called', 'use fetchV2() instead');

error()

Logs a message at the error level.

Aura.log.error(message: string, ...data: unknown[]): void

Param	Type	Description
message	string	The log message.
...data	unknown[]	Optional additional data to attach.

js
try {
  await riskyOperation();
} catch (err) {
  Aura.log.error('Operation failed', err);
}

tag()

Creates a tagged sub-logger. Every message from the returned logger is automatically prefixed with the given tag in the console output and stored with the tag in history.

Aura.log.tag(name: string): TaggedLogger

Param	Type	Description
name	string	The tag label to prefix on all messages.

Returns a TaggedLogger with debug(), info(), warn(), and error() methods.

js
const api = Aura.log.tag('API');
api.info('GET /users');       // [INFO][API] GET /users
api.error('500 response');    // [ERROR][API] 500 response

const ws = Aura.log.tag('WebSocket');
ws.debug('Frame received');   // [DEBUG][WebSocket] Frame received

Tagged Loggers

Tagged loggers share the same level filter, history buffer, transports, and event emitter as the parent logger. They simply add a tag field to each LogEntry they produce. This makes it easy to filter history or transport output by subsystem.

js
const router = Aura.log.tag('Router');
const auth   = Aura.log.tag('Auth');

router.info('Navigate to /dashboard');
auth.warn('Token expiring soon');

// Filter history by tag
const authLogs = Aura.log.getHistory().filter(e => e.tag === 'Auth');

addTransport()

Registers a custom transport function that is called for every log entry that passes the level filter. Returns an unsubscribe function to remove the transport later.

Aura.log.addTransport(transport: (entry: LogEntry) => void): () => void

Param	Type	Description
transport	(entry: LogEntry) => void	A function that receives each `LogEntry`.

The LogEntry object contains:

Property	Type	Description
level	LogLevel	One of `'debug'`, `'info'`, `'warn'`, `'error'`.
message	string	The log message.
data	unknown[]	Extra data arguments.
timestamp	number	Unix timestamp in milliseconds (`Date.now()`).
tag	string?	Optional tag from a tagged logger.

js
// Send errors to an external service
const remove = Aura.log.addTransport((entry) => {
  if (entry.level === 'error') {
    fetch('/api/logs', {
      method: 'POST',
      body: JSON.stringify(entry),
    });
  }
});

// Later, remove the transport
remove();

Custom Transports

Transports are plain functions, so you can build any pipeline you need. Errors thrown inside a transport are silently caught to avoid breaking the logging flow.

js
// Store logs in IndexedDB
Aura.log.addTransport(async (entry) => {
  await Aura.idb.set('logs', {
    ...entry,
    date: new Date(entry.timestamp).toISOString(),
  });
});

// Format and write to a DOM element
Aura.log.addTransport((entry) => {
  const el = document.getElementById('log-output');
  if (!el) return;
  const line = `[${entry.level.toUpperCase()}] ${entry.message}\n`;
  el.textContent += line;
});

getHistory()

Returns a copy of the log history array. Optionally pass a level to filter entries — only entries at or above that level are returned.

Aura.log.getHistory(level?: LogLevel): LogEntry[]

Param	Type	Description
level	LogLevel?	Optional. If provided, only entries at or above this level are included.

js
// All history
const all = Aura.log.getHistory();

// Only warnings and errors
const issues = Aura.log.getHistory('warn');

console.log(`${issues.length} issues found`);

clearHistory()

Clears all stored log history.

Aura.log.clearHistory(): void

js
Aura.log.clearHistory();
console.log(Aura.log.getHistory().length); // 0

export()

Serializes the log history to a formatted JSON string. Optionally filter by level, the same way getHistory() does.

Aura.log.export(level?: LogLevel): string

Param	Type	Description
level	LogLevel?	Optional minimum level filter.

js
// Export all logs as JSON
const json = Aura.log.export();

// Export only errors
const errors = Aura.log.export('error');

// Download as a file
const blob = new Blob([json], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'logs.json';
a.click();

Events Integration

When Aura's event system is connected, every log entry automatically emits events on the Aura event bus. This lets other parts of your app react to log messages without importing the logger directly.

Emitted Events

Event	Payload	Description
log:debug	LogEntry	Fired for every debug-level message.
log:info	LogEntry	Fired for every info-level message.
log:warn	LogEntry	Fired for every warn-level message.
log:error	LogEntry	Fired for every error-level message.
log:*	LogEntry	Fired for every message, regardless of level.

js
// Listen for all error-level logs via the event bus
Aura.on('log:error', (entry) => {
  showToast(`Error: ${entry.message}`);
});

// Listen for any log message
Aura.on('log:*', (entry) => {
  appendToDevPanel(entry);
});

// These fire the events automatically
Aura.log.error('Connection lost');  // triggers log:error + log:*
Aura.log.info('Reconnecting...');  // triggers log:info  + log:*