Logger
walkerOS provides a centralized logging system that enables consistent logging across the collector, sources, and destinations. The logger supports four log levels and provides scoped logging for better debugging.
Configuration
Configure logging when initializing the collector:
Log levels
| Level | Value | Description |
|---|---|---|
ERROR | 0 | Only errors (default) |
WARN | 1 | Errors and warnings |
INFO | 2 | Errors, warnings, and informational |
DEBUG | 3 | All messages including debug information |
Using the logger
The logger is automatically available in destination and source contexts:
In destinations
In sources
Logger API
Methods
| Method | Description |
|---|---|
error(message, context?) | Log an error message |
warn(message, context?) | Log a warning (degraded state, config issues) |
info(message, context?) | Log an informational message |
debug(message, context?) | Log a debug message |
throw(message, context?) | Log an error and throw an exception (returns never) |
json(data) | Output structured JSON data |
scope(name) | Create a scoped logger with a prefixed scope |
Error handling
The logger accepts Error objects directly and automatically extracts relevant
information:
Boundary error logs
When an exception escapes the inner pipeline of collector.push or
collector.command, the collector emits a structured error log and
increments collector.status.failed. The messages are 'push failed'
and 'command failed' respectively, with the full event/ingest or
command/data context as structured fields. See
Status — What failed counts for details and
PII implications.
Internal pipeline failures from mapping, source startup, transformer
init, and destination init are scoped under 'source',
'transformer:<type>', or the destination type. User-callback throws
from on subscriptions are scoped under 'on'. The full list of error
verbs and scopes is documented in
Status — What failed counts.
Throwing errors
Use logger.throw() to log an error and throw in a single call:
Scoped loggers
Scoped loggers prefix log messages with context information, making it easier to trace logs to their origin:
Custom handler
For advanced use cases like sending logs to external services, configure a custom handler:
The handler receives:
| Parameter | Type | Description |
|---|---|---|
level | Level | Log level enum (ERROR=0, WARN=1, INFO=2, DEBUG=3) |
message | string | The log message |
context | LogContext | Additional context object |
scope | string[] | Array of scope names |
originalHandler | DefaultHandler | The default console handler |
Testing
Use the mock logger utility for testing destinations and sources:
The mock logger provides jest mock functions for all logger methods plus:
scopedLoggers: Array of scoped loggers created viascope()