betterlog 2.1.2 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42be8d52810b7073915e4b1efea2bbf42a9dab3fce71392d2d76018a6e15f1b8
-  data.tar.gz: 614f43b1a12d2e45bd0149c32045bdba913269ffe3799958584ec2bcb2ad0007
+  metadata.gz: b6cba025c355a1dfa04219216b3bfd51d99e37e5d22bfbf46fe2d29c93f43f89
+  data.tar.gz: ff8256d38cb36de010ce1f0122e51e5e95aea082121533fb9b1ccbd148521125
 SHA512:
-  metadata.gz: 88672071ddeea36aaca49a2f49ec2408f2e378b2f17de5c2aed437aeed1e73ba8e44ee0af0f9bac72c10f8561b226191e982f4d1076922cae54f1d91327ea846
-  data.tar.gz: 46686b79bf11b7013e784cd6b4031b686b3dedeab53f401fde392d852802e87ff01ee28014a125f601f4120263a6f3ce0c0d288995a3cf240dfa58d9c8310513
+  metadata.gz: 33d3ed44b0b7ffca65ae280eab36317c37c3f83e1bff19084bd054b6e22edc648e396d66ca270d972a85868740a5a1c1326d427f62f4942249b89022cafec34e
+  data.tar.gz: a9e446d2e8ed415cc5591175752a6b2d901e4ad4890fa8c1ef142db8df6c6959edb80e5cc660f160c11537884bf604148a9311287e29e85743b6473c66c724ca

data/CHANGES.md

@@ -1,5 +1,11 @@
 # Changes
 
+## 2025-09-03 v2.1.3
+
+- Improved documentation for the `colorize` method with detailed styling examples
+- Enhanced documentation for the `format_pattern` method with a detailed syntax guide
+- Added `doc` directory to `.gitignore` and updated `Rakefile` to include it in the ignore list
+
 ## 2025-09-02 v2.1.2
 
 - Moved only `filter_severities` method to private scope

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2018 Florian Frank
+Copyright 2018 betterplace
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/README.md

@@ -2,74 +2,327 @@
 
 ## Description
 
-Logging tools for betterplace structured logging in rails applications.
+Structured logging support for Rails applications with flexible formatting and
+filtering capabilities.
 
-## Configuration
+## Installation
 
-Copy the example configuration in config/log.yml into your application to get
-you started. Then add this line to your Gemfile:
+You can use rubygems to fetch the gem and install it for you:
 
-```
-gem 'betterlog'
-```
+    # gem install betterlog
+
+You can also put this line into your Gemfile:
+
+    gem 'betterlog'
+
+and bundle. This will make the `Betterlog` module and its logging facilities
+available.
 
 ## Usage
 
-### `betterlog`
+### Basic Logging
 
-Use it to tail local logfiles:
+The main logging interface provides structured JSON logging with automatic
+Rails integration:
 
