Overview
The logger module provides a pre-configured Pino logger instance with environment-aware settings. It automatically adjusts log levels and formatting based on your environment.
This is an internal utility used by the SDK for logging. Plugin developers can use standard console.log() or implement their own logging solution. The SDK’s internal logger is not exported for external use.
Internal Usage
The SDK uses this logger internally for debugging and error reporting:
// Internal SDK logging (for reference)
logger.info("Plugin started")
logger.error("Connection failed", { url: "wss://hub.atomemo.com" })
logger.debug("Processing message", { messageId: 123 })
logger.trace("Detailed trace information")
Log Levels
The logger supports standard Pino log levels:
trace: Most detailed logging (only in debug mode)debug: Detailed debugging information (only in debug mode)info: General informational messageswarn: Warning messageserror: Error messagesfatal: Fatal errors that cause termination
Level Configuration
The log level is automatically configured based on the DEBUG environment variable:
- Debug Mode (
DEBUG=true): Level set to "trace" - all logs are shown
- Production Mode (
DEBUG=false): Level set to "error" - only errors and fatal logs are shown
export const logger = pino({
level: env.DEBUG ? "trace" : "error",
// ...
})
Configuration
All logs include ISO 8601 timestamps:
timestamp: pino.stdTimeFunctions.isoTime
{"level":30,"time":"2026-03-01T12:34:56.789Z","msg":"Plugin started"}
Transport (Development/Test)
In development and test environments (NODE_ENV=development or NODE_ENV=test), the logger uses pino-pretty for human-readable output:
transport: ["development", "test"].includes(env.NODE_ENV)
? {
targets: [
{
target: "pino-pretty",
options: {
colorize: true,
ignore: "pid,hostname",
translateTime: "mm/dd/yyyy HH:MM:ss TT",
},
},
],
}
: undefined
03/01/2026 12:34:56 PM INFO: Plugin started
03/01/2026 12:34:57 PM ERROR: Connection failed
url: "wss://hub.atomemo.com"
NODE_ENV=production), logs are output as compact JSON for efficient parsing:
{"level":30,"time":"2026-03-01T12:34:56.789Z","msg":"Plugin started"}
{"level":50,"time":"2026-03-01T12:34:57.123Z","url":"wss://hub.atomemo.com","msg":"Connection failed"}
Implementation Examples
These examples show how the logger is used internally by the SDK:
Structured Logging
// Internal SDK code
logger.info({ userId: "123", action: "login" }, "User logged in")
// Log with error
try {
await connectToHub()
} catch (error) {
logger.error({ err: error }, "Failed to connect to hub")
}
Child Loggers
The SDK creates child loggers for different components:
// Internal SDK code
const pluginLogger = logger.child({ plugin: "my-plugin", version: "1.0.0" })
pluginLogger.info("Initialized") // Includes plugin and version in every log
Conditional Logging
// Internal SDK code
const env = getEnv()
if (env.DEBUG) {
logger.debug("Detailed debug information")
}
Environment Dependencies
The logger depends on these environment variables (managed by getEnv()):
DEBUG: Controls log level (trace vs error)NODE_ENV: Controls output format (pretty vs JSON)
Pino is one of the fastest Node.js loggers:
- Asynchronous by default
- Low overhead in production
- JSON output for efficient parsing
- Pretty printing only in development
Best Practices
Use Appropriate Log Levels
// Good
logger.trace("Raw message data", { data })
logger.debug("Processing step completed", { step: 1 })
logger.info("Plugin started successfully")
logger.warn("Deprecated API used")
logger.error("Failed to process message", { err })
// Avoid
logger.info("x = 123") // Too verbose for info
logger.error("Success") // Wrong level
Include Context
// Good - includes context
logger.error({ err, userId, messageId }, "Failed to process message")
// Less useful - missing context
logger.error("Failed to process message")
Don’t Log Sensitive Data
// Bad - logs API key
logger.info({ apiKey: env.HUB_DEBUG_API_KEY }, "Connecting")
// Good - redacts sensitive data
logger.info({ apiKey: "***" }, "Connecting")
Type Definition
import type { Logger } from "pino"
export const logger: Logger