Merge pull request #21 from on-strum/develop

OnStrum::Logs v0.3.0

Author: bestwebua

.reek.yml

@@ -13,6 +13,7 @@ detectors:
     exclude:
       - OnStrum::Logs::Configuration#valid_argument_type?
       - OnStrum::Logs::Logger::Default#configuration
+      - OnStrum::Logs::Configuration#instance_initializer
 
   FeatureEnvy:
     exclude:
@@ -22,5 +23,9 @@ detectors:
     exclude:
       - OnStrum::Logs::Configuration#detailed_formatter
 
+  TooManyStatements:
+    exclude:
+      - OnStrum::Logs::Logger::Default#hash_normalizer
+
 exclude_paths:
   - spec/support/helpers

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2024-03-10
+
+### Added
+
+- Added ability to configure builtin attribute key names
+
+### Updated
+
+- Updated `OnStrum::Logs::Configuration`, tests
+- Updated `OnStrum::Logs::Logger::Default`, tests
+- Updated `OnStrum::Logs::Formatter::Base`, tests
+- Updated `OnStrum::Logs::Formatter::Json`, tests
+- Updated `OnStrum::Logs::RspecHelper::Configuration`, tests
+- Updated `OnStrum::Logs::RspecHelper::ContextGenerator`, tests
+- Updated gem documentation
+
 ## [0.2.0] - 2024-03-05
 
 ### Added

README.md

@@ -34,7 +34,8 @@ Simple configurable structured logger with `JSON` formatter out of the box.
 
 - Structured `JSON` log
 - Built-in detailed (debug) formatter
-- Ability to configure required parameters
+- Ability to configure builtin attribute key names
+- Ability to configure required attributes
 - Ability to configure formatters
 - Ability to serialize an exceptions into structured log
 
@@ -85,6 +86,30 @@ OnStrum::Logs.configure do |config|
   # Optional parameter. You can use your custom formatter insted of built-in.
   # Please note, using this option will override using detailed_formatter option.
   config.custom_formatter = YourCustomFormatter
