RTALogger 1.1.1 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b037c1dbb6f51228afd43cfc7e576e86a7e46e711b96cedaaeb9a5b3e5f3f1ec
-  data.tar.gz: d1e2fb9ee4cddf0b221b0ec9c471117953387c502337e3d438b82348ce4111ae
+  metadata.gz: ce594204cc18c9c040fd6efa93a6390ef4ee8d8193dd2f94a5633a4dff82c33b
+  data.tar.gz: a5aa6fb8dcf05c391390d1766fcb536a52da3bd2e5aa381f4084da09a7e15112
 SHA512:
-  metadata.gz: 1fe26e02fcdb17eb44f56644469f7061a925f5dfdc25afcde968b1d910eb5f25a13a49e25afeec8898e78eb7398bbcabe53fca3b7ca98dc85afdeae304ba12a0
-  data.tar.gz: 11fdcff4f789f1eb739cd307c9f60c52b7f6a2816caa60699b0d1f607fba0a3cf7619e58dd17d6817b4711ba35f4998585e64a8d0f099142f8c3009210220759
+  metadata.gz: 18a50c861fbff016f990a89d39e1da24e26dd983f32ac90172818d70f7fca78cabf8c6cc26d624fd901ace2fcfa358fa49b9b0256de6dec48df867972d99757c
+  data.tar.gz: ba39a6640b4ac17499fcad6a7fba72db587430936c0357cfdbbec46e1a292cac28327019943687bef55cd18496fdae568742c3d4ffe11519e2a3836291a41598

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    RTALogger (1.1.1)
+    RTALogger (2.1.1)
       fluent-logger (~> 0.9)
       jbuilder (~> 2.10)
 

data/README.md

@@ -58,12 +58,13 @@ To use log manager APIs, first step is to have a quick review on Log Data Struct
 - At last the final element is log message, which contains log message data.
 
 ### Which Log Severity Levels to use
-- DEBUG = 0 : Low-level information, mostly for developers.
-- INFO = 1 : Generic (useful) information about system operation.
-- WARN = 2 : A warning, which it does NOT cause crashing the process.
-- ERROR = 3 : A handleable error condition.
-- FATAL = 4 : An un-handleable error that results in a program crash.
-- UNKNOWN = 5 : An unknown message that should always be logged.
+- TRACE = 0 : all information that helps us to trace the processing of an incoming request through our application.
+- DEBUG = 1  : Low-level information, mostly for developers.
+- INFO = 2 : Generic (useful) information about system operation.
+- WARN = 3 : A warning, which it does NOT cause crashing the process.
+- ERROR = 4 : A handleable error condition.
+- FATAL = 5 : An un-handleable error that results in a program crash.
+- UNKNOWN = 6 : An unknown message that should always be logged.
     
 ### Time for coding
 - create log manager instance:
