Logging | SignalWire

The SDK provides a structured logging system with configurable log levels, formats, colors, and output streams. Configuration is driven by environment variables (see Environment Variables) and can be overridden programmatically.

1 import { Logger, getLogger, setGlobalLogLevel } from '@signalwire/sdk';

Logger

Structured logger that respects global level, format, and color settings. Each Logger has a name and optional bound context data included in every entry.

Parameters

name

stringRequired

Logger name shown in log output (e.g., "AgentBase", "SessionManager").

context

Record<string, unknown>

Optional key-value pairs included in every log entry from this logger.

debug / info / warn / error

Log a message at the given severity level.

msg

stringRequired

The log message.

data

Record<string, unknown>

Optional structured data to include in the log entry.

bind

Create a child logger with additional bound context fields merged into the parent’s context.

context

Record<string, unknown>Required

Key-value pairs to merge into the child logger’s context.

Returns: Logger — A new Logger instance with the merged context.

getLogger

Create or retrieve a cached Logger instance by name.

Parameters

name

stringRequired

Logger name. Instances are cached — calling getLogger('foo') twice returns the same Logger.

Returns

Logger

Example

1 import { getLogger } from '@signalwire/sdk';
2 
3 const log = getLogger('MyAgent');
4 log.info('Agent started', { port: 3000 });
5 log.debug('Processing request', { callId: 'abc-123' });

setGlobalLogLevel

Set the minimum log level for all loggers. Messages below this level are suppressed.

Parameters

level

"debug" | "info" | "warn" | "error"Required

The minimum severity level to emit.

Returns

void

Example

1 import { setGlobalLogLevel } from '@signalwire/sdk';
2 
3 setGlobalLogLevel('debug'); // Show all messages including debug

suppressAllLogs

Suppress or restore all log output globally.

Parameters

suppress

booleanDefaults to true

true to suppress all output, false to restore.

Returns

void

Example

1 import { suppressAllLogs } from '@signalwire/sdk';
2 
3 suppressAllLogs(true); // Silence all logging

setGlobalLogFormat

Set the output format for all loggers.

Parameters

format

"text" | "json"Required

"text" for human-readable output with colors, "json" for structured JSON entries.

Returns

void

Example

1 import { setGlobalLogFormat } from '@signalwire/sdk';
2 
3 setGlobalLogFormat('json'); // Structured JSON output for log aggregators

setGlobalLogColor

Enable or disable ANSI color codes in text-format output.

Parameters

enabled

booleanRequired

true to enable colors, false to disable.

Returns

void

Example

1 import { setGlobalLogColor } from '@signalwire/sdk';
2 
3 setGlobalLogColor(false); // Disable colors for CI/CD pipelines

setGlobalLogStream

Set the output stream for all loggers.

Parameters

stream

"stdout" | "stderr"Required

The output stream to use.

Returns

void

Example

1 import { setGlobalLogStream } from '@signalwire/sdk';
2 
3 setGlobalLogStream('stderr'); // Route all logs to stderr

resetLoggingConfiguration

Reset all logging settings to their environment-variable-based defaults and clear the logger cache.

Parameters

None.

Returns

void

Example

1 import { resetLoggingConfiguration } from '@signalwire/sdk';
2 
3 resetLoggingConfiguration();

getExecutionMode

Detect the execution environment by inspecting well-known environment variables.

Parameters

None.

Returns

[string, 'off' | 'stderr' | 'default'] — A tuple of [environment_name, derived_log_mode].

Environment	Detection	Log Mode
CGI	`GATEWAY_INTERFACE`	`off`
AWS Lambda	`AWS_LAMBDA_FUNCTION_NAME` or `LAMBDA_TASK_ROOT`	`stderr`
Google Cloud Functions	`FUNCTION_TARGET` or `K_SERVICE`	`default`
Azure Functions	`AZURE_FUNCTIONS_ENVIRONMENT` or `FUNCTIONS_WORKER_RUNTIME`	`default`
Server (default)	No match	`default`

Example

1 import { getExecutionMode } from '@signalwire/sdk';
2 
3 const [env, mode] = getExecutionMode();
4 console.log(`Running in ${env} environment (log mode: ${mode})`);