-```
-$ betterlog -f
+```ruby
+# Log simple messages
+Log.info("User logged in", meta: { module: 'session', user_id: 123 })
+Log.error("Database connection failed", meta: { module: 'database', error: "Connection timeout" })
+
+# Log exceptions with full backtrace information
+begin
+  # some code that might fail
+rescue => e
+  Log.error(e, meta: { module: 'api_v4', context: "API request processing" })
+end
 ```
 
-or filter from stdin with
+### Command-Line Interface
 
+The `betterlog` CLI tool provides powerful log file processing and filtering
+capabilities:
+
+#### Basic Usage
+
+Tail local logfiles:
+```bash
+$ betterlog -f
 ```
+
+Filter from stdin:
+```bash
 $ cat log/development.log | betterlog
 ```
 
 Search for GET in the last 1000 rails log lines:
+```bash
+$ betterlog -F rails -n 1000 -s GET
+```
 
+Display help for all options:
+```bash
+$ betterlog -h
 ```
-$ betterlog -F rails -n 1000 -s GET
+
+#### Command-Line Options
+
+- `-c` Enable colors during pretty printing
+- `-f` Follow the log files in real-time
+- `-h` Display help information
+- `-p FORMAT` Pretty print log files (e.g., `long`, `short`)
+- `-e EMITTER` Only output events from specific emitters
+- `-s MATCH` Only display events matching search string
+- `-S SEVERITY` Only output events with specified severity level
+- `-n NUMBER` Rewind this many lines backwards before tailing
+- `-F SHORTCUT` Use configuration file shortcuts
+
+#### Examples
+
+Follow Rails logs with colorized output for errors or greater:
+```bash
+$ betterlog -f -F rails -p long -c -S ">=error"
 ```
 
-Display the help for more options with `betterlog -h`.
+Search for specific terms in log files:
+```bash
+$ betterlog -f -s SELECT
+```
 
-### `betterlog_pusher`
+This filters out all logging messages where `meta: { module: 'api_v4' }` was
+given:
 
-- `BETTERLOG_SERVER_URL` is the URL log information is ultimately posted to
-  in the form of `https://user:password@appname-prd-log.betterops.de/log`.
+```
+$ betterlog -f -s meta:module=api_v4
+```
 
-- `BETTERLOG_LINES`, e. g. 1000, is the number of lines which are posted per
-  every request to the above URL.
+Follow multiple log files with default format in colors including the last 10
+lines:
+```bash
+$ betterlog -f -F rails -F redis -pd -c -n 10
+```
 
-- `REDIS_URL` the redis server URL for the server where Log information is
-  stored before posted to the betterlog server.
+Filter stdin from file with default format in color:
+```bash
+$ betterlog -pd -c < unicorn.log
+```
 
-  The rails application should be configured like this to store log information
-  on this redis server:
+Filter last 10 lines of a file with default format in color:
+```bash
+$ betterlog -c -pd -n 10 unicorn.log
+```
 
-  ```
-  config.logger = Betterlog::Logger.new(Redis.new(url: ENV.fetch('REDIS_URL')))
-  ```
+### Architecture Overview
 
-### `betterlog_sink`
+Betterlog follows a modular architecture where different components work
+together to provide structured logging:
 
-This is a small wrapper around the `kubectl logs…` command,
-see `kubectl help logs` for the options.
+```mermaid
+graph TD
+    A[Application Code] --> B(Log Interface)
+    B --> C[Betterlog::Log]
+    C --> D[Event Creation]
+    D --> E[JSON Serialization]
+    E --> F[Formatting Engine]
+    F --> G[Output to Logger]
 
-To tail a log and prettify the output just call and pipe to the `betterlog`
-executable:
+    subgraph "Rails Integration"
+        H[Rails.logger]
+        I[LegacyFormatter]
+        J[Structured Logging]
+        H <---> I
+        I <---> J
+    end
 
+    C --> H
 ```
