betterlog 2.1.3 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e44f75b0aa17e54401d1ecb4ad6d33d8081cae0f6f07740a762d7597e06faa58
-  data.tar.gz: e76cd7fbdd63d2f881e3b8e370135466408161d352a81ff84b839cfa5c1ab41c
+  metadata.gz: b6cba025c355a1dfa04219216b3bfd51d99e37e5d22bfbf46fe2d29c93f43f89
+  data.tar.gz: ff8256d38cb36de010ce1f0122e51e5e95aea082121533fb9b1ccbd148521125
 SHA512:
-  metadata.gz: 631e02be296ef311afa02fd8eb15bb6a2c9913c07ec175bd18c767c351b2431e0ec6eb5c01a7d8638b343b13d621b3790b3c710b5aad1bd728cb550e503c6266
-  data.tar.gz: 2ecc2726e28df7efe266cac59a2d6e39b376a1c3e84d2132ffb135cc83d65cf75f523cccea8f4b48587ee5a3c84dc19b18425e067bd2ad6ade239037c944c5d1
+  metadata.gz: 33d3ed44b0b7ffca65ae280eab36317c37c3f83e1bff19084bd054b6e22edc648e396d66ca270d972a85868740a5a1c1326d427f62f4942249b89022cafec34e
+  data.tar.gz: a9e446d2e8ed415cc5591175752a6b2d901e4ad4890fa8c1ef142db8df6c6959edb80e5cc660f160c11537884bf604148a9311287e29e85743b6473c66c724ca

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/VERSION

@@ -1 +1 @@
-2.1.3
+2.1.4

data/betterlog.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: betterlog 2.1.3 ruby lib
+# stub: betterlog 2.1.4 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterlog".freeze
-  s.version = "2.1.3".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/version.rb

@@ -1,6 +1,6 @@
 module Betterlog
   # Betterlog version
-  VERSION         = '2.1.3'
+  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.3
+  version: 2.1.4
 platform: ruby
 authors:
 - betterplace Developers