log4j2_logger_bridge 1.0.1-java → 1.1.1-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f03bc99125d4e93d9c2b50ffa1e105881bf26d933faeb179caa55cda476bf0c0
-  data.tar.gz: 6d2de401a6ea49ca9f932edfc2852da7152c5eb86c52fe27d0626e945b4826ac
+  metadata.gz: 0ed8508f36743d2f912be5d41a6d6acbc7cf408aa823c6e93627b12ac1a19bbf
+  data.tar.gz: 6aea8a650f7076ed1e648cf74281b40bad6ec8e58bc69de7f5d406ec0f531524
 SHA512:
-  metadata.gz: 544eb01b920127d42859a28a96b3e31da2091e589735de2d8ebedb9999e580fbf5c3d318b456890b885aabe1c709a3942f1250e48a041d0562b00238ae1005da
-  data.tar.gz: cb8ddfbd3ae21e86376a89695d14dbff8b4e137fb38039238d4f8e2004623b4e2f24fa1d691484d9a82f73c72daea8a73aafeedf8802777c522142ee0acd18f3
+  metadata.gz: e816e54807be7a57e9ecc9da2bc658eef0481cbdebe79b3bb818d004f36ed90be2a4c1f58f592288f64a8cd9bb2683285d26ec41b2c46f65f22f15ad77b1d8ee
+  data.tar.gz: 1b935f796dee964f6f1b8d42f2b58d9d9fdd882fe380faecbafa0d173dcca8e54aadb52fa09e3c2fbf2427eb36825716a2e36985be6df2345c2b2c99634a51a1

data/README.md

@@ -6,3 +6,211 @@ It attempts to provide a single unified interface for both logging
 technologies, so that switching between either backend can be accomplished
 without much effort.
 