-$ betterlog_sink --since=1m -f | betterlog
+
+**Diagram Explanation**: This shows how the system is structured. Application
+code calls the logging interface (`Log.info`), which creates structured events
+and processes them through JSON serialization and formatting before outputting
+to either Rails' logger or a default logger. The Rails integration section
+shows how it seamlessly connects with Rails' existing logging infrastructure.
+
+### Logging Flow
+
+When you call a logging method, the following process occurs:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Log as Betterlog::Log
+    participant Formatter as EventFormatter
+    participant Logger as Rails.logger/DefaultLogger
+
+    App->>Log: Log.info(message, data)
+    Log->>Formatter: format(pretty: false)
+    Formatter->>Formatter: JSON.generate(event)
+    Formatter->>Logger: logger.info(json_string)
+    Logger-->>App: Success/Failure
 ```
 
-The sink always defaults to the production logfile, to switch the context to
-staging, prepend the command with the `LOG_ENV` env variable like so:
+**Diagram Explanation**: This illustrates the complete logging workflow. When
+you call `Log.info()`, it goes through the Betterlog::Log (or Log) class, gets
+formatted into a structured event with JSON serialization, and finally outputs
+to either Rails' logger or the default logger. The process is designed to
+maintain structured logging while being compatible with existing Rails logging
+systems.
 
+### Thread-Local Metadata
+
+Betterlog supports thread-local metadata that gets automatically included with
+all log events:
+
+```mermaid
+sequenceDiagram
+    participant User as User Code
+    participant Meta as GlobalMetadata
+    participant Log as Betterlog::Log
+
+    User->>Meta: Betterlog.with_meta(data) { block }
+    Meta->>Meta: Add data to thread-local storage
+    Log->>Log: emit(event)
+    Log->>Log: Merge with GlobalMetadata.current
+    Meta->>Meta: Remove data after block
 ```
-$ LOG_ENV=staging betterlog_sink -f | betterlog
+
+**Diagram Explanation**: This shows how thread-local metadata works. When you
+use `Betterlog.with_meta()`, it temporarily adds metadata to a thread-local
+store, which gets merged with your log events during processing. The metadata
+is automatically cleaned up after the block executes, ensuring thread safety
+and preventing memory leaks.
+
+**Practical Usage Examples**:
+
+**In Rails Controllers** (from `application_controller.rb`):
+```ruby
+class ApplicationController < ActionController::Base
+  # …
+  around_action :set_global_metadata
+
+
+  def set_global_metadata(&block)
+    Betterlog.with_meta(
+      request_id: request.request_id,
+      user_id:    current_user&.id,
+      &block
+    )
+  end
+end
 ```
+This ensures all logs within a request include user and request context
+automatically.
+
+
+**In Background Jobs** (from `booking_mandate/job.rb`):
+
+```ruby
+Betterlog.with_meta(
+  module: 'booking',
+  booking_mandate_id: id,
+) do
+  # All logs in this block automatically include:
+  # - module: 'booking'
+  # - booking_mandate_id: id
+  Log.info("Successfully booked booking mandate #{id}")
+end
+```
+
+This pattern provides consistent contextual information across all log entries
+for a given request or job execution while maintaining thread safety.
+
+These examples show how global metadata is actually used in production code:
+1. **Controller level**: Automatically includes request and user context for
+   all logs during a web request
+2. **Job level**: Automatically includes job-specific context (like booking
+   mandate ID) for all logs within that job execution
+
+This makes debugging much easier since you can always trace logs back to their
+specific context without having to manually pass around context information.
+
+### Configuration
+
+Configuration is handled through the `config/log.yml` file. The configuration
+supports:
+
+- Log formats and styling definitions
+- Severity filtering rules
+- Configuration shortcuts for different environments
+- Color schemes for terminal output
+
+Example configuration structure:
+```yaml
+development: &development
+  level: <%= ENV.fetch('LOG_LEVEL', :debug).to_sym %>
+  styles:
+    'timestamp': [ yellow, bold ]
+    'file': [ blue, bold ]
+    severity:
+      debug: green
+      info: green
+      warn:  yellow
+      error: red
+      fatal: [ red, blink ]
+      unknown: red
+  formats:
+    default: &default_format >
+      {%lt%timestamp} {%5s%severity}
+      "{%0.<%= ENV.fetch('COLUMNS', 80).to_i / 2 %>%message}"
+      {host}
+      {location}
+      {file}{-%O%backtrace}{-%O%meta}
+    d: *default_format
+    long: &long_format |
+      type: {type}
+      timestamp: {%lt%timestamp}
+      severity: {severity}
+      message: "{message}"
+      error_class: {error_class}
+      backtrace: {%O%backtrace}
+      host: {host}
+      location: {location}
+      file: {file}
+      meta: {%O%meta}\n
+    l: *long_format
+    legacy: >
+      {%0.1s%severity} [{%lt%timestamp} #{%d%pid}] {%5s%severity} --
+      {program}: {message}
+  config_files:
+    rails:
+      - log/development.log
+    test:
+      - log/test.log
+    mysql:
+      - log/mysql/mysqld.log
+      - log/mysql/mysql-slow.log
+  legacy_supported: yes
+test:
+  <<: *development
+  level: <%= ENV.fetch('LOG_LEVEL', :debug).to_sym %>
+staging: *development
+production:
+  <<: *development
+  level: <%= ENV.fetch('LOG_LEVEL', :info).to_sym %>
+```
+
+### Rails Integration
+
+When used in a Rails application, betterlog automatically integrates with
+Rails' logging system by detecting Rails presence and using `Rails.logger`
+instead of its default logger. The system also includes a
+`Betterlog::Log::LegacyEventFormatter` that ensures compatibility with existing
+Rails logging formats.
+
+## Download
+
+The homepage of this library is located at
+
+* https://github.com/betterplace/betterlog
+
+## Author
+
+The [betterplace Developers](mailto:developers@betterplace.org)
+
+## License
+
+This software is licensed under the [Apache 2.0 license](LICENSE)

data/Rakefile

@@ -12,8 +12,8 @@ GemHadar do
   test_dir    'spec'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
     '.ruby-version', '.AppleDouble', 'tags', '.DS_Store', '.utilsrc',
-    '.bundle', '.byebug_history', 'errors.lst', '.yardoc', 'betterlog-server',
-    'gospace'
+    '.bundle', '.byebug_history', 'errors.lst', '.yardoc', 'doc',
+    'betterlog-server', 'gospace'
   package_ignore '.all_images.yml', '.utilsrc', '.rspec', '.tool-versions',
     '.gitignore', *Dir['.semaphore/**/*'], *Dir['.github/**/*']
   readme      'README.md'

data/VERSION

@@ -1 +1 @@
-2.1.2
+2.1.4

data/betterlog.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: betterlog 2.1.2 ruby lib
+# stub: betterlog 2.1.4 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterlog".freeze
-  s.version = "2.1.2".freeze
+  s.version = "2.1.4".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/lib/betterlog/log/event_formatter.rb

@@ -65,15 +65,48 @@ module Betterlog
       #
       # This method applies visual styling to a string by looking up the
       # appropriate style configuration based on the provided key and value,
-      # then applying that style using the internal apply_style method.
-      #
-      # @param key [ Object ] the lookup key for determining the style
-      # configuration
-      # @param value [ Object ] the value used to determine which specific
-      # style to apply
-      # @param string [ Object ] the string to be colorized, defaults to the
-      # key if not provided
-      # @return [ String ] the colorized string based on the configured styles
+      # then applying that style using the internal apply_style method. The
+      # colorization logic supports both static and dynamic styling based on
+      # the value being formatted.
+      #
+      # <b>Style Configuration Patterns</b>
+      #
+      # Styles can be configured in several ways:
+      #
+      # <b>Static Styles</b>
+      # - String: Single ANSI color code (e.g., "red", "bold")
+      # - Array: Multiple ANSI codes (e.g., ["red", "bold"])
+      #
+      # <b>Dynamic Styles</b>
+      # - ComplexConfig::Settings: Different styles based on value content
+      #   Example: { debug: "green", error: "red" } where the style is selected based on the value
+      #
+      # <b>Usage Examples</b>
+      #
+      # Given a configuration like:
+      #   styles:
+      #     'timestamp': [ yellow, bold ]
+      #     severity:
+      #       debug: green
+      #       info: green
+      #       warn:  yellow
+      #       error: red
+      #
+      # The method will:
+      # - Colorize "{timestamp}" with yellow/bold styling
+      # - Colorize "{severity}" with green for "debug"/"info", yellow for "warn", red for "error"
+      #
+      # @param key [Object] the lookup key for determining the style configuration
+      # @param value [Object] the value used to determine which specific style to apply
+      # @param string [Object] the string to be colorized, defaults to the key if not provided
+      # @return [String] the colorized string based on the configured styles
+      # @see Betterlog::Log::EventFormatter#apply_style
+      #
+      # @example Static styling
+      #   colorize(:timestamp, nil, "2023-12-01")  # Returns colored timestamp string
+      #
+      # @example Dynamic styling based on value
+      #   colorize(:severity, :error, "ERROR")    # Returns red-colored string
       def colorize(key, value, string = key)
         case style = cc.log.styles[key]
         when nil, String, Array
@@ -109,18 +142,54 @@ module Betterlog
         end
       end
 
-      # Formats a log event using a specified pattern with support for
-      # directives and colorization.
+      # Formats a log event using a specified pattern with support for directives and colorization.
       #
-      # This method processes a format string by replacing placeholders with
-      # actual event data, applying formatting directives for special handling
-      # of values like objects or timestamps, and optionally applying color
-      # styling based on configured styles.
+      # This method processes a format string by replacing placeholders with actual event data,
+      # applying formatting directives for special handling of values like objects or timestamps,
+      # and optionally applying color styling based on configured styles.
       #
-      # @param format [ String ] the format pattern to apply to the log event
-      # @return [ String ] the formatted string representation of the log event
+      # <b>Format Pattern Syntax</b>
+      #
+      # Format patterns use curly braces `{}` to define placeholders with optional directives:
+      #
+      # <b>Basic Key Substitution</b>
+      # - `{key}` - Substitutes the value of `@event[key]`
+      # - `{-key}` - Invisible variant; omits output when value is nil (instead of showing `{key}`)
+      #
+      # <b>Object Formatting Directives</b>
+      # - `{%O%key}` - Formats complex objects (arrays/hashes) with nested structure visualization
+      #   Example: Shows arrays with bullet points and hashes with key-value pairs
+      #
+      # <b>Timestamp Formatting Directives</b>
+      # - `{%t%key}` - Formats timestamp values with various time formats based on flag:
+      #   - `%ut%key` - UTC ISO8601 format (e.g., "2023-12-01T10:30:45.123Z")
+      #   - `%lt%key` - Local time ISO8601 format
+      #   - `%it%key` - Unix timestamp integer (e.g., "1701423425")
+      #   - `%ft%key` - Unix timestamp float (e.g., "1701423425.123")
+      #   - `%t%key` (default) - UTC ISO8601 format
+      #
+      # <b>String Formatting Directives</b>
+      # - `{%.format%key}` - Applies Ruby string formatting using the `%` operator
+      #   Example: `{%.2f%price}` formats a float to 2 decimal places
+      #
+      # <b>Colorization</b>
+      # Values are automatically colorized based on configured styles in the `styles` configuration.
+      # For example, timestamp values use yellow/bold styling, and severity levels use different colors
+      # based on their value (debug=green, warn=yellow, error=red, etc.).
+      #
+      # @param format [String] the format pattern to apply to the log event
+      # @return [String] the formatted string representation of the log event
       # @see Betterlog::Log::EventFormatter#format_object
       # @see Betterlog::Log::EventFormatter#colorize
+      #
+      # @example Basic usage with default configuration
+      #   formatter.format_pattern(format: "{%lt%timestamp} {message}")
+      #
+      # @example Complex formatting with object display
+      #   formatter.format_pattern(format: "{%O%backtrace} {message}")
+      #
+      # @example Conditional display of optional fields
+      #   formatter.format_pattern(format: "{file}{-%O%backtrace}")
       def format_pattern(format:)
         format.
           gsub('\n', "\n").

data/lib/betterlog/version.rb

@@ -1,6 +1,6 @@
 module Betterlog
   # Betterlog version
-  VERSION         = '2.1.2'
+  VERSION         = '2.1.4'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: betterlog
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.1.4
 platform: ruby
 authors:
 - betterplace Developers