About SmooAI

SmooAI is an AI-powered platform for helping businesses multiply their customer, employee, and developer experience.

Learn more on smoo.ai

SmooAI Packages

Check out other SmooAI packages at smoo.ai/open-source

About @smooai/logger

The missing piece for AWS & Browser logging - A contextual logging system that automatically captures the full execution context you need to debug production issues, without the manual setup.

Why @smooai/logger?

Ever spent hours debugging an AWS service in production, only to realize you're missing critical context? Or tracking down a browser issue without knowing the user's device or browser version? Traditional loggers give you the message, but not the story.

@smooai/logger automatically captures:

For AWS Services:

• 📍 Exact code location - File, line number, and call stack for every log
• 🔗 Request journey - Correlation IDs that follow requests across services
• ⚡ AWS context - Service-specific metadata and execution details
• 🌐 HTTP details - Headers, methods, status codes from API Gateway
• 📬 Message context - SQS attributes, EventBridge events, SNS messages
• 🔧 Service integration - Lambda, ECS, Fargate, EC2, and more

For Browser:

• 🖥️ Device intelligence - Desktop, mobile, or tablet detection
• 🌏 Browser context - Name, version, platform, and user agent
• 📱 Platform details - Operating system and architecture
• 🔍 Request tracking - Automatic correlation across API calls
• 🚨 Rich errors - Full stack traces with source map support

Install

pnpm add @smooai/logger

Python Package

The Python port mirrors the TypeScript API for backend services. Install it from PyPI:

pip install smooai-logger

or with uv:

uv add smooai-logger

See python/README.md for usage examples aligned with the TypeScript docs below.

Rust Crate

Need the same structured logging features in Rust? A parity crate now lives in rust/logger/:

[dependencies]
smooai-logger = { git = "https://github.com/SmooAI/logger", package = "smooai-logger" }

Usage examples and API notes are documented in rust/logger/README.md.

The Power of Automatic Context

See Where Your Logs Come From

Every log entry includes the exact location in your code:

const logger = new AwsServerLogger();
logger.info('User created');

// Output includes:
{
  "callerContext": {
    "stack": [
      "at UserService.createUser (/src/services/UserService.ts:42:16)",
      "at processRequest (/src/handlers/userHandler.ts:15:23)",
      "at Runtime.handler (/src/index.ts:8:10)"
    ]
  }
}

No more guessing which function logged what - the full execution path is right there.

Track Requests Across Services

Correlation IDs automatically flow through your entire system:

// Service A: API Gateway Handler
logger.addLambdaContext(event, context);
logger.info('Request received'); // Correlation ID: abc-123

// Service B: SQS Processor (automatically extracts ID)
logger.addSQSRecordContext(record);
logger.info('Processing message'); // Same Correlation ID: abc-123

// Service C: Another Lambda (receives via HTTP header)
logger.info('Completing workflow'); // Still Correlation ID: abc-123

Production-Ready Examples

AWS Lambda with API Gateway

import { AwsServerLogger } from '@smooai/logger/AwsServerLogger';

const logger = new AwsServerLogger({ name: 'UserAPI' });

export const handler = async (event, context) => {
    logger.addLambdaContext(event, context);

    try {
        const user = await createUser(event.body);
        logger.info('User created successfully', { userId: user.id });
        return { statusCode: 201, body: JSON.stringify(user) };
    } catch (error) {
        logger.error('Failed to create user', error, {
            body: event.body,
            headers: event.headers,
        });
        throw error;
    }
};

AWS ECS/Fargate Services

const logger = new AwsServerLogger({
    name: 'OrderService',
    level: Level.Info,
});

// Automatically captures container metadata
app.post('/orders', async (req, res) => {
    logger.addContext({
        taskArn: process.env.ECS_TASK_ARN,
        containerName: process.env.ECS_CONTAINER_NAME,
    });

    logger.info('Processing order', {
        orderId: req.body.orderId,
        amount: req.body.amount,
    });
});

SQS Message Processing

export const sqsHandler = async (event) => {
    for (const record of event.Records) {
        logger.addSQSRecordContext(record);
        logger.info('Processing order', {
            messageId: record.messageId,
            attempt: record.attributes.ApproximateReceiveCount,
        });

        // Logger maintains context throughout async operations
        await processOrder(record.body);
    }
};

Browser Tracking

import { BrowserLogger } from '@smooai/logger/browser/BrowserLogger';

const logger = new BrowserLogger({ name: 'CheckoutFlow' });

// Automatically captures browser context
const response = await fetch('/api/checkout', {
  method: 'POST',
  headers: { 'X-Correlation-Id': logger.correlationId() }
});

logger.addResponseContext(response);
logger.info('Checkout completed', { orderId: data.id });

// Output includes rich browser context:
{
  "browserContext": {
    "name": "Chrome",
    "version": "120.0.0",
    "platform": "MacIntel",
    "userAgent": "Mozilla/5.0...",
    "isDesktop": true,
    "isMobile": false,
    "isTablet": false
  },
  "http": {
    "request": {
      "method": "POST",
      "path": "/api/checkout",
      "headers": { "x-correlation-id": "abc-123" }
    },
    "response": {
      "statusCode": 200,
      "headers": { "content-type": "application/json" }
    }
  }
}

Advanced Features

Smart Error Handling

Errors are automatically serialized with full context:

try {
    await riskyOperation();
} catch (error) {
    logger.error('Operation failed', error, { context: 'additional-info' });
    // Includes: error message, stack trace, error type, and your context
}

Flexible Context Management

// Add user context that persists across logs
logger.addUserContext({ id: 'user-123', role: 'admin' });

// Add telemetry for performance tracking
logger.addTelemetryFields({ duration: 150, operation: 'db-query' });

// Add custom context for specific logs
logger.info('Payment processed', {
    amount: 99.99,
    currency: 'USD',
});

Local Development Features

Pretty Printing

const logger = new AwsServerLogger({
    prettyPrint: true, // Readable console output for development
});

Automatic Log Rotation

Logs are automatically saved to disk in development with smart rotation:

// Auto-enabled in local environments
// Saves to .smooai-logs/ with ANSI colors for easy reading
const logger = new AwsServerLogger({
    rotation: {
        size: '10M', // Rotate at 10MB
        interval: '1d', // Daily rotation
        compress: true, // Gzip old logs
    },
});

Import Paths

// AWS environments (Lambda, ECS, EC2, etc.)
import { AwsServerLogger, Level } from '@smooai/logger/AwsServerLogger';

// Browser environments
import { BrowserLogger, Level } from '@smooai/logger/browser/BrowserLogger';

Configuration

Log Levels

• TRACE - Detailed debugging information
• DEBUG - Diagnostic information
• INFO - General operational information
• WARN - Warning conditions
• ERROR - Error conditions
• FATAL - Critical failures

Context Presets

• MINIMAL - Essential context only
• FULL - All available context (default)

Built With

• TypeScript - Full type safety
• AWS SDK Integration - Native support for Lambda, ECS, EC2, and more
• Browser Detection - Automatic environment adaptation
• Rotating File Stream - Smart log rotation

(back to top)

Contact

Brent Rager

• Email
• LinkedIn
• BlueSky
• TikTok
• Instagram

Smoo Github: https://github.com/SmooAI

(back to top)