relaton-logger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2da06b3c702a902ef2fc5110c19a2c1f0c997caa3409a2c014fa2b8968ec0873
+  data.tar.gz: 7908c829ec6d272cc924d0ae64a100f13b473945f0bca7496679215f515ccb8a
+SHA512:
+  metadata.gz: 6b484c092d45bc81bab1c0551f48f81df0b64eb1f23eea52fa341f1fc1a8893264ee03e3de18a9af2f056e316a86d6002e9227e98555c80357d922465cc8d81d
+  data.tar.gz: cbae4869240542f537409d49c05864de5ca358fc17698fab793c794e7a2338cb8673524e450aebc9e1ea27adc7416c05912622bf6f92bd23e4ff684887554b80

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+require: rubocop-rails
+
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+AllCops:
+  TargetRubyVersion: 2.7
+Rails:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Andrei Kislichenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,132 @@
+= Relaton::Logger
+
+image:https://img.shields.io/gem/v/relaton-logger.svg["Gem Version", link="https://rubygems.org/gems/relaton-logger"]
+image:https://github.com/relaton/relaton-logger/workflows/rake/badge.svg["Build Status", link="https://github.com/relaton/relaton-logger/actions?workflow=rake"]
+image:https://codeclimate.com/github/relaton/relaton-logger/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/relaton/relaton-logger"]
+image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-logger.svg["Pull Requests", link="https://github.com/relaton/relaton-logger/pulls"]
+image:https://img.shields.io/github/commits-since/relaton/relaton-logger/latest.svg["Commits since latest",link="https://github.com/relaton/relaton-logger/releases"]
+
+Relaton::Logger is a Ruby gem that implements a logger for Relaton gems. It is also possible to use this gem as a standalone logger.
+
+== Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add relaton-logger
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install relaton-logger
+
+== Usage
+
+The Relaton::Logger gem provides a logger pool that can be used to log messages. The logger pool is a singleton and can be accessed by calling `Relaton.logger_pool`. The logger pool is an Array that contains loggers. By default, the logger pool contains a single logger, which is an instance of `Relaton::Logger::Log` class, which inherits the `Logger` class from the Ruby standard library.
+
+The logger pool can be used to log messages by calling the methods of the loggers in the pool. These methods are the same as the methods of the `Logger` class from the Ruby standard library (`debug`, `info`, `warn`, `error`, `fatal`, `unknown`).
+
+[source, ruby]
+----
+require "relaton/logger"
+
+Relaton.logger_pool.info "message"
+INFO: message
+----
+
+The program name and the key can be passed as arguments to the log methods. The program name is a string that is added to the log message. The key is a string that is added to the log message in parentheses.
+
+[source, ruby]
+----
+Relaton.logger_pool.warn "message", "progname", key: "KEY"
+[progname] WARN: (KEY) message
+----
+
+The block form of the log methods can be used to log messages that are expensive to generate. The block is called only if the message is logged.
+
+[source, ruby]
+----
+Relaton.logger_pool.error("progname", key: "KEY") { "message" }
+[progname] ERROR: (KEY) message
+----
+
+The logger pool can configured to contain multiple loggers. The loggers in the pool are called in the order they are added to the pool. To add a logger to the pool, call the `<<` method of the logger pool and pass the logger as an argument.
+
+[source, ruby]
+----
+Relaton::Logger.configure do |config|
+  config.logger_pool << Relaton::Logger::Log.new("relaton.log", levels: [:info, :warn])
+end
+----
+
+To replace the loggers in the pool, use `=` method of the logger pool and pass the new loggers as an argument.
+
+[source, ruby]
+----
+Relaton::Logger.configure do |config|
+  config.logger_pool = [Relaton::Logger::Log.new("relaton.log", levels: [:info, :warn])]
+end
+----
+
+To create a new logger, call the `new` method of the `Relaton::Logger::Log` class and pass arguments:
+
+- `logdev` - file name or an IO object. If nil or File::NULL, messages are not logged. If it is a file name, the file is opened in append mode. If it is an IO object, messages are written to it.
+- `shift_age` - the number of old log files to keep. If 0, no old log files are kept. If it is a number, old log files are kept and the log file is rotated when it reaches the maximum size. If it is a string, old log files are kept and the log file is rotated when it reaches the maximum size. The string is a time unit and a number, for example, "daily 7" or "weekly 4". Default is 0.
+- `shift_size` - the maximum size of the log file. If it is a number, the log file is rotated when it reaches the maximum size. If it is a string, the log file is rotated when it reaches the maximum size. The string is a number and a time unit, for example, "1048576" or "1M". Default is 1048576.
+- `levels` - an array of symbols that represent the log levels The log levels are `:debug`, `:info`, `:warn`, `:error`, `:fatal`, `:unknown`. Default is `[:info, :warn, :error, :fatal, :unknown]`.
+- `formatter` - a formatter object that is used to format the log messages. Two formatters are available at this moment `Relaton::Logger::FormatterString`, `Relaton::Logger::FormatterJson`, and `Proc`. The default formater is `Relaton::Logger::FormatterString`.
+- `progname` - a string that is added to the log message. Default is nil.
+
+[source, ruby]
+----
+Relaton::Logger::Log.new("relaton.log", levels: [:info, :warn], formatter: Relaton::Logger::FormatterJSON, progname: "progname")
+----
+
+To create a custom formatter implement a class with the `call` method which takes agruments:
+
+- `severity` - the log level
+- `time` - the time the message was logged
+- `progname` - the program name
+- `msg` - the message
+- any other keyword arguments that are passed to the log method, for example, `key`
+
+[source, ruby]
+----
+class CustomFormatter
+  def call(severity, time, progname, msg, key: "Key 1")
+    "#{time} [#{severity}] #{progname} (#{key}): #{msg}\n"
+  end
+end
+
+Relaton::Logger::Log.new("relaton.log", formatter: CustomFormatter)
+----
+
+It's possible to use `Proc` as a formatter. The `Proc` object is called with the same arguments as the `call` method of the custom formatter.
+
+[source, ruby]
+----
+log = Relaton::Logger::Log.new("relaton.log")
+
+log.formatter = Proc.new do |severity, time, progname, msg, key: "Key 1"|
+  "#{time} [#{severity}] #{progname} (#{key}): #{msg}\n"
+end
+----
+
+A log file can be cleared by calling the `truncate` method of the logger pool.
+
+[source, ruby]
+----
+Relaton.logger_pool.truncate
+----
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-logger.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec]