+Below are usage examples for `log4j2_logger_bridge`, based on the gem's public API (notably `Log4j2LoggerBridge.log_level=`, the injected `log`/`logger` proxy, and `Log4j2LoggerBridge.configure_destination` for log file + rollover). 
+
+
+## Install
+
+Install the gem.
+
+
+### Gemfile
+
+Specify the gem inclusion in your project's Ruby Gemfile.
+
+```ruby
+gem 'log4j2_logger_bridge'
+```
+
+
+### Require
+
+Load the gem in a Ruby code module.
+
+```ruby
+require 'log4j2_logger_bridge'
+```
+
+
+## Quick-start
+
+Gotta go fast.
+
+
+### 1) Log to stdout
+
+Example of simply logging to stdout with default configuration.
+
+```ruby
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'log4j2_logger_bridge'
+
+module Example
+  module_function
+
+  def main
+    log.info("Hello from the bridge.")
+    log.warn("This is a warning!")
+    log.error("This is an error!")
+  end
+end
+
+Example.main
+```
+
+For example:
+
+```
+$ bundle exec ruby scripts/example.rb
+18:13:28,236 INFO  [Example] Hello from the bridge.
+18:13:28,238 WARN  [Example] This is a warning!
+18:13:28,238 ERROR [Example] This is an error!
+```
+
+Levels include: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
+
+
+### 2) Categories (optional)
+
+Categories are set automatically from the receiver/callsite, but you can also force one:
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'log4j2_logger_bridge'
+
+Log4j2LoggerBridge.with_category("MyCategory") do
+  log.info("this line is tagged with MyCategory")
+end
+```
+
+
+## In a project with OptionParser
+
+Say your project supports:
+
+```ruby
+module MyProject
+  def main(args = parse_arguments)
+    # Your app code here.
+  end
+end
+```
+
+Here is a minimal end-to-end example that matches that pattern:
+
+```ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'log4j2_logger_bridge'
+
+module MyProject
+  class ArgumentsParser
+    attr_reader :parser, :options
+
+    def initialize(option_parser = OptionParser.new)
+      @parser = option_parser
+      @options = { log_level: 0 }
+      @parser.banner = "Usage: #{File.basename($PROGRAM_NAME)} [options]"
+      @parser.on_tail("-v", "--verbose", "Increase verbosity") do
+        @options[:log_level] = @options[:log_level] - 1
+      end
+    end
+  end
+
+  module_function
+
+  def parse_arguments(arguments_parser = ArgumentsParser.new)
+    arguments_parser.parser.parse!(ARGV)
+    arguments_parser.options
+  rescue OptionParser::ParseError => e
+    abort e.message
+  end
+
+  def main(args = parse_arguments)
+    Log4j2LoggerBridge.log_level = args[:log_level]
+
+    log.info("server starting")
+    log.debug("debug details here")
+  end
+end
+
+MyProject.main
+```
+
+Notes:
+
+* The gem accepts `log_level=` as an Integer descending from 0 (`0, -1, -2, ...`) or as a Symbol/String (like `:info`, `"debug"`).
+* With a `-v` flag decreasing the integer, you get more verbosity (for example `0` -> debug, `-1` -> trace, etc.).
+
+
+## Advanced usage: configure rolling log files and log directory
+
+The gem exposes a destination configuration entrypoint that creates the logs directory + log file if missing, and (on JRuby) wires Log4j2 rolling file behavior.
+
+
+### Example
+
+Setting logs directory under your project, and rollover configuration.
+
+```ruby
+# frozen_string_literal: true
+
+require 'log4j2_logger_bridge'
+
+Log4j2LoggerBridge.configure_destination do |c|
+  c.project_dir_path = File.expand_path('..', __dir__) # repo/app root
+  c.logs_dir_name = 'logs'
+  c.app_name = 'my_project'
+  c.log_file_name = 'my_project.log'
+
+  # Rolling policy knobs:
+  c.rollover_size = '250M'
+  c.rollover_schedule = '0 0 0 * * ?' # cron-style schedule used by Log4j2
+  # Optional: override pattern for rolled files
+  c.rolling_file_name_template = 'my_project-%d{yyyy-MM-dd}.log.gz'
+end
+
+Log4j2LoggerBridge.log_level = :info
+log.info("logging to file (and rolling per settings)")
+```
+
+How to think about it:
+
+* Call `configure_destination` once at process startup (before heavy logging).
+* Keep the config close to your app's boot path (for example, in `config/boot.rb` or similar).
+
+
+## Practical integration pattern
+
+A common layout:
+
+```ruby
+# lib/my_app/boot.rb
+# frozen_string_literal: true
+
+require 'log4j2_logger_bridge'
+
+module MyApp
+  module Boot
+    module_function
+
+    def setup_logging!(args)
+      Log4j2LoggerBridge.configure_destination do |c|
+        c.project_dir_path = args.fetch(:project_dir_path, Dir.pwd)
+        c.logs_dir_name = args.fetch(:logs_dir_name, 'logs')
+        c.app_name = args.fetch(:app_name, 'my_app')
+        c.rollover_size = args.fetch(:rollover_size, '100M')
+      end
+
+      Log4j2LoggerBridge.log_level = args.fetch(:log_level, :info)
+    end
+  end
+end
+```
+
+Then call `MyApp::Boot.setup_logging!(args)` from `main` right after parsing options.

data/lib/log4j2_logger_bridge/backend.rb

@@ -22,11 +22,12 @@ if Log4j2LoggerBridge::Utils.jruby?
 end
 
 require 'fileutils'
-require 'logger'
 
+require_relative 'destination'
 require_relative 'helpers'
 require_relative 'injection'
 require_relative 'log4j2_initialization_methods'
+require_relative 'log4j2_rolling_file'
 require_relative 'ruby_logger_initialization_methods'
 require_relative 'proxy'
 
@@ -50,6 +51,29 @@ module Log4j2LoggerBridge
     init_ruby_logger_backend
   end
 
+  # Public API: configure file destination + rollover.
+  # Example:
+  # Log4j2LoggerBridge.configure_destination do |c|
+  #   c.project_dir_path = File.realpath(__dir__)
+  #   c.rollover_size = '100M'
+  # end
+  def configure_destination(&block)
+    Log4j2LoggerBridge::Destination.configure(&block)
+  end
+
+  # Convenience: direct access to rollover settings.
+  def rollover
+    Log4j2LoggerBridge::Destination.rollover
+  end
+
+  def logs_dir_path
+    Log4j2LoggerBridge::Destination.logs_dir_path
+  end
+
+  def log_file_path
+    Log4j2LoggerBridge::Destination.log_file_path
+  end
+
   def dispatch(level, *args, &block)
     return backend.public_send(level, *args, &block) if Utils.jruby?
 

data/lib/log4j2_logger_bridge/constants.rb

@@ -4,15 +4,20 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 
+require 'logger'
+
 # The Log4j2LoggerBridge module
 module Log4j2LoggerBridge
   # The Constants module
   module Constants
-    DEFAULT_TIME_FORMAT = '%Y-%m-%d %H:%M:%S'.freeze
+    DEFAULT_TIMESTAMP_FORMAT = '%Y-%m-%d %H:%M:%S'.freeze
     DEFAULT_APP_NAME = 'app'.freeze
     DEFAULT_LOG_PATTERN = '%d{ABSOLUTE} %-5p [%X{category}] %m%n'.freeze
     DEFAULT_RUBY_LOG_FORMAT =
       "%<timestamp>s %-5<severity>s [%<category>s] %<msg>s\n".freeze
+    DEFAULT_ROLLOVER_SCHEDULE = '0 0 0 * * ?'.freeze
+    DEFAULT_ROLLOVER_SIZE = '100M'.freeze
+    DEFAULT_LOGS_DIR_NAME = 'logs'.freeze
     EMPTY_STRING = ''.freeze
 
     NUMERIC_TO_SYMBOL = {

data/lib/log4j2_logger_bridge/destination.rb

@@ -0,0 +1,107 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+require 'fileutils'
+
+require_relative 'constants'
+
+module Log4j2LoggerBridge
+  # Centralized destination config for both CRuby Logger and JRuby Log4j2.
+  module Destination
+    # The Configuration class for the Destination module
+    class Configuration
+      include Constants
+
+      attr_accessor :project_dir_path, :app_name, :logs_dir_name,
+        :log_file_name, :timestamp_format, :rollover_schedule,
+        :rollover_size, :rolling_file_name_template
+
+      def initialize
+        @project_dir_path = Dir.pwd
+        @app_name = File.basename(@project_dir_path.to_s)
+        @logs_dir_name = DEFAULT_LOGS_DIR_NAME
+        @log_file_name = "#{@app_name}.log"
+        @timestamp_format = DEFAULT_TIMESTAMP_FORMAT
+        @rollover_schedule = DEFAULT_ROLLOVER_SCHEDULE
+        @rollover_size = DEFAULT_ROLLOVER_SIZE
+        @rolling_file_name_template = nil
+      end
+
+      def logs_dir_path
+        File.expand_path(File.join(project_dir_path, logs_dir_name))
+      end
+
+      def log_file_path
+        File.expand_path(File.join(logs_dir_path, log_file_name))
+      end
+
+      def resolved_rolling_file_name_template
+        template = rolling_file_name_template
+        return File.expand_path(template) if template && !template.strip.empty?
+
+        File.expand_path(
+          File.join(logs_dir_path, "#{app_name}-%d{yyyy-MM-dd}.log.gz")
+        )
+      end
+
+      def ensure_paths!
+        FileUtils.mkdir_p(logs_dir_path)
+        FileUtils.touch(log_file_path)
+      end
+
+      def rollover
+        {
+          schedule: rollover_schedule,
+          size: rollover_size,
+          file_pattern: resolved_rolling_file_name_template
+        }
+      end
+    end
+    # class Configuration
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Example:
+      # Log4j2LoggerBridge::Destination.configure do |c|
+      #   c.project_dir_path = '/srv/myapp'
+      #   c.rollover_size = '250M'
+      # end
+      def configure
+        yield(config)
+        config.ensure_paths!
+        config
+      end
+
+      def logs_dir_path
+        config.logs_dir_path
+      end
+
+      def log_file_path
+        config.log_file_path
+      end
+
+      def rollover
+        config.rollover
+      end
+
+      def rollover_schedule=(value)
+        config.rollover_schedule = value
+      end
+
+      def rollover_size=(value)
+        config.rollover_size = value
+      end
+
+      def rolling_file_name_template=(value)
+        config.rolling_file_name_template = value
+      end
+    end
+    # class << self
+  end
+end

data/lib/log4j2_logger_bridge/helpers.rb

@@ -22,8 +22,8 @@ module Log4j2LoggerBridge
       DEFAULT_APP_NAME
     end
 
-    def time_format
-      DEFAULT_TIME_FORMAT
+    def timestamp_format
+      DEFAULT_TIMESTAMP_FORMAT
     end
 
     def ruby_log_format

data/lib/log4j2_logger_bridge/log4j2_initialization_methods.rb

@@ -24,6 +24,12 @@ module Log4j2LoggerBridge
 
       configure_log4j
 
+      Log4j2LoggerBridge::Log4j2RollingFile.apply!(
+        builder: @log4j_configuration,
+        root_logger: @root_logger,
+        layout: @layout
+      )
+
       @log4j2_initialized = true
     end
 
@@ -32,18 +38,21 @@ module Log4j2LoggerBridge
       @log4j2_context.updateLoggers
     end
 
+    def log4j_configuration
+      @log4j_configuration ||= init_config
+    end
+
     # rubocop: disable Metrics/AbcSize
     # rubocop: disable Metrics/MethodLength
-    def log4j_configuration(
-        config = ConfigurationBuilderFactory.newConfigurationBuilder)
-      layout = config.newLayout('PatternLayout')
+    def init_config(config = ConfigurationBuilderFactory.newConfigurationBuilder)
+      @layout = config.newLayout('PatternLayout')
         .addAttribute('pattern', java_log_pattern)
       console = config.newAppender('stdout', 'CONSOLE')
-        .addAttribute('target', ConsoleAppender::Target::SYSTEM_OUT).add(layout)
+        .addAttribute('target', ConsoleAppender::Target::SYSTEM_OUT).add(@layout)
       config.add(console)
-      root = config.newRootLogger(Level::INFO)
+      @root_logger = config.newRootLogger(Level::INFO)
         .add(config.newAppenderRef('stdout'))
-      config.add(root)
+      config.add(@root_logger)
       app_logger = config.newLogger(app_logger_name, Level::INFO)
         .add(config.newAppenderRef('stdout'))
         .addAttribute('additivity', false)

data/lib/log4j2_logger_bridge/log4j2_rolling_file.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# The Log4j2LoggerBridge module
+module Log4j2LoggerBridge
+  # The Log4j2RollingFile module
+  module Log4j2RollingFile
+    def apply!(builder:, root_logger:, layout:)
+      destination = Log4j2LoggerBridge::Destination.config
+      destination.ensure_paths!
+
+      cron_policy = build_cron_policy(builder, destination)
+      size_policy = build_size_policy(builder, destination)
+      policies = build_policies(builder, cron_policy, size_policy)
+
+      build_and_add_rolling_appender(builder, layout, destination, policies)
+      attach_rolling_appender_to_root(builder, root_logger)
+    end
+    module_function :apply!
+
+    def build_cron_policy(builder, destination)
+      cron = builder.newComponent('CronTriggeringPolicy')
+      cron.addAttribute('schedule', destination.rollover_schedule)
+    end
+    module_function :build_cron_policy
+
+    def build_size_policy(builder, destination)
+      size = builder.newComponent('SizeBasedTriggeringPolicy')
+      size.addAttribute('size', destination.rollover_size)
+    end
+    module_function :build_size_policy
+
+    def build_policies(builder, cron_policy, size_policy)
+      policies = builder.newComponent('Policies')
+      policies = policies.addComponent(cron_policy)
+      policies.addComponent(size_policy)
+    end
+    module_function :build_policies
+
+    def build_and_add_rolling_appender(builder, layout, destination, policies)
+      appender = builder.newAppender('rolling_file', 'RollingFile')
+      appender = appender.addAttribute('fileName', destination.log_file_path)
+      appender = appender.addAttribute(
+        'filePattern',
+        destination.resolved_rolling_file_name_template
+      )
+      appender = appender.add(layout)
+      appender = appender.addComponent(policies)
+      builder.add(appender)
+    end
+    module_function :build_and_add_rolling_appender
+
+    def attach_rolling_appender_to_root(builder, root_logger)
+      root_logger = root_logger.addAttribute('additivity', false)
+      root_logger.add(builder.newAppenderRef('rolling_file'))
+    end
+    module_function :attach_rolling_appender_to_root
+  end
+end

data/lib/log4j2_logger_bridge/ruby_logger_initialization_methods.rb

@@ -21,7 +21,7 @@ module Log4j2LoggerBridge
 
     def ruby_formatter(severity, datetime, _progname, msg)
       category = (Thread.current[:logging_category] || app_name).to_s
-      timestamp = datetime.strftime(time_format)
+      timestamp = datetime.strftime(timestamp_format)
       format(ruby_log_format, timestamp: timestamp,
         severity: severity_label(severity), category: category, msg: msg)
     end

data/lib/log4j2_logger_bridge/version.rb

@@ -4,6 +4,7 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 
+# The Log4j2LoggerBridge module
 module Log4j2LoggerBridge
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.1.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: log4j2_logger_bridge
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.1
 platform: java
 authors:
 - Nels Nelson
@@ -49,9 +49,11 @@ files:
 - lib/log4j2_logger_bridge.rb
 - lib/log4j2_logger_bridge/backend.rb
 - lib/log4j2_logger_bridge/constants.rb
+- lib/log4j2_logger_bridge/destination.rb
 - lib/log4j2_logger_bridge/helpers.rb
 - lib/log4j2_logger_bridge/injection.rb
 - lib/log4j2_logger_bridge/log4j2_initialization_methods.rb
+- lib/log4j2_logger_bridge/log4j2_rolling_file.rb
 - lib/log4j2_logger_bridge/proxy.rb
 - lib/log4j2_logger_bridge/ruby_logger_initialization_methods.rb
 - lib/log4j2_logger_bridge/utils.rb