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.

Go Package

The Go port provides the same structured logging features for Go services:

go get github.com/smooai/logger

import "github.com/smooai/logger"

l, err := logger.New(logger.Options{
    Name:  "MyService",
    Level: logger.LevelInfo,
})
if err != nil {
    log.Fatal(err)
}
defer l.Close()

// Add HTTP request context (auto-sets namespace and extracts correlation ID)
l.AddHTTPRequest(logger.HTTPRequest{
    Method: "POST",
    Path:   "/api/users",
    Headers: map[string]string{"X-Correlation-Id": "abc-123"},
})

// Structured logging with context maps
l.Info("User created", logger.Map{"userId": "123"})

// Error logging with automatic stack traces
l.Error("Operation failed", fmt.Errorf("database timeout"))

// User context, telemetry, and correlation tracking
l.AddUserContext(logger.User{ID: "user-456", Role: "admin"})
l.SetCorrelationID("custom-trace-id")

Features: all 6 log levels (TRACE through FATAL), structured JSON output, ANSI pretty-printing in local dev, automatic file rotation to .smooai-logs/, global context with correlation/request/trace IDs, HTTP request/response context, user context, and telemetry fields.

See go/ for the full source and go/logger_test.go for comprehensive test coverage (27 tests).

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 - Core implementation with full type safety, AWS SDK integration, browser detection, and rotating file streams
• Python - Pydantic-based structured logging with rich terminal output and AWS context support
• Rust - High-performance structured logging with serde serialization and colored output
• Go - Native structured logging with JSON output, ANSI pretty-printing, and automatic file rotation
• Log Viewer - Desktop application (Rust/egui) for viewing and analyzing SmooAI logs with filtering and DuckDB-powered queries

Contact

Brent Rager

• Email
• LinkedIn
• BlueSky
• TikTok
• Instagram

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