Basic Usage
Learn the basics of logging with Pail
Last updated:
Basic Usage
This guide covers the fundamental logging operations in Pail.
Default Logger
Pail provides a pre-configured logger instance ready to use:
import { pail } from "@visulima/pail";
pail.info("Server started");
pail.success("Operation completed");
pail.error("Something went wrong", error);Log Types
Pail provides semantic log types for different purposes:
Informational Logs
pail.info("User logged in", { userId: 123 });
pail.log("General message");Success Messages
pail.success("File uploaded successfully");Warnings
pail.warn("Using deprecated API");
pail.warning("High memory usage detected");Errors
pail.error("Failed to connect to database", error);
pail.critical("System failure", criticalError);
pail.emergency("System is down!");
pail.alert("Immediate action required");Debug and Trace
pail.debug("Processing request", { requestId: "abc" });
pail.trace("Entering function", { functionName: "processData" });Status Messages
pail.pending("Task in progress...");
pail.complete("Task completed");
pail.start("Starting process");
pail.stop("Process stopped");
pail.await("Waiting for response");
pail.wait("Waiting...");
pail.watch("Watching for changes");Message Formats
Simple String
pail.info("Hello world");String Interpolation
pail.info("User %s logged in", "John");
pail.success("Completed %d tasks", 5);Multiple Arguments
pail.debug("Processing", "request", { id: 123 });
// All arguments are included in contextStructured Message Object
pail.complete({
prefix: "[task]",
message: "Fix issue #59",
suffix: "(@prisis)",
});Error Objects
try {
// ...
} catch (error) {
pail.error(error); // Error object is automatically serialized
pail.error("Operation failed", error); // With additional context
}Objects and Arrays
pail.info({ userId: 123, action: "login" });
pail.debug([1, 2, 3, 4, 5]);Creating Custom Loggers
Create a logger with custom configuration:
import { createPail } from "@visulima/pail";
const logger = createPail({
logLevel: "debug",
scope: "my-module",
});
logger.info("Module initialized");Enabling and Disabling
logger.disable(); // Stop all logging
logger.info("This won't be logged");
logger.enable(); // Resume logging
logger.info("This will be logged");
if (logger.isEnabled()) {
logger.debug("Logger is active");
}Pausing and Resuming
Queue messages during critical operations:
logger.pause(); // Start queuing messages
logger.info("Message 1"); // Queued
logger.warn("Message 2"); // Queued
logger.resume(); // Flush all queued messages
logger.info("Message 3"); // Output immediatelyConsole Integration
Wrap Console (Browser)
logger.wrapConsole(); // Redirect console.* to logger
console.log("Goes through logger");
console.error("Also goes through logger");
logger.restoreConsole(); // Restore original consoleWrap Streams (Server)
logger.wrapStd(); // Redirect stdout/stderr to logger
process.stdout.write("Goes through logger");
logger.restoreStd(); // Restore original streamsWrap Everything (Server)
logger.wrapAll(); // Wraps both console and streams
// All output goes through logger
logger.restoreAll(); // Restore everythingException Handling
Automatically log uncaught exceptions:
logger.wrapException(); // Sets up global error handlers
// Uncaught errors will be logged automatically
throw new Error("This will be logged");Raw Logging
Bypass normal processing:
logger.raw("Direct message", { data: "value" });
// Uses rawReporter, bypasses processorsNext Steps
- Scoped Loggers - Organize logs by context
- Custom Types - Create custom log types
- Timers - Measure performance