Lockness Logger | Lockness Documentation

Lockness Logger

LLM DOCS:VIEW

Structured logging system with multiple levels, transports, and formatters for production-ready applications.

Overview

@lockness/logger provides:

5 Log Levels - DEBUG, INFO, WARN, ERROR, FATAL with filtering
Multiple Formatters - Text, JSON, Pretty (with colors)
Flexible Transports - Console, File, Memory, Custom
Contextual Logging - Child loggers with inherited context
Metadata Support - Attach structured data to logs
Async Operations - Non-blocking logging
Type Safe - Full TypeScript support

Installation

typescript

import { configureLogger, Logger } from '@lockness/logger'
// or
import { configureLogger, Logger } from '@lockness/core'

Basic Usage

Simple Logging

typescript

import { Logger } from '@lockness/logger'

const log = new Logger()

await log.info('Application started')
await log.warn('Low disk space', { available: '10GB' })
await log.error('Database connection failed', new Error('Connection timeout'))

Global Logger

typescript

import { configureLogger, logger } from '@lockness/logger'

// Configure once at startup
configureLogger({
    level: LogLevel.DEBUG,
})

// Use anywhere in your app
await logger().info('User logged in', { userId: 123 })

Quick Helpers

typescript

import { error, info, warn } from '@lockness/logger'

await info('Server started on port 3000')
await warn('Rate limit approaching')
await error('Failed to send email', new Error('SMTP error'))

Log Levels

Logs are filtered by severity threshold:

typescript

import { Logger, LogLevel } from '@lockness/logger'

const log = new Logger({ level: LogLevel.WARN })

await log.debug('Debug message') // Skipped
await log.info('Info message') // Skipped
await log.warn('Warning message') // Logged
await log.error('Error message') // Logged
await log.fatal('Fatal message') // Logged

Level Hierarchy:

DEBUG (0) - Detailed debugging information
INFO (1) - General informational messages
WARN (2) - Warning messages
ERROR (3) - Error conditions
FATAL (4) - Critical failures requiring immediate attention

Formatters

Text Formatter (Production Default)

typescript

import { Logger, TextFormatter } from '@lockness/logger'

const log = new Logger({
    formatter: new TextFormatter(),
})

await log.info('User login', { userId: 123 })
// Output: 2024-01-01T12:00:00.000Z INFO  User login {"userId":123}

JSON Formatter (Log Aggregation)

Perfect for log aggregation systems (ELK, Splunk, etc.):

typescript

import { JsonFormatter, Logger } from '@lockness/logger'

const log = new Logger({
    formatter: new JsonFormatter(),
})

await log.info('API request', { method: 'GET', path: '/users' })
// Output: {"timestamp":"2024-01-01T12:00:00.000Z","level":"INFO","message":"API request","method":"GET","path":"/users"}

Pretty Formatter (Development)

Colorized output for development:

typescript

import { Logger, PrettyFormatter } from '@lockness/logger'

const log = new Logger({
    formatter: new PrettyFormatter(),
})

await log.info('Server ready')
// Output: ℹ️  12:00:00 INFO  Server ready (with colors!)

Transports

Console Transport

Log to stdout/stderr:

typescript

import { ConsoleTransport, Logger } from '@lockness/logger'

const log = new Logger({
    transports: [new ConsoleTransport()],
})

await log.info('Console output')

File Transport

Log to files:

typescript

import { FileTransport, Logger, TextFormatter } from '@lockness/logger'

const log = new Logger({
    transports: [
        new FileTransport('./logs/app.log', new TextFormatter()),
    ],
})

await log.info('Written to file')

// Close file handles when done
await log.close()

Memory Transport (Testing)

Store logs in memory for testing:

typescript

import { Logger, MemoryTransport } from '@lockness/logger'

const memory = new MemoryTransport()
const log = new Logger({
    transports: [memory],
})

await log.info('Test message')

const logs = memory.getLogs()
console.log(logs) // [{ level: 1, message: '...', ... }]

memory.clear() // Clear logs

Multiple Transports

Log to multiple destinations simultaneously:

