betterlog 2.0.6 → 2.1.1

data/lib/betterlog/log.rb

@@ -5,6 +5,16 @@ require 'betterlog/log/event_formatter'
 require 'betterlog/log/severity'
 
 module Betterlog
+  # A flexible, framework-agnostic logging solution that provides a clean API
+  # for structured logging with automatic Rails integration and error recovery.
+  #
+  # This class implements a singleton pattern using Tins::SexySingleton and
+  # automatically detects Rails environment to use its logger when available.
+  # It supports structured logging with contextual information, location
+  # tracking, and event notification capabilities.
+  #
+  # @example Basic usage
+  #   Betterlog::Log.info("User logged in", meta: { user_id: 123 })
   class Log
     include Tins::SexySingleton
     extend ComplexConfig::Provider::Shortcuts
@@ -15,6 +25,12 @@ module Betterlog
       default_logger.level = level
     end
 
+    # Returns the appropriate logger instance for the application.
+    #
+    # This method checks if Rails is defined and has a logger available,
+    # falling back to a default logger otherwise.
+    #
+    # @return [Logger] The Rails logger if available, otherwise the default logger.
     def logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : self.class.default_logger
     end
@@ -22,7 +38,7 @@ module Betterlog
     # Logs a message on severity info.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def info(object, **rest)
       protect do
@@ -34,7 +50,7 @@ module Betterlog
     # Logs a message on severity warn.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def warn(object, **rest)
       protect do
@@ -46,7 +62,7 @@ module Betterlog
     # Logs a message on severity debug.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def debug(object, **rest)
       protect do
@@ -58,7 +74,7 @@ module Betterlog
     # Logs a message on severity error.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def error(object, **rest)
       protect do
@@ -70,7 +86,7 @@ module Betterlog
     # Logs a message on severity fatal.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def fatal(object, **rest)
       protect do
@@ -83,7 +99,7 @@ module Betterlog
     # passing the severity: keyword.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def output(object, **rest)
       protect do
@@ -91,10 +107,16 @@ module Betterlog
       end
     end
 