data/lib/relaton/logger/config.rb

@@ -0,0 +1,34 @@
+module Relaton::Logger
+  module Config
+    def configure
+      yield configuration if block_given?
+    end
+
+    def configuration
+      @configuration ||= self::Configuration.new
+    end
+  end
+
+  class Configuration
+    # @return [Array<Relaton::Logger::Log>] List of loggers
+    attr_reader :logger_pool
+
+    def initialize
+      @logger_pool ||= Pool.new
+      @logger_pool << Log.new($stderr, levels: %i[info warn error fatal])
+    end
+
+    #
+    # Replace the current list of loggers with the given list of loggers.
+    #
+    # @param [Array<Relaton::Logger::Log>] loggers list of loggers
+    #
+    # @return [void]
+    #
+    def logger_pool=(loggers)
+      @logger_pool.loggers = loggers
+    end
+  end
+
+  extend Config
+end

data/lib/relaton/logger/formatter_json.rb

@@ -0,0 +1,8 @@
+module Relaton::Logger
+  class FormatterJSON < ::Logger::Formatter
+    def call(severity, _datetime, progname, msg, **args)
+      hash = { prog: progname, message: msg, severity: severity }.merge(args)
+      "#{hash.to_json}\n"
+    end
+  end
+end

data/lib/relaton/logger/formatter_string.rb

@@ -0,0 +1,12 @@
+module Relaton::Logger
+  class FormatterString < ::Logger::Formatter
+    def call(severity, _datetime, progname, msg, **args)
+      output = []
+      output << "[#{progname}]" if progname
+      output << "#{severity}:"
+      output << "(#{args[:key]})" if args[:key]
+      output << "#{msg}\n"
+      output.join " "
+    end
+  end
+end

data/lib/relaton/logger/log.rb

