RTALogger 0.1.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cd821ed8beebbda5bfd6aff1088372642f5f20012c7f5d6ca8b2d59cc8dee42
-  data.tar.gz: 8dbf6b01f03b98525acade15eaebece1e500dfbc610f2d9cbda5e760df0e048b
+  metadata.gz: c27d68d46d9d0ff75577b50a1b29983ce9012bc1d3dc86778b197154596ab2c5
+  data.tar.gz: 53ebb2215c5a2e4733de28b9178c9d4db5713aa87483309407be0de1763b36f1
 SHA512:
-  metadata.gz: 7a1e77c33e3fb301780bb6d4a0b254701ab918403ee8705e19bda759b2c0ce56b1e1cf76c18012c195b5c3b28267dea524bbe3db303f7a9fb9dca58662fe9a2f
-  data.tar.gz: fd81ab07bb1a3c79e00e425298068e4cfa357208e4173f157a156e5cdefcb044f456604cfc0c3b9d0f37342e672d47636ffd75ceb4b5ef866a47f8f7db9bc7aa
+  metadata.gz: e731b3cd50b9c13b017679a34e9136b743055e50892017a73890d5f74031f6d88fc437b8a26dee5abe8207fcc9c1616c83ab998f77ee216701c2fd0d98220cc2
+  data.tar.gz: 871fd3047f195f7076e08eeec631bc3f0143ea4c4f8ae483bf054e244e5e6f75541f775f0b4f973e8127a592cace225922357fb7f9167f00623f3845bd0573b7

data/.idea/RTALogger.iml