@@ -86,41 +87,76 @@ To use log manager APIs, first step is to have a quick review on Log Data Struct
   {
     "default_manager": "develop",
     "log_managers":
-      [
-        {
-          "manager_name": "develop",
-          "enable": true,
-          "app_name": "TestApp",
-          "severity_level": "debug",
-          "buffer_size": 100,
-          "flush_wait_seconds": 15,
-          "repositories":
-                  [
-                    {
-                      "enable": true,
-                      "type": "console",
-                      "formatter": "delimited_text",
-                      "delimiter": "|"
-                    },
-                    {
-                      "enable": true,
-                      "type": "File",
-                      "file_path": "./log/log.txt",
-                      "roll_period": "daily",
-                      "roll_size": "1048576",
-                      "formatter": "delimited_text",
-                      "delimiter": "|"
-                    },
-                    {
-                      "enable": true,
-                      "type": "fluentd",
-                      "host": "localhost",
-                      "port": "8888",
-                      "formatter": "json"
-                    }
-                  ]
-        }
-      ]
+    [
+      {
+        "title": "develop",
+        "enable": true,
+        "app_name": "TestApp",
+        "severity_level": "trace",
+        "buffer_size": 100,
+        "flush_wait_seconds": 10,
+        "repositories":
+        [
+          {
+            "type": "console",
+            "title": "console_repo_1",
+            "enable": true,
+            "formatter":
+            {
+              "type": "text",
+              "delimiter": "|"
+            },
+            "filters":
+            [
+              {
+                "type": "topic",
+                "title": "topic_filter_1",
+                "enable": true,
+                "default_regex" : "^test$"
+              },
+              {
+                "type": "message",
+                "title": "message_filter_1",
+                "enable": false,
+                "default_regex" : "error"
+              }
+            ]
+          },
+          {
+            "type": "file",
+            "title": "file_repo_1",
+            "enable": true,
+            "file_path": "log.txt",
+            "roll_period": "daily",
+            "roll_size": "1048576",
+            "formatter":
+            {
+              "type": "json",
+              "delimiter": "|"
+            }
+          },
+          {
+            "enable": false,
+            "title": "fluentd_repo_1",
+            "type": "fluentd",
+            "host": "localhost",
+            "port": "8888",
+            "formatter":
+            {
+              "type": "json"
+            }
+          }
+        ],
+        "topics":
+        [
+          {
+            "title": "test",
+            "enable": true,
+            "severity_level": "WARN"
+          }
+        ]
+      }
+    ]
   }
 }
 ``` 
@@ -136,21 +172,25 @@ To use log manager APIs, first step is to have a quick review on Log Data Struct
     # Assume user 'Tom' is trying to authenticate we will use user_name as log Context_id
     user_name = 'Tom'
     topic = log_manager.add_topic('Authentication')
+    topic.trace(user_name, 'Authentication process began for:', user_name)
     topic.debug(user_name, 'use_id is nil for user:', user_name)
     topic.info(user_name, 'User ', user_name , ' is trying to login.')
     topic.warning(user_name, 'Authentication failed for user ', user_name)
     topic.error(user_name, 'Error connecting to data base for user ', user_name)
     topic.fatal(user_name, 'Authentication service has been stopped working')
     topic.unknown(user_name, 'An unknown error occured during authentication. user name:', user_name)
+    topic.trace(user_name, 'Authentication process end for:', user_name)
 ```
 the result will be:
 ```
+    {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"TRACE","message"Authentication process began for: Tom"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"DEBUG","message":"user_id is nil for user: Tom"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"INFO","message":"User Tom is trying to login"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"WARN","message":"Authentication failed for user Tom"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"ERROR","message":"Error connecting to data base for user Tom"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"FATAL","message":"Authentication service has been stopped working"}
     {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"UNKNOWN","message":"An unknown error occured during authentication. user name: Tom"}
+    {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":"TRACE","message"Authentication process end for: Tom"}
 ```
 - json config file sample
 ```json
@@ -161,37 +201,55 @@ the result will be:
     "log_managers":
     [
       {
-        "manager_name": "develop",
+        "title": "develop",
         "enable": true,
         "app_name": "TestApp",
-        "severity_level": "debug",
+        "severity_level": "trace",
         "buffer_size": 100,
-        "flush_wait_seconds": 15,
+        "flush_wait_seconds": 10,
         "repositories":
         [
           {
-            "enable": true,
             "type": "console",
+            "title": "console_repo_1",
+            "enable": true,
             "formatter":
             {
               "type": "text",
               "delimiter": "|"
-            }
+            },
+            "filters":
+            [
+              {
+                "type": "topic",
+                "title": "topic_filter_1",
+                "enable": true,
+                "default_regex" : "^test$"
+              },
+              {
+                "type": "message",
+                "title": "message_filter_1",
+                "enable": false,
+                "default_regex" : "error"
+              }
+            ]
           },
           {
-            "enable": false,
             "type": "file",
+            "title": "file_repo_1",
+            "enable": true,
             "file_path": "log.txt",
             "roll_period": "daily",
             "roll_size": "1048576",
             "formatter":
             {
-              "type": "text",
+              "type": "json",
               "delimiter": "|"
             }
           },
           {
             "enable": false,
+            "title": "fluentd_repo_1",
             "type": "fluentd",
             "host": "localhost",
             "port": "8888",
@@ -206,7 +264,7 @@ the result will be:
           {
             "title": "test",
             "enable": true,
-            "severity_level": "info"
+            "severity_level": "WARN"
           }
         ]
       }
@@ -214,7 +272,7 @@ the result will be:
   }
 }
 ```
