charmbracelet/log
Log
This is a structured logging library designed to produce logs using key-value pairs, severity levels, and machine-readable formats. It provides a toolkit for creating logs that are consistent for both human review and machine parsing.
The project is distinguished by its focus on terminal visualization, using a styling system to apply colors and prefixes to log entries for improved readability in consoles. It also includes a specialized adapter to convert standard library log calls into structured events by inferring severity levels from message prefixes.
The library manages metadata through contextual sub-loggers that attach persistent attributes and automatic source location information to entries. It supports multiple serialization formats, including JSON and logfmt, and provides source attribution by analyzing the call stack to identify the origin of log events.
The system integrates with the standard slog package via a custom handler to route structured logs through its formatting engine.
Features
- Structured Logging - Implements structured logging by recording operational data as machine-readable key-value pairs.
- Log Formatters - Provides pluggable formatters to serialize structured logs into multiple formats including JSON and logfmt.
- Logfmt Serializers - Serializes log entries into key-value pairs following the logfmt standard to handle complex data types.
- Terminal Output Stylers - Applies visual styles and color-coded escape sequences to log output for improved console readability.
- Structured Logging Libraries - Provides a comprehensive toolkit for producing structured logs with key-value pairs and severity levels.
- Persistent Log Context - Attaches persistent metadata fields to logger instances to ensure consistent context across all subsequent logs.
- JSON Formats - Serializes log entries into machine-readable JSON and logfmt formats for observability tool compatibility.
- Severity Level Filtering - Filters log messages based on a minimum severity threshold such as Info or Error.
- Contextual Logging - Injects persistent metadata and source location information into log entries to enable system-wide tracing.
- Log Configuration - Provides global settings for controlling log severity levels, time formats, and output prefixes.
- Logger Hierarchies - Implements hierarchical logger structures where child loggers inherit metadata and attributes from their parents.
- Contextual Logger Instances - Provides a logging system capable of creating child loggers that carry persistent, scoped metadata.
- Structured Log Field Attachments - Allows adding structured key-value pairs to log entries to provide consistent context throughout an execution.
- Log Level Visual Styling - Maps specific log levels to visual color profiles and formatting rules for improved terminal readability.
- Log Metadata Injectors - Automatically injects constant fields, timestamps, and source location information into every emitted log entry.
- Logfmt Serializers - Includes a dedicated serializer for converting structured log data into the logfmt standard.
- Runtime Call-Stack Capturers - Analyzes the runtime call stack to bypass wrapper functions and identify the original source of a log event.
- Standard Library Adapters - Wraps standard library logging interfaces to integrate them into a structured logging pipeline.
- Logging Libraries - Provides adapters that convert standard library log calls into structured events to modernize legacy logging.
- Adapter Patterns - Uses adapter patterns to bridge the gap between standard library logging and structured logging interfaces.
- Custom Log Formatting - Supports converting structured log data into multiple interchangeable formats including text, JSON, and logfmt.
- Source Location Capture - Automatically records the source file, line number, and function name for every emitted log entry.
- Severity Inference Engines - Infers log severity levels from unstructured strings by matching message prefixes against defined patterns.
- Component Identifiers - Allows prepending specific strings to log entries to identify which component emitted the message.
- Logging Integrations - Implements a custom handler for the standard slog package to route structured logs through its formatting engine.