typescript

import {
    ConsoleTransport,
    FileTransport,
    Logger,
    PrettyFormatter,
    TextFormatter,
} from '@lockness/logger'

const log = new Logger({
    transports: [
        new ConsoleTransport(), // Pretty console output
        new FileTransport('./logs/app.log', new TextFormatter()),
    ],
    formatter: new PrettyFormatter(),
})

await log.info('Logged everywhere')

Contextual Logging

Create child loggers with inherited context:

typescript

import { Logger } from '@lockness/logger'

const appLog = new Logger({ context: 'App' })

const dbLog = appLog.child('Database')
const cacheLog = appLog.child('Cache')

await dbLog.info('Query executed')
// Output: ... [App:Database] Query executed

await cacheLog.info('Cache hit')
// Output: ... [App:Cache] Cache hit

Nested contexts:

typescript

const serverLog = new Logger({ context: 'Server' })
const apiLog = serverLog.child('API')
const userLog = apiLog.child('Users')

await userLog.info('User created')
// Output: ... [Server:API:Users] User created

Metadata

Attach structured data to logs:

typescript

await log.info('User action', {
    userId: 123,
    action: 'login',
    ip: '127.0.0.1',
    timestamp: Date.now(),
})

Error objects are automatically expanded:

typescript

try {
    throw new Error('Database connection failed')
} catch (err) {
    await log.error('Connection error', err)
    // Includes: error message, stack trace, error name
}

Custom error metadata:

typescript

await log.error('Request failed', {
    statusCode: 500,
    endpoint: '/api/users',
    duration: 1234,
    userId: 'abc123',
})

API Reference

Logger Class

typescript

// Constructor
new Logger(config?: LoggerConfig)

// Configuration
interface LoggerConfig {
    level?: LogLevel              // Minimum log level (default: INFO)
    transports?: LogTransport[]   // Output destinations
    formatter?: LogFormatter      // Log format
    context?: string              // Logger context name
}

// Methods
setLevel(level: LogLevel): void
getLevel(): LogLevel
addTransport(transport: LogTransport): void
child(context: string): Logger

// Logging methods
debug(message: string, metadata?: Record<string, unknown>): Promise<void>
info(message: string, metadata?: Record<string, unknown>): Promise<void>
warn(message: string, metadata?: Record<string, unknown>): Promise<void>
error(message: string, error?: Error | Record<string, unknown>): Promise<void>
fatal(message: string, error?: Error | Record<string, unknown>): Promise<void>

// Cleanup
close(): Promise<void>

Global Functions

typescript

configureLogger(config?: LoggerConfig): Logger
logger(): Logger
createLogger(config?: LoggerConfig): Logger

debug(message: string, metadata?: Record<string, unknown>): Promise<void>
info(message: string, metadata?: Record<string, unknown>): Promise<void>
warn(message: string, metadata?: Record<string, unknown>): Promise<void>
error(message: string, error?: Error | Record<string, unknown>): Promise<void>
fatal(message: string, error?: Error | Record<string, unknown>): Promise<void>

Use Cases

HTTP Request Logging

typescript

import { JsonFormatter, Logger } from '@lockness/logger'

const httpLog = new Logger({
    context: 'HTTP',
    formatter: new JsonFormatter(),
})

// Log requests
await httpLog.info('Request received', {
    method: 'POST',
    path: '/api/users',
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0...',
})

// Log responses
await httpLog.info('Response sent', {
    status: 201,
    duration: 45,
    bytes: 1024,
})

Service-Specific Logging

typescript

import { Logger } from '@lockness/logger'

const appLog = new Logger({ context: 'App' })

// Database logger
const dbLog = appLog.child('DB')
await dbLog.info('Connected to PostgreSQL')
await dbLog.debug('Query', { sql: 'SELECT * FROM users', duration: 23 })

// Cache logger
const cacheLog = appLog.child('Cache')
await cacheLog.info('Redis connected')
await cacheLog.debug('Cache hit', { key: 'user:123' })