-    def metric(name:, value: nil, success: -> result { true }, **rest, &block)
-      warn "#{self.class}##{__method__} is deprecated"
-    end
-
+    # Emits a log event by adding contextual information, notifying
+    # subscribers, and logging through the configured logger.
+    #
+    # This method enhances the provided event with location information if
+    # available, sets the emitter identifier, triggers any registered
+    # notifiers, and finally logs the event using the application's logger at
+    # the event's severity level.
+    #
+    # @param event [Betterlog::Log::Event] the log event to be emitted
+    # @return [Betterlog::Log] the log instance itself
     def emit(event)
       l = caller_locations.reverse_each.each_cons(3).find { |c, n1, n2|
         n2.absolute_path =~ /betterlog\/log\.rb/ and break c # TODO check if this still works

data/lib/betterlog/notifiers.rb

@@ -1,10 +1,31 @@
 module Betterlog
+  # Module for managing and coordinating log event notifiers.
+  #
+  # This module provides a centralized mechanism for registering and notifying
+  # objects when specific log events occur. It maintains a collection of
+  # notifier instances that can respond to log events, allowing for flexible
+  # integration with external monitoring, alerting, or logging systems.
+  # Notifiers are invoked when log events explicitly request notification,
+  # enabling decoupled communication between the logging system and downstream
+  # services.
+  #
+  # @see Betterlog::Log#emit
+  # @see Betterlog::Log::Event#notify?
   module Notifiers
 
     class_attr_accessor :notifiers
 
     self.notifiers = Set[]
 
+    # Registers a notifier object with the Notifiers module.
+    #
+    # This method adds a notifier to the collection of registered notifiers,
+    # ensuring that it responds to the required notify interface. The notifier
+    # will subsequently be invoked when log events with notification requests
+    # are emitted.
+    #
+    # @param notifier [ Object ] the notifier object to be registered
+    # @return [ Class ] Returns the Notifiers class itself
     def self.register(notifier)
       notifier.respond_to?(:notify) or raise TypeError,
         "notifier has to respond to notify(message, hash) interface"
@@ -12,6 +33,14 @@ module Betterlog
       self
     end
 
+    # Notifies registered notifiers with the event data.
+    #
+    # This method checks if the provided event has notification enabled,
+    # and if so, iterates through all registered notifiers to send them
+    # the event's message and metadata. It also updates the context for
+    # each notifier before sending the notification.
+    #
+    # @param event [Betterlog::Log::Event] the log event to be notified about
     def self.notify(event)
       event.notify? or return
       notifiers.each do |notifier|
@@ -20,6 +49,15 @@ module Betterlog
       end
     end
 
+    # Sets the context for all registered notifiers with the provided data.
+    #
+    # This method iterates through all registered notifiers and invokes their
+    # context method if they respond to it, passing the given data hash to
+    # allow notifiers to update their internal state or configuration based
+    # on the provided context information.
+    #
+    # @param data [ Hash ] A hash containing the context data to be passed
+    #   to each notifier that supports the context interface
     def self.context(data)
       notifiers.each do |notifier|
         notifier.respond_to?(:context) or next

data/lib/betterlog/railtie.rb

@@ -1,4 +1,12 @@
 module Betterlog
+  # Integrates Betterlog with Rails application initialization.
+  #
+  # This Railtie is responsible for configuring Rails to use Betterlog's legacy event formatter
+  # as the default logger formatter. It ensures that log messages are properly structured
+  # and enriched with metadata when used within a Rails application context.
+  #
+  # @see Betterlog::Log::LegacyEventFormatter
+  # @see Rails::Railtie
   class Railtie < Rails::Railtie
     initializer "betterlog_railtie.configure_rails_initialization" do
       require 'betterlog/log/legacy_event_formatter'

data/lib/betterlog/version.rb

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

data/lib/betterlog.rb

@@ -3,6 +3,12 @@ require 'json'
 require 'complex_config'
 require 'term/ansicolor'
 
+# Main module for Betterlog logging functionality.
+#
+# Provides structured logging tools designed for betterplace's logging
+# infrastructure in Rails applications. Offers thread-local metadata
+# management, event formatting, severity handling, and integration with Rails
+# logging systems.
 module Betterlog
 end
 
@@ -16,3 +22,12 @@ if defined? Rails
 end
 
 Log = Betterlog::Log
+
+# This class serves as a convenience alias for the Betterlog::Log module,
+# providing a simple way to access the logging functionality throughout a Rails
+# application
+#
+# @see Betterlog::Log
+# @see Betterlog
+class Log
+end

data/spec/spec_helper.rb

@@ -1,9 +1,5 @@
-if ENV['START_SIMPLECOV'].to_i == 1
-  require 'simplecov'
-  SimpleCov.start do
-    add_filter "#{File.basename(File.dirname(__FILE__))}/"
-  end
-end
+require 'gem_hadar/simplecov'
+GemHadar::SimpleCov.start
 require 'rspec'
 begin
   require 'debug'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: betterlog
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.1.1
 platform: ruby
 authors:
 - betterplace Developers
 bindir: bin
 cert_chain: []
-date: 2025-02-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '1.28'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '1.28'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -215,11 +215,7 @@ extra_rdoc_files:
 - lib/betterlog/railtie.rb
 - lib/betterlog/version.rb
 files:
-- ".all_images.yml"
-- ".github/workflows/codeql-analysis.yml"
-- ".gitignore"
-- ".semaphore/semaphore.yml"
-- ".tool-versions"
+- CHANGES.md
 - Gemfile
 - LICENSE
 - README.md
@@ -258,16 +254,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Structured logging support for bp
 test_files:

data/.all_images.yml

@@ -1,18 +0,0 @@
-dockerfile: |-
-  RUN apk add --no-cache yaml-dev build-base git
-  RUN gem install gem_hadar
-
-script: &script |-
-  echo -e "\e[1m"
-  ruby -v
-  echo -e "\e[0m"
-  bundle
-  rake spec
-
-fail_fast: yes
-
-images:
-  ruby:3.4-alpine: *script
-  ruby:3.3-alpine: *script
-  ruby:3.2-alpine: *script
-  ruby:3.1-alpine: *script

data/.github/workflows/codeql-analysis.yml

@@ -1,72 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ master ]
-  schedule:
-    - cron: '27 21 * * 1'
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [ 'go', 'ruby' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
-        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        
-        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-        # queries: security-extended,security-and-quality
-
-        
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-
-    #   If the Autobuild fails above, remove it and uncomment the following three lines. 
-    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
-
-    # - run: |
-    #   echo "Run, Build Application using script"
-    #   ./location_of_script_within_repo/buildscript.sh
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2

data/.gitignore

@@ -1,16 +0,0 @@
-.*.sw[pon]
-.AppleDouble
-.DS_Store
-.bundle
-.byebug_history
-.ruby-version
-.rvmrc
-.utilsrc
-.yardoc
-Gemfile.lock
-betterlog-server
-coverage
-errors.lst
-gospace
-pkg
-tags

data/.semaphore/semaphore.yml

@@ -1,45 +0,0 @@
-version: v1.0
-name: Betterlog pipeline
-agent:
-  machine:
-    type: e1-standard-2
-    os_image: ubuntu2004
-
-blocks:
-  - name: Caching
-    task:
-      prologue:
-        commands:
-          - checkout
-      jobs:
-        - name: cache bundle
-          commands:
-            - sem-version ruby $(awk '/^ruby/ { print $2 }' .tool-versions)
-            - cache restore gems-$SEMAPHORE_GIT_BRANCH,gems-master
-            - bundle config set path 'vendor/bundle'
-            - bundle config jobs $(getconf _NPROCESSORS_ONLN)
-            - bundle install
-            - cache store gems-$SEMAPHORE_GIT_BRANCH vendor/bundle
-
-  - name: "Unit tests"
-    task:
-      env_vars:
-        - name: RAILS_ENV
-          value: test
-      prologue:
-        commands:
-          - checkout
-
-          # Setup ruby
-          - sem-version ruby $(awk '/^ruby/ { print $2 }' .tool-versions)
-
-          # Setup gems
-          - cache restore gems-$SEMAPHORE_GIT_BRANCH,gems-master
-          - bundle config set path 'vendor/bundle'
-          - bundle config jobs $(getconf _NPROCESSORS_ONLN)
-          - bundle install
-
-      jobs:
-        - name: RSpec Unit Tests
-          commands:
-            - bundle exec rake

data/.tool-versions

@@ -1 +0,0 @@
-ruby 3.4.1