@@ -10,10 +10,8 @@
     <orderEntry type="library" scope="PROVIDED" name="activesupport (v6.0.3.4, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="bundler (v2.1.4, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="concurrent-ruby (v1.1.7, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="cool.io (v1.7.0, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.4.4, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="fluentd (v1.11.4, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="http_parser.rb (v0.6.0, ruby-2.6.3-p62) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="fluent-logger (v0.9.0, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="i18n (v1.8.5, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="jbuilder (v2.10.1, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="minitest (v5.14.2, ruby-2.6.3-p62) [gem]" level="application" />
@@ -24,13 +22,8 @@
     <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.10.0, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.10.0, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.10.0, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="serverengine (v2.2.2, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="sigdump (v0.2.4, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="strptime (v0.2.5, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="thread_safe (v0.3.6, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="tzinfo (v1.2.7, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="tzinfo-data (v1.2020.4, ruby-2.6.3-p62) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="yajl-ruby (v1.4.1, ruby-2.6.3-p62) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="zeitwerk (v2.4.1, ruby-2.6.3-p62) [gem]" level="application" />
   </component>
 </module>

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    RTALogger (0.1.1)
-      fluentd (~> 1.11, >= 1.11.4)
+    RTALogger (1.1.0)
+      fluent-logger (~> 0.9)
       jbuilder (~> 2.10)
 
 GEM
@@ -15,19 +15,9 @@ GEM
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
     concurrent-ruby (1.1.7)
-    cool.io (1.7.0)
     diff-lcs (1.4.4)
-    fluentd (1.11.4)
-      cool.io (>= 1.4.5, < 2.0.0)
-      http_parser.rb (>= 0.5.1, < 0.7.0)
-      msgpack (>= 1.3.1, < 2.0.0)
-      serverengine (>= 2.0.4, < 3.0.0)
-      sigdump (~> 0.2.2)
-      strptime (>= 0.2.2, < 1.0.0)
-      tzinfo (>= 1.0, < 3.0)
-      tzinfo-data (~> 1.0)
-      yajl-ruby (~> 1.0)
-    http_parser.rb (0.6.0)
+    fluent-logger (0.9.0)
+      msgpack (>= 1.0.0, < 2)
     i18n (1.8.5)
       concurrent-ruby (~> 1.0)
     jbuilder (2.10.1)
@@ -48,16 +38,9 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.0)
-    serverengine (2.2.2)
-      sigdump (~> 0.2.2)
-    sigdump (0.2.4)
-    strptime (0.2.5)
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    tzinfo-data (1.2020.4)
-      tzinfo (>= 1.0.0)
-    yajl-ruby (1.4.1)
     zeitwerk (2.4.1)
 
 PLATFORMS

data/README.md

@@ -1,8 +1,32 @@
 # RTALogger
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/RTALogger`. To experiment with that code, run `bin/console` for an interactive prompt.
+RTA Log Manager has been designed and implemented to provide standard logging API for developers.
+This prevents chaos in log data format. 
+Also provide multiple extendable log repositories including wrapping existing loggers, like 'Fluentd' or implement completely new custom logger. 
+All log manager's main features are configable through a json config file.
 
-TODO: Delete this and the text above, and describe your gem
+Main purposes of developing this gem are:
+- Creating standard logging API to seperate application from existing variety of loggers.
+- Wrapping around existing loggers so get advantage of different loggers at the same time.
+- Make it possible to easily replace a logger component with a new one. (for example Rails standard Logger with Fluentd)
+  without any changes in the consumer application. 
+- Creating easy to use logger interface.
+- Apply some rules and restrictions about log structure and data format, which prevents chaos in application log information.
+- No interrupt or wait time for log consumer modules.
+- Utilize multiple log repositories at the same time in background (Console, File, UDP, FluentD, etc.) 
+- Make it possible to implement customized log repositories.
+
+Main Features:
+- Creating multiple log manager instances with different configuration is possible entire application.
+- Each log manager instance could be configured via a json file.
+- Each log manager instance could be config to use multiple log repositories such as Console, File, UDP, Fluentd.
+- Runtime configurations could be applied through log manager APIs.
+- By using multi threading techniques and also buffering techniques, 
+  all logging process will handled in seperated thread.
+  So the log consumer modules should not be wait for log manager to finish the logging task.
+- Multiple standard log severity levels are available through topic APIs (debug, info, warning, error, fatal, unknown)
+- Main features could be set and manipulate through json configuration file.
+- And at the end, it is easy to use for ruby backend developers. 
 
 ## Installation
 
@@ -20,45 +44,307 @@ Or install it yourself as:
 
     $ gem install RTALogger
 
+To add gem to your rails application:
+   
+     $ bundle add RTALogger
+     
 ## Usage
+#### RTA Log Data Structure
+To use log manager APIs, first step is to have a quick review on Log Data Structure
+- Application: The root of each log data record is Application, which specify the log data owner application.
+- Topic: By adding multiple topics to log manager you can categorize log data in logical topics.
+- Context: Under each topic, one or multiple contexts (in one level) could be defined. 
+- As an instance the Application could by 'MyEShopApp', one of Topics could be 'Authentication' and 
+  Contexts could be 'uer_name' which attend in application authorization process.
+- The next step is log severity level, which determines that the log record severity (debug, information, warning, error, fatal, unknown)
+- At last the final element is log message, which contains log message data.
 
-require_relative 'log_factory_manager'
-require_relative 'log_factory_repository'
+### 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.
+    
+### Time for coding
+- create log manager instance:
+```ruby
+    # add required files
+    require 'log_factory_manager'
 
-controller_name = 'test_controller'
-userID = 5
+    # create log manager instance using LogFactory
+    log_manager = RTALogger::LogFactory.log_manager_instance
+```
+- Apply configuration using json config file
+```ruby
+    # the parameter is the json config file
+    log_manager.config_use_json_file('rta_logger_config.json')
+```
+- Sample configuration json file
+```
+{
+  "rta_logger":
+  {
+    "default_manager": "develop",
+    "log_managers":
+      [
+        {
+          "manager_name": "develop",
+          "enable": true,
+          "app_name": "TestApp",
+          "severity_level": "debug",
+          "buffer_size": 100,
+          "flush_wait_seconds": 15,
+          "repos":
+                  [
+                    {
+                      "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"
+                    }
+                  ]
+        }
+      ]
+  }
+}
+``` 
+- Add new topic to log manager and get the topic instance
+```ruby
+    # the parameter is the topic name
+    # if add_topic API called multiple times with same parameter,
+    # only one instance will be created for that topic 
+    topic = log_manager.add_topic('Authentication')
+```
+- Finally add log message using topic instance
+```ruby
+    # 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.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)
+```
+the result will be:
+```
+    {"occurred_at":"2020-11-04 15:56:58:785","app_name":"TestApp","topic_title":"Authentication","context_id":"Tom","severity":0,"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":1,"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":2,"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":3,"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":4,"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":5,"message":"An unknown error occured during authentication. user name: Tom"}
+```
+- json config file sample
+```json
+{
+  "rta_logger":
+  {
+    "default_manager": "develop",
+    "log_managers":
+    [
+      {
+        "manager_name": "develop",
+        "enable": true,
+        "app_name": "TestApp",
+        "severity_level": "debug",
+        "buffer_size": 100,
+        "flush_wait_seconds": 15,
+        "repos":
+        [
+          {
+            "enable": true,
+            "type": "console",
+            "formatter":
+            {
+              "type": "text",
+              "delimiter": "|"
+            }
+          },
+          {
+            "enable": false,
+            "type": "file",
+            "file_path": "log.txt",
+            "roll_period": "daily",
+            "roll_size": "1048576",
+            "formatter":
+            {
+              "type": "text",
+              "delimiter": "|"
+            }
+          },
+          {
+            "enable": false,
+            "type": "fluentd",
+            "host": "localhost",
+            "port": "8888",
+            "formatter":
+            {
+              "type": "json"
+            }
+          }
+        ],
+        "topics":
+        [
+          {
+            "title": "test",
+            "enable": true,
+            "severity_level": "info"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+- json config file structure 
+```comment
+  As we described you cap apply RTA log manager using a json config file.
+  
+  log_manager.config_use_json_file('rta_logger_config.json')
+     
+  The file structure:
+  - rta_logger : the root element of rta_logger json configuration.
+    - default_manager: the name of default log manager config, when there is 
+      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.
+      - 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.
+      - buffer_size: The memory buffer size (number of buffered log objects) to 
+        decread api consumers wait time. when the buffer is full the flush operation will
+        save buffered logs to log repositoies.
+      - flush_wait_seconds: Time in soconds which log managers wait to flush buffered log objects
+        to log repository.
+      - repos: Array of log repositories. It is possible to define multiple log repositories to
+        store log data. there are variaty of log repositories and it is possible to
+        add new ones. Each item in Repos array will configure a log repository.
+        Pre-defined types are described below, also it's possible to implement your custome repo type 
+        and register it to RTALogger.
+        - Log repository types and config:
+          1- console: Show log data in text format on standard out put
+             - "type": "console"
+             - "enable": [true/false] this will activate or deactivate log repository.
+             - "foramtter" is the text, json or any custome defined types as LogRecord formatter
+                - "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
+          2- file: Store log data in a file.
+             - "type": "console"
+             - "enable": [true/false] this will activate or deactivate log repository.
+             - "file_path": [file path and file name] the path and the name to store log data.
+             - "roll_period": ["daily"/"weekly"/"monthly"] the period to generate new log file.
+             - "roll_size": [bytes]  the maximum size of log file to 
+                roll file and create the new log file
+             - "foramtter" is the text, json or any custome defined types as LogRecord formatter
+                - "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
+          3- udp: Send log data over UDP on network. 
+             - "type": "udp"
+             - "enable": [true/false] this will activate or deactivate log repository.
+             - "host": IP of the server to send log data.
+             - "port": Port of server to send log data.
+          4- fluentd: send log data to Fluentd Log collector over network using TCP/IP protocol.
+             - "type": "fluentd"
+             - "enable": [true/false] this will activate or deactivate log repository.
+             - "host": IP of the server to send log data.
+             - "port": Port of server to send log data.
+             - "tls_options": TLS configuration to stablish a secure TCP connection to Fluentd Server.
+             - "foramtter" is the text, json or any custome defined types as LogRecord formatter
+                - "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
+        - 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
+```ruby
+    # change log manager app name at run time
+    log_manager.app_name = 'myTestApp'
 
-# create log manager instance
-# this could be a global variable declared in application level
-log_manager = RTALogger::LogFactory.log_manager_instance
+    # update specific topic log level if necessary
+    log_manager.update_topic_severity_level(topic_title, RTALogger::SeverityLevel::INFO)
 
-# set log manage application name (hard code)
-log_manager.app_name = 'myTestApp'
+    # update all topics severity level if necessary
+    log_manager.update_all_topics_severity_level(RTALogger::SeverityLevel::INFO)
 
-# load log manager configuration from a json config file
-log_manager.config_use_json_file('rta_logger_config.json')
+    # enable or disable specific topic if necessary
+    log_manager.update_topic_enable(topic_title, [true/false])
 
-# add log repository to log manager
-#log_manager.propagator.add_log_repository(RTALogger::LogFactory.new_log_repository_console)
+    # enable or disable all topic if necessary
+    log_manager.update_all_topics_enable([true/false])
+```
+- Implement and Expand
+  It is possible to implement new log repositories. There will be fue rules to implement and
+  integrate new customized log repository with RTALogger LogManager.
+  
+  1- Define you class inside RTALogger module.
+  
+  2- The class should be inherited from 'RTALogger::LogRepository'.
+  
+  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
+  
+  4- After implementing your own log repository, you should register the class at run-time using the following syntax:
+  ```ruby
+  RTALogger::LogFactory.register_log_repository :console, 'log_repository_console.rb'
+  ```
+  Another example: LogRepositoryMyCustomizedUdp
+
+  ```ruby
+  RTALogger::LogFactory.register_log_repository :my_customized_udp, 'log_repository_my_customized_udp.rb'
+  ```
+  Here is 'LogRepositoryConsole' implementation:
+```ruby
+require_relative 'log_repository'
+require_relative 'log_factory_log_formatter'
 
-# add new topic to log manager
-# use this api to get a new log topic instance
-# this api could be called in entry point of each service or class initialize method
-topic = log_manager.add_topic(controller_name)
+module RTALogger
+  # show log items on console out put
+  class LogRepositoryConsole < LogRepository
+    def initialize
+      super
 
-# add log information to log topic
-topic.debug(userID, 'Controller Name=', controller_name, 'debug')
-topic.info(userID, 'Controller Name=', controller_name, 'information')
-topic.warning(userID, 'Controller Name=', controller_name, 'warning')
-topic.error(userID, 'Controller Name=', controller_name, 'error')
-topic.fatal(userID, 'Controller Name=', controller_name, 'fatal')
-topic.unknown(userID, 'Controller Name=', controller_name, 'unknown')
+      @formatter = RTALogger::LogFactory.log_formatter_default
+    end
 
-# update specific topic log level if necessary
-# log_manager.update_topic_level(controller_name, RTALogger::LogSeverity::INFO)
+    protected
 
-# update all topics log level if necessary
-# log_manager.update_all_topics_log_level(RTALogger::LogSeverity::INFO)
+    def flush_and_clear
+      semaphore.synchronize do
+        @log_records.each { |log_record| puts @formatter.format(log_record) }
+      end
+      super
+    end
+  end
+end
+```
 
 ## Development
 
@@ -68,7 +354,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/RTALogger.
+Bug reports and pull requests are welcome on GitHub at https://github.com/BBahrainy/RTALogger.
 
 
 ## License