+
+  # Optional parameter. You can override log level builtin attribute key.
+  # It is equal to :level by default.
+  config.field_name_level = :log_level
+
+  # Optional parameter. You can override log time builtin attribute key.
+  # It is equal to :time by default.
+  config.field_name_time = :log_time
+
+  # Optional parameter. You can override log message builtin attribute key.
+  # It is equal to :message by default.
+  config.field_name_message = :log_message
+
+  # Optional parameter. You can override log context builtin attribute key.
+  # It is equal to :context by default.
+  config.field_name_context = :log_context
+
+  # Optional parameter. You can override log exception message builtin attribute key.
+  # It is equal to :message by default.
+  config.field_name_exception_message = :log_exception_message
+
+  # Optional parameter. You can override log exception stack trace builtin attribute key.
+  # It is equal to :stack_trace by default.
+  config.field_name_exception_stack_trace = :log_exception_stack_trace
 end
 ```
 

lib/on_strum/logs/configuration.rb

@@ -4,12 +4,24 @@ module OnStrum
   module Logs
     class Configuration
       INCOMPLETE_CONFIG = 'service_name, service_version are required parameters'
-      SETTERS = %i[custom_formatter service_name service_version].freeze
+      SETTERS = %i[
+        custom_formatter
+        service_name
+        service_version
+        field_name_level
+        field_name_time
+        field_name_message
+        field_name_context
+        field_name_exception_message
+        field_name_exception_stack_trace
+      ].freeze
+      BUILTIN_FIELDS_DEFAULT_NAMES = %i[level time message context stack_trace].freeze
 
       attr_reader(*OnStrum::Logs::Configuration::SETTERS)
       attr_accessor :detailed_formatter
 
       def initialize(&block)
+        instance_initializer.each { |instace_variable, value| instance_variable_set(:"@#{instace_variable}", value) }
         tap(&block) if block
       end
 
@@ -28,12 +40,32 @@ def formatter
         custom_formatter || builded_formatter
       end
 
+      # TODO: hardcoded fields will be removed in next release
+      def log_attributes_order
+        @log_attributes_order ||= OnStrum::Logs::Configuration::SETTERS[3..6].map do |field_name_getter|
+          public_send(field_name_getter)
+        end + %i[service_name service_version]
+      end
+
       private
 
+      def instance_initializer
+        message_key = OnStrum::Logs::Configuration::BUILTIN_FIELDS_DEFAULT_NAMES[2]
+        {
+          field_name_level: OnStrum::Logs::Configuration::BUILTIN_FIELDS_DEFAULT_NAMES[0],
+          field_name_time: OnStrum::Logs::Configuration::BUILTIN_FIELDS_DEFAULT_NAMES[1],
+          field_name_message: message_key,
+          field_name_context: OnStrum::Logs::Configuration::BUILTIN_FIELDS_DEFAULT_NAMES[3],
+          field_name_exception_message: message_key,
+          field_name_exception_stack_trace: OnStrum::Logs::Configuration::BUILTIN_FIELDS_DEFAULT_NAMES[4]
+        }
+      end
+
       def valid_argument_type?(method_name, argument)
         argument.is_a?(
           case method_name
           when :service_name, :service_version then ::String
+          when *OnStrum::Logs::Configuration::SETTERS[3..-1] then ::Symbol
           when :custom_formatter then ::Class
           end
         )

lib/on_strum/logs/formatter/base.rb

@@ -5,10 +5,9 @@ module Logs
     module Formatter
       class Base
         DATETIME_FORMAT = '%FT%T.%3N%:z'
-        LOG_ATTRIBUTES_ORDER = %i[level time message context service_name service_version].freeze
 
         def self.arrange_attrs(**log_data)
-          OnStrum::Logs::Formatter::Base::LOG_ATTRIBUTES_ORDER.each_with_object({}) do |attribute, arranged_attrs|
+          OnStrum::Logs.configuration.log_attributes_order.each_with_object({}) do |attribute, arranged_attrs|
             arranged_attrs[attribute] = log_data[attribute]
           end
         end

lib/on_strum/logs/formatter/json.rb

@@ -6,10 +6,11 @@ module Formatter
       class Json < Base
         require 'json'
 
-        def self.call(time:, **log_data)
+        def self.call(**log_data)
+          time_key = OnStrum::Logs.configuration.field_name_time
           json_log = arrange_attrs(
-            time: time.strftime(OnStrum::Logs::Formatter::Base::DATETIME_FORMAT),
-            **log_data
+            **log_data,
+            time_key => log_data[time_key].strftime(OnStrum::Logs::Formatter::Base::DATETIME_FORMAT)
           ).to_json
 
           "#{json_log}\n"

lib/on_strum/logs/logger/default.rb

@@ -20,7 +20,10 @@ def initialize
 
             # TODO: we need to have ability to process log data before render it to STDOUT/STDERR
             # hash_normalizer(arg); after_callback.call(arg)
-            logger.public_send(method_name, hash_normalizer(arg).merge(level: method_name.to_s.upcase))
+            logger.public_send(
+              method_name,
+              hash_normalizer(arg).merge(configuration.field_name_level => method_name.to_s.upcase)
+            )
           end
         end
 
@@ -35,7 +38,7 @@ def configuration
         def formatter
           @formatter ||= proc do |_severity, datetime, _progname, log_data|
             configuration.formatter.call(
-              time: datetime,
+              configuration.field_name_time => datetime,
               service_name: configuration.service_name,
               service_version: configuration.service_version,
               **log_data
@@ -44,20 +47,22 @@ def formatter
         end
 
         def hash_normalizer(object)
+          message_key, context_key = configuration.field_name_message, configuration.field_name_context
+
           case object
           when ::Hash
-            raise OnStrum::Logs::Error::Logger unless object.key?(:message)
+            raise OnStrum::Logs::Error::Logger unless object.key?(message_key)
 
-            { message: object.delete(:message), context: (object.empty? ? nil : object) }
+            { message_key => object.delete(message_key), context_key => (object.empty? ? nil : object) }
           when ::Exception
             {
-              message: "Exception: #{object.class}",
-              context: {
-                message: object.message,
-                stack_trace: object.backtrace
+              message_key => "Exception: #{object.class}",
+              context_key => {
+                configuration.field_name_exception_message => object.message,
+                configuration.field_name_exception_stack_trace => object.backtrace
               }
             }
-          else { message: object.to_s, context: nil }
+          else { message_key => object.to_s, context_key => nil }
           end
         end
       end

lib/on_strum/logs/version.rb

@@ -2,6 +2,6 @@
 
 module OnStrum
   module Logs
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

spec/on_strum/logs/configuration_spec.rb

@@ -4,21 +4,34 @@
   describe 'defined constants' do
     it { expect(described_class).to be_const_defined(:INCOMPLETE_CONFIG) }
     it { expect(described_class).to be_const_defined(:SETTERS) }
+    it { expect(described_class).to be_const_defined(:BUILTIN_FIELDS_DEFAULT_NAMES) }
   end
 
   describe '.new' do
     let(:custom_formatter) { use_formatter(:custom) }
     let(:detailed_formatter) { true }
     let(:service_name) { random_service_name }
     let(:service_version) { random_semver }
+    let(:field_name_level) { random_field_name }
+    let(:field_name_time) { random_field_name }
+    let(:field_name_message) { random_field_name }
+    let(:field_name_context) { random_field_name }
+    let(:field_name_exception_message) { random_field_name }
+    let(:field_name_exception_stack_trace) { random_field_name }
 
     context 'when valid configuration' do
       subject(:configuration) do
         create_configuration(
           custom_formatter: custom_formatter,
           detailed_formatter: detailed_formatter,
           service_name: service_name,
-          service_version: service_version
+          service_version: service_version,
+          field_name_level: field_name_level,
+          field_name_time: field_name_time,
+          field_name_message: field_name_message,
+          field_name_context: field_name_context,
+          field_name_exception_message: field_name_exception_message,
+          field_name_exception_stack_trace: field_name_exception_stack_trace
         )
       end
 
@@ -27,6 +40,12 @@
         expect(configuration.detailed_formatter).to eq(detailed_formatter)
         expect(configuration.service_name).to eq(service_name)
         expect(configuration.service_version).to eq(service_version)
+        expect(configuration.field_name_level).to eq(field_name_level)
+        expect(configuration.field_name_time).to eq(field_name_time)
+        expect(configuration.field_name_message).to eq(field_name_message)
+        expect(configuration.field_name_context).to eq(field_name_context)
+        expect(configuration.field_name_exception_message).to eq(field_name_exception_message)
+        expect(configuration.field_name_exception_stack_trace).to eq(field_name_exception_stack_trace)
         expect(configuration).to be_complete
       end
     end
@@ -76,6 +95,22 @@
 
         include_examples 'raies argument error'
       end
+
+      OnStrum::Logs::Configuration::SETTERS[3..-1].each do |field_name_setter|
+        context "when argument #{field_name_setter}= invalid" do
+          subject(:configuration) do
+            create_configuration(
+              service_name: random_service_name,
+              service_version: random_semver,
+              field_name_setter => invalid_argument
+            )
+          end
+
+          let(:expected_error_message) { "#{invalid_argument} is not a valid #{field_name_setter}=" }
+
+          include_examples 'raies argument error'
+        end
+      end
     end
 
     context 'when configuration without block' do
@@ -85,6 +120,12 @@
         expect(configuration.service_name).to be_nil
         expect(configuration.service_version).to be_nil
         expect(configuration.custom_formatter).to be_nil
+        expect(configuration.field_name_level).to eq(:level)
+        expect(configuration.field_name_time).to eq(:time)
+        expect(configuration.field_name_message).to eq(:message)
+        expect(configuration.field_name_context).to eq(:context)
+        expect(configuration.field_name_exception_message).to eq(:message)
+        expect(configuration.field_name_exception_stack_trace).to eq(:stack_trace)
         expect(configuration.detailed_formatter).to be_nil
         expect(configuration).not_to be_complete
       end
@@ -156,4 +197,30 @@
       include_examples 'returns target formatter'
     end
   end
+
+  describe '#log_attributes_order' do
+    subject(:log_attributes_order) { configuration_instance.log_attributes_order }
+
+    let(:configuration_instance) do
+      create_configuration(
+        field_name_level: random_field_name,
+        field_name_time: random_field_name,
+        field_name_message: random_field_name,
+        field_name_context: random_field_name
+      )
+    end
+
+    it 'returns log attributes order' do
+      expect(log_attributes_order).to eq(
+        [
+          configuration_instance.field_name_level,
+          configuration_instance.field_name_time,
+          configuration_instance.field_name_message,
+          configuration_instance.field_name_context,
+          :service_name,
+          :service_version
+        ]
+      )
+    end
+  end
 end

spec/on_strum/logs/formatter/base_spec.rb

@@ -3,12 +3,24 @@
 RSpec.describe OnStrum::Logs::Formatter::Base do
   describe 'defined constants' do
     it { expect(described_class).to be_const_defined(:DATETIME_FORMAT) }
-    it { expect(described_class).to be_const_defined(:LOG_ATTRIBUTES_ORDER) }
   end
 
   describe '.arrange_attrs' do
     subject(:arrange_attrs) { described_class.arrange_attrs(**log_data) }
 
+    let!(:configuration_instance) do
+      init_configuration(
+        field_name_level: field_name_level,
+        field_name_time: field_name_time,
+        field_name_message: field_name_message,
+        field_name_context: field_name_context
+      )
+    end
+
+    let(:field_name_level) { :a }
+    let(:field_name_time) { :b }
+    let(:field_name_message) { :c }
+    let(:field_name_context) { :d }
     let(:level) { random_log_level }
     let(:time) { random_datetime }
     let(:message) { random_message }
@@ -17,17 +29,17 @@
     let(:service_version) { random_semver }
     let(:log_data) do
       [
-        [:level, level],
-        [:time, time],
+        [field_name_level, level],
+        [field_name_time, time],
         [:service_name, service_name],
         [:service_version, service_version],
-        [:message, message],
-        [:context, context]
+        [field_name_message, message],
+        [field_name_context, context]
       ].shuffle.to_h
     end
 
     it 'arranges log data by predefined order' do
-      expect(arrange_attrs.keys).to eq(described_class::LOG_ATTRIBUTES_ORDER)
+      expect(arrange_attrs.keys).to eq(configuration_instance.log_attributes_order)
     end
   end
 end