-- json config file structure 
+### json config file structure 
 ```comment
   As we described you cap apply RTA log manager using a json config file.
   
@@ -226,7 +284,7 @@ the result will be:
       multiple log manager configuration in Log_Managers array.
     - log_managers : the array of LogManagers with different configuration.
       It is possible to define multiple log manager configurations for differen usages.
-      - manager_name: the name of log manager. It will be used to define the default log manager.
+      - title: the name of log manager. It will be used to define the default log manager.
       - enable: (true/false) The value of this property activate or deactivate entire log manager.
       - app_name: Application name as the owner of log data.
       - severity_level: Defines which level of log data will be stored in log repositories.
@@ -274,13 +332,29 @@ the result will be:
                 - "type": ["text"/"json"] type of formatter
                 - "delimiter": [any text delimiter you need.(as an instance pipe line "|")]
                 if formatter not defined then the json formatter will be used
+          New Features: 
+             * In RTALogger version 2.1.0 and above defineing filters is possible for each repository.
+             * Repositories filtes could restrict the amount of data stored by specific repository.
+             * Also you can add new repositories and filters at run time.
+             * filters configuration: It's possible to apply multiple filters on a repository. When repository will 
+               flush a log_record only if the record pass all filter conditions.
+             * There are variaty of filter types, including:
+               'topic' which apply a regular expresion on log_record.topic_title to pass filtering condition.
+               'context' which apply a regular expresion on log_record.context_id to pass filtering condition.
+               'message' which apply a regular expression on log_record.full_message to pass filtering condition.
+             * Each filter has following attributes to counfigure:
+               "type": ["topic"/"context"/"message" or any customized filter] described in previous lines.
+               "title": "filte_title" a unique title to make filter run time configuration
+               "enable": [true/false] this will enable or disable filtering opration of current filter.
+               "default_regex": "valid regual expression" to compare with corresponding attribute.
+             * It's possible to implement customize filter classes and integerate with RTALogger filter factory. 
         - topics: This is an optional item. When you need to customize a specific topic severity level or
                   enable value, you can define the settings here.
           - title: The topic title to customize. (mandatoy).
           - severity_level: Defines which level of log data will be stored in log repositories.
           - enable: [true/false] to enable or disable logging process of the topic.
 ```
-- Some useful features
+##Some useful features
 ```ruby
     # change log manager app name at run time
     log_manager.app_name = 'myTestApp'
@@ -296,10 +370,36 @@ the result will be:
 
     # enable or disable all topic if necessary
     log_manager.update_all_topics_enable([true/false])
+
+    # to get log manager configuration as json object use to_builder method
+    log_manager.to_builder
+    
+    # to get log manager configuration as json string use reveal_config method
+    log_manager.reveal_config
+    
+    # to apply some limited changes on log manager functionality at run time
+    # config_json parameter should carry a json object which contains the configuration
+    # structure described before in 'json configuration file structure' section.
+    # Attention: these changes will apply to manager but will not save. 
+    # So during next load these changes will be lost. Save changes will be available in
+    # next version.
+    # Attention: only following attributes could be change at run time:
+    # log_manager.enable
+    # log_manager.default_severity_level    
+    # log_manager.buffer_size (minimum is 100)
+    # log_manager.flush_wait_time (minimum 15 second)
+    # repository.enable
+    # topic.enable
+    # topic.severity_level
+    # Other attributes could only change via config file via manager config_use_json_file 
+    # In RTALogger version 2.1.0 and above, it is possible to add new repositories or repository filters at run time
+    # using log_manager.apply_run_time_config method. 
+    log_manager.apply_run_time_config(config_json) 
 ```
-- Implement and Expand
+### Implement and Expand
+#### Implement new customized log repository
   It is possible to implement new log repositories. There will be fue rules to implement and
-  integrate new customized log repository with RTALogger LogManager.
+  integrate new customized log repository with RTALogger LogManager factory.
   
   1- Define you class inside RTALogger module.
   
@@ -307,7 +407,7 @@ the result will be:
   
   3- Also appropriate naming convention is necessary. 
      As an example if you are implementing a Console Repo, your class name should be LogRepositoryConsole and 
-     your source code in a ruby file and name it log_repository_console.rb
+     your source code should be placed in a ruby file and name it log_repository_console.rb
   
   4- After implementing your own log repository, you should register the class at run-time using the following syntax:
   ```ruby
@@ -344,17 +444,95 @@ module RTALogger
 end
 ```
 