// Queue logger
const queueLog = appLog.child('Queue')
await queueLog.info('Worker started')
await queueLog.warn('Queue backlog', { count: 1000 })

Development vs Production

typescript

import {
    ConsoleTransport,
    FileTransport,
    JsonFormatter,
    Logger,
    LogLevel,
    PrettyFormatter,
} from '@lockness/logger'

const isDev = Deno.env.get('ENV') === 'development'

const log = new Logger({
    level: isDev ? LogLevel.DEBUG : LogLevel.INFO,
    formatter: isDev ? new PrettyFormatter() : new JsonFormatter(),
    transports: isDev ? [new ConsoleTransport()] : [
        new FileTransport('./logs/app.log'),
        new ConsoleTransport(),
    ],
})

Application Lifecycle

typescript

import { Logger, LogLevel } from '@lockness/logger'

const log = new Logger({
    level: LogLevel.INFO,
    context: 'MyApp',
})

// Application startup
await log.info('Application starting', {
    version: '1.0.0',
    env: Deno.env.get('ENV'),
    node: Deno.version.deno,
})

await log.info('Database connected', {
    host: 'localhost',
    database: 'myapp',
})

await log.info('Server listening', {
    port: 3000,
    mode: 'production',
})

// User actions
await log.info('User registered', {
    userId: 'abc123',
    email: 'user@example.com',
    timestamp: new Date(),
})

// Errors
await log.error('Payment failed', {
    userId: 'abc123',
    amount: 99.99,
    gateway: 'stripe',
    errorCode: 'card_declined',
})

Best Practices

Use Appropriate Log Levels

typescript

await log.debug('Variable value:', { value: x }) // Development only
await log.info('User logged in') // Informational
await log.warn('Cache miss') // Warnings
await log.error('Failed to save', err) // Errors
await log.fatal('Database unavailable', err) // Critical

Add Context to Loggers

typescript

const userLog = appLog.child('UserService')
const orderLog = appLog.child('OrderService')

Include Metadata

typescript

await log.info('Order placed', {
    orderId: 'ORD-123',
    userId: 456,
    total: 99.99,
    items: 3,
})

Log Errors with Stack Traces

typescript

try {
    await operation()
} catch (err) {
    await log.error('Operation failed', err as Error)
}

Use JSON Format for Production

typescript

import { JsonFormatter } from '@lockness/logger'

const log = new Logger({
    formatter: new JsonFormatter(),
})

Close File Transports

typescript

const log = new Logger({
    transports: [new FileTransport('./app.log')],
})

// ... application logic ...

await log.close() // Close file handles

Configure Once, Use Everywhere

typescript

// app.ts
configureLogger({
    level: LogLevel.INFO,
    formatter: new JsonFormatter(),
})

// any-file.ts
import { logger } from '@lockness/logger'
await logger().info('Ready')

Custom Transport

Create custom transports for third-party services:

typescript

import type { LogEntry, LogTransport } from '@lockness/logger'

class SlackTransport implements LogTransport {
    constructor(private webhookUrl: string) {}

    async log(entry: LogEntry): Promise<void> {
        if (entry.level >= LogLevel.ERROR) {
            await fetch(this.webhookUrl, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    text: `[${entry.level}] ${entry.message}`,
                    attachments: [{ text: JSON.stringify(entry.metadata) }],
                }),
            })
        }
    }
}

const log = new Logger({
    transports: [
        new ConsoleTransport(),
        new SlackTransport('https://hooks.slack.com/...'),
    ],
})

Performance

Logs below threshold skipped (no formatting overhead)
Async operations don't block application
Formatting happens once, sent to all transports
Memory transport is fast for testing

Testing

typescript

import { Logger, MemoryTransport } from '@lockness/logger'

Deno.test('test logging', async () => {
    const memory = new MemoryTransport()
    const log = new Logger({ transports: [memory] })

    await log.info('Test message', { foo: 'bar' })

    const logs = memory.getLogs()
    assertEquals(logs.length, 1)
    assertEquals(logs[0].message, 'Test message')
    assertEquals(logs[0].metadata.foo, 'bar')
})

Edit this page