smartlog/readme.hints.md

SmartLog - Development Hints & Notes

This document contains notes and findings about the SmartLog library to help with development and understanding of the codebase.

Key Components

• Smartlog: Main logger class that handles logging operations
• LogRouter: Routes logs to various destinations
• LogGroup: Groups related logs for better traceability
• ConsoleLog: Destination that logs to the console
• ILogDestination: Interface for implementing custom log destinations

Core Concepts

• Log Context: Metadata about the environment (company, environment, runtime, etc.)
• Log Levels: 'silly', 'info', 'debug', 'note', 'ok', 'success', 'warn', 'error', 'lifecycle'
• Log Types: 'log', 'increment', 'gauge', 'error', 'success', 'value', 'finance', 'compliance'
• Log Correlation: Used to link related logs together (group, transaction, instance)

Interactive Console Features

• SmartlogSourceInteractive: Creates interactive spinners for CLI applications
• SmartlogProgressBar: Creates progress bars for CLI applications
• Both automatically detect non-interactive environments and provide fallback behavior

Environment Detection

The library uses feature detection to adapt to different environments:

• Checks for TTY capability
• Detects CI/CD environments (GitHub Actions, Jenkins, GitLab CI, Travis, CircleCI)
• Provides appropriate output based on the environment

Available Destinations

• Console (built-in)
• File (ts_destination_file)
• Local (ts_destination_local)
• Clickhouse (ts_destination_clickhouse)
• Developer Tools (ts_destination_devtools)
• Receiver (ts_destination_receiver)

Advanced Features

• Increment Logging: For metrics and counters
• Console Capture: Option to capture all console output through Smartlog
• Custom Destinations: Extend with custom log destinations

Tests

Test files are organized by environment compatibility:

• *.both.ts: Tests for both browser and Node.js
• *.node.ts: Tests for Node.js only
• *.browser.ts: Tests for browser only