-## Development
+#### Implement new customized log repository filter
+  It is possible to implement new log repository filter. There will be fue rules to implement and
+  integrate new customized log repository filter with RTALogger LogManager factory.
+  
+  1- Define you class inside RTALogger module.
+  
+  2- The class should be inherited from 'RTALogger::LogFilterBase'.
+  
+  3- Also appropriate naming convention is necessary. 
+     As an example if you are implementing a Console Repo, your class name should be LogFilterTopic and 
+     your source code should be placed in a ruby file and name it log_filter_topic.rb
+  
+  4- After implementing your own log filter, you should register the class at run-time using the following syntax:
+  ```ruby
+  RTALogger::LogFactory.register_log_filter :topic, 'log_filter_topic.rb'
+  ```
+  Another example: LogFilterMyCustomizedFilter
 
-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.
+  ```ruby
+  RTALogger::LogFactory.register_log_filter :my_customized_filter, 'log_repository_my_customized_filter.rb'
+  ```
+  Here is 'LogRepositoryTopic' implementation:
+  ```ruby
+require_relative 'log_filter_base'
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+module RTALogger
+  class LogFilterTopic < LogFilterBase
+    def match_conditions(log_record)
+      return true if !@enable
+      result = super
+      return result unless result
 
+      return default_regex.present? ? (Regexp.new(@default_regex).match(log_record.topic_title)) : result
+    end
+  end
+end
+```
+#### Implement new customized log formatter
+
+  It is possible to implement new log formatter. There will be fue rules to implement and
+  integrate new customized log formatter with RTALogger LogManager factory.
+  
+  1- Define you class inside RTALogger module.
+  
+  2- The class should be inherited from 'RTALogger::LogFormatter'.
+  
+  3- Also appropriate naming convention is necessary. 
+     As an example if you are implementing a Text formatter, your class name should be LogFormatterText and 
+     your source code should be placed in a ruby file and name it log_formatter_text.rb
+  
+  4- After implementing your own log formatter, you should register the class at run-time using the following syntax:
+  ```ruby
+  RTALogger::LogFactory.register_log_formatter :text, 'log_formatter_text.rb'
+  ```
+  Another example: LogFormatterMyCustomizedFormatter
+
+  ```ruby
+  RTALogger::LogFactory.register_log_formatter :my_customized_formatter, 'log_formatter_my_customized_formatter.rb'
+  ```
+  Here is 'LogFormatterText' implementation:
+  ```ruby
+require_relative 'log_formatter_base'
+require_relative 'severity_level'
+
+module RTALogger
+  # text formatter which receive log_record and
+  # returns it's data as delimited text string
+  class LogFormatterText < LogFormatterBase
+    include SeverityLevel
+
+    def format(log_record)
+      return '' unless log_record
+
+      result = log_record.occurred_at.strftime('%F %H:%M:%S:%3N')
+      result << @delimiter << log_record.app_name
+      result << @delimiter << log_record.topic_title
+      result << @delimiter << log_record.context_id.to_s
+      result << @delimiter << parse_severity_level_to_s(log_record.severity)
+      result << @delimiter << log_record.message.join(' ').gsub(delimiter, '$<$')
+
+      result
+    end
+  end
+end
+```
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/BBahrainy/RTALogger.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/RTALogger/version.rb

@@ -1,3 +1,3 @@
 module RTALogger
-  VERSION = '1.1.1'.freeze
+  VERSION = '2.1.1'.freeze
 end

data/lib/log_factory_filter.rb

@@ -0,0 +1,33 @@
+require_relative 'log_filter_base'
+
+module RTALogger
+  # Log factory to get new instance of log filter
+  module LogFactory
+    def self.create_filter(type, config_json = '')
+      lib_file = @log_filters[type.to_sym]
+      raise "unregistered filter class: #{type.to_s}" if lib_file.nil? || lib_file.empty?
+      begin
+        load lib_file
+      rescue
+        raise "unable to load formatter class file: #{lib_file}"
+      end
+
+      filter_class_name = 'RTALogger::' + ('log_filter_' + type.to_s).split('_').map(&:capitalize).join
+      filter_class = Object.const_get(filter_class_name)
+      return nil unless filter_class
+      result = filter_class.new
+
+      return result if config_json.empty?
+      result.load_config(config_json) if result.present?
+      return result
+    end
+
+    def self.register_log_filter(type, class_file_name)
+      @log_filters[type.to_sym] = class_file_name
+    end
+
+    @log_filters = {:topic => 'log_filter_topic.rb',
+                    :context => 'log_filter_context.rb',
+                    :message => 'log_filter_message.rb'}
+  end
+end