@@ -0,0 +1,64 @@
+module Relaton::Logger
+  class Log < ::Logger
+    attr_reader :levels
+
+    def initialize(logdev, shift_age = 0, shift_size = 1_048_576, **args) # rubocop:disable Lint/MissingSuper
+      self.levels = args.delete(:levels) || [UNKNOWN, FATAL, ERROR, WARN, INFO]
+      self.level = @levels.min
+      self.progname = args.delete(:progname)
+      @default_formatter = FormatterString.new
+      self.datetime_format = args.delete(:datetime_format)
+      self.formatter = args.delete(:formatter)
+      self.formatter = self.formatter.new if self.formatter.is_a? Class
+      @logdev = nil
+      @level_override = {}
+      if logdev && logdev != File::NULL
+        @logdev = LogDevice.new(logdev, shift_age: shift_age, shift_size: shift_size, **args)
+      end
+    end
+
+    def levels=(levels)
+      @levels = Set.new levels.map { |l| Severity.coerce l }
+      self.level = @levels.min
+    end
+
+    def add_level(level)
+      @levels << Severity.coerce(level)
+      self.level = @levels.min
+    end
+
+    def remove_level(level)
+      @levels.delete Severity.coerce(level)
+      self.level = @levels.min
+    end
+
+    def unknown(message = nil, progname = nil, **args, &block)
+      level = Object.const_get "Logger::#{__callee__.to_s.upcase}"
+      add(level, message, progname, **args, &block)
+    end
+
+    %i[fatal error warn info debug].each { |m| alias_method m, :unknown }
+
+    def add(severity, message = nil, progname = nil, **args) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      severity ||= UNKNOWN
+      return true if @logdev.nil? || !@levels.include?(severity)
+
+      if block_given?
+        progname ||= message || @progname
+        message = yield
+      else
+        progname ||= @progname
+      end
+      @logdev.write format_message(format_severity(severity), Time.now, progname, message, **args)
+      true
+    end
+
+    def format_message(severity, datetime, progname, msg, **args)
+      (@formatter || @default_formatter).call(severity, datetime, progname, msg, **args)
+    end
+
+    def truncate
+      @logdev.truncate
+    end
+  end
+end

data/lib/relaton/logger/log_device.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Relaton::Logger
+  class LogDevice < ::Logger::LogDevice
+    #
+    # @param header [Boolean, nil] whether to add header to log file
+    #
+    def initialize(logdev, **args)
+      # TODO: the header is not used yet, maybe it will be used in the future for not JSON formatters
+      @header = args.delete :header
+      super
+    end
+
+    def add_log_header(file)
+      return unless @header
+
+      super
+    end
+
+    def truncate
+      return unless @dev.respond_to? :truncate
+
+      @dev.truncate 0
+      @dev.rewind
+    end
+  end
+end

data/lib/relaton/logger/pool.rb

@@ -0,0 +1,24 @@
+module Relaton::Logger
+  class Pool
+    extend Forwardable
+    def_delegators :@loggers, :<<, :[], :first, :last, :empty?, :any?, :size, :each, :detect, :length
+
+    attr_accessor :loggers
+
+    def initialize
+      @loggers = []
+    end
+
+    def unknown(message = nil, progname = nil, **args, &block)
+      @loggers.each { |logger| logger.send(__callee__, message, progname, **args, &block) }
+      nil
+    end
+
+    %i[fatal error warn info debug].each { |m| alias_method m, :unknown }
+
+    def truncate
+      @loggers.each(&:truncate)
+      nil
+    end
+  end
+end

data/lib/relaton/logger/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Logger
+    VERSION = "0.1.0"
+  end
+end

data/lib/relaton/logger.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "logger"
+require_relative "logger/version"
+require_relative "logger/log"
+require_relative "logger/log_device"
+require_relative "logger/pool"
+require_relative "logger/formatter_string"
+require_relative "logger/formatter_json"
+require_relative "logger/config"
+
+module Relaton
+  def self.logger_pool
+    Logger.configuration.logger_pool
+  end
+end

data/sig/relaton/logger.rbs

@@ -0,0 +1,6 @@
+module Relaton
+  module Logger
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: relaton-logger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+description: The logger for Relaton gem.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- lib/relaton/logger.rb
+- lib/relaton/logger/config.rb
+- lib/relaton/logger/formatter_json.rb
+- lib/relaton/logger/formatter_string.rb
+- lib/relaton/logger/log.rb
+- lib/relaton/logger/log_device.rb
+- lib/relaton/logger/pool.rb
+- lib/relaton/logger/version.rb
+- sig/relaton/logger.rbs
+homepage: https://github.com/relaton/relaton-logger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/relaton/relaton-logger
+  source_code_uri: https://github.com/relaton/relaton-logger
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key: 
+specification_version: 4
+summary: The logger for Relaton gem.
+test_files: []