Logger

Robo.js includes a built-in logger that provides structured output, custom log levels, child loggers, and integration with the /dev commands and error replies. While console.log works, the logger offers additional capabilities for debugging and monitoring.

Using the Logger

Import the global logger instance:

import { logger } from 'robo.js'

logger.info('Hello World!')

import { logger } from 'robo.js'

logger.info('Hello World!')

Creating a Logger

You can create a new Logger instance with custom settings:

import { Logger } from 'robo.js'

const customLogger = new Logger({
	level: 'debug',
	prefix: 'DiscordLogger',
	maxEntries: 200 // Default: 100
})

import { Logger } from 'robo.js'

const customLogger = new Logger({
	level: 'debug',
	prefix: 'DiscordLogger',
	maxEntries: 200 // Default: 100
})

Note: In most cases, use the default logger instance provided by Robo.js rather than creating your own.

Log Methods

The logger provides methods for different severity levels:

logger.debug('Debugging message')
logger.info('Info message')
logger.warn('Warning message')
logger.error('Error message')
logger.log('3rd Party message')
logger.event('Event Patched message')

logger.debug('Debugging message')
logger.info('Info message')
logger.warn('Warning message')
logger.error('Error message')
logger.log('3rd Party message')
logger.event('Event Patched message')

The configured log level determines which messages appear in output.

Log Levels

Level	Description
`trace`	Very detailed debugging messages
`debug`	Debugging messages
`info`	Informational messages
`wait`	Waiting/pending operation messages
`other`	Third-party or uncategorized output
`event`	Event-related messages
`ready`	Ready/startup messages
`warn`	Warning messages
`error`	Error messages

The default level is info.

Changing Log Level

Update the log level at runtime by calling logger() with new options:

logger({ level: 'debug' })

logger({ level: 'debug' })

Child Loggers

Create namespaced child loggers with logger.fork() to identify the source of log output:

const dbLogger = logger.fork('database')
dbLogger.info('Connection initiated!')

const dbLogger = logger.fork('database')
dbLogger.info('Connection initiated!')

All output from dbLogger is prefixed with database, making it easy to filter logs by component. This is particularly useful in plugins and modules.

Flushing Logs

Manually flush pending log writes:

await logger.flush()

await logger.flush()

This ensures all buffered writes complete before proceeding.

Retrieving Recent Logs

Access recent log entries from the logger's buffer:

const recentLogs = logger.getRecentLogs()

const recentLogs = logger.getRecentLogs()

Specify a count to limit the number of entries returned:

const recent20Logs = logger.getRecentLogs(20) // Default: 25

const recent20Logs = logger.getRecentLogs(20) // Default: 25

Custom Drains

A drain is a target where log output is sent. By default, logs go to the console. You can configure custom drains to redirect output to external logging services or files.

Note: The official @robojs/better-stack plugin forwards logs to Better Stack Logs for searchable, centralized logging.

Setting a Custom Drain

Using setDrain():

import { logger } from 'robo.js'

async function customDrain(logger: any, level: string, ...data: any[]): Promise<void> {
	// Custom drain logic
}

logger().setDrain(customDrain)

import { logger } from 'robo.js'

async function customDrain(logger, level, ...data) {
	// Custom drain logic
}

logger().setDrain(customDrain)

In the Logger constructor:

import { Logger } from 'robo.js'

const logger = new Logger({
	drain: customDrain
})

import { Logger } from 'robo.js'

const logger = new Logger({
	drain: customDrain
})

In the robo.mjs configuration:

// config/robo.mjs
export default {
	logger: {
		drain: customDrain
	}
}

The default drain function writes to the console. All drains must return a Promise<void>:

async function consoleDrain(logger: any, level: string, ...data: any[]): Promise<void> {
	// Default drain logic
}

async function consoleDrain(logger, level, ...data) {
	// Default drain logic
}

Performance

The Robo.js logger is optimized for asynchronous operation. It writes logs in parallel and maintains a flush queue to ensure all entries are captured, even during a crash. This is important for diagnosing issues in production.

Logger output is also integrated into the /dev logs command and error replies, enabling in-Discord debugging without switching between environments.

Next Steps

Configuration

Configure log levels and drains in your project settings.

Internals

How the runtime manages logging and other systems.

Mode

Use modes to change log levels between development and production.

Logger

Configuration

Internals

Mode

On this page