RTALogger 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8102f5e6bfb81e09e529d98b34039304aa7376d553e0df71e974a2eeaf6818d
-  data.tar.gz: 7a6558fa4df04b8bbaede48620644b7b85de448d96b7e93340d30f018a872461
+  metadata.gz: d4c558e31bfbc739d0ad9ebb218c96c61fdcc354b6ae9a9c0daa3ea4743786c3
+  data.tar.gz: b00ec909d9a8791671e29e949fb19cfb31e59d7fbf353532a70bfb216e6b4e45
 SHA512:
-  metadata.gz: 590a74703f4605c4a0df2e3a5a1997bf1c0209182b961ef74769f4c037f7fefb8770240d317e6017d3cf9ae30f1fc1cbd4e489c6e5c7f083b36f04b6d6f64bc6
-  data.tar.gz: 1dd9d109f63173420be1bbb6306d76eda10140c4474aa8b4de27f46ef7dbadceec58d5ba8816b03fa53de2cb6ee6b793ae3726ade97728aa3de55ec592e30255
+  metadata.gz: c6296831235e737111217cf51f4e3d477620d588319fb0540760b948028b26f87361e03cc7c453dd00ab3c4553a26ad045791e2d9e64d1153017246e664348bd
+  data.tar.gz: 39885f5f4f039199748d9201f632ac4e745bd41cced49971ddc70b9599281c556a2d85e3fb13332a76cb0b01d78f1efb88d510331071332ccfdcbd26528543a7

data/.idea/.gitignore

@@ -0,0 +1,2 @@
+# Default ignored files
+/workspace.xml

data/.idea/.rakeTasks

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Settings><!--This file was automatically generated by Ruby plugin.
+You are allowed to: 
+1. Remove rake task
+2. Add existing rake tasks
+To add existing rake tasks automatically delete this file and reload the project.
+--><RakeGroup description="" fullCmd="" taksId="rake"><RakeTask description="Build RTALogger-0.1.0.gem into the pkg directory" fullCmd="build" taksId="build" /><RakeTask description="Remove any temporary products" fullCmd="clean" taksId="clean" /><RakeTask description="Remove any generated files" fullCmd="clobber" taksId="clobber" /><RakeTask description="Build and install RTALogger-0.1.0.gem into system gems" fullCmd="install" taksId="install" /><RakeGroup description="" fullCmd="" taksId="install"><RakeTask description="Build and install RTALogger-0.1.0.gem into system gems without network access" fullCmd="install:local" taksId="local" /></RakeGroup><RakeTask description="Create tag v0.1.0 and build and push RTALogger-0.1.0.gem to https://www.rubygems.org" fullCmd="release[remote]" taksId="release[remote]" /><RakeTask description="Run RSpec code examples" fullCmd="spec" taksId="spec" /></RakeGroup></Settings>

data/.idea/RTALogger.iml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <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="diff-lcs (v1.4.4, 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" />
+    <orderEntry type="library" scope="PROVIDED" name="msgpack (v1.3.3, ruby-2.6.3-p62) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rake (v12.3.3, ruby-2.6.3-p62) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.10.0, ruby-2.6.3-p62) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.10.0, ruby-2.6.3-p62) [gem]" level="application" />
+    <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="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="zeitwerk (v2.4.1, ruby-2.6.3-p62) [gem]" level="application" />
+  </component>
+</module>

data/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptSettings">
+    <option name="languageLevel" value="ES6" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="ruby-2.6.3-p62" project-jdk-type="RUBY_SDK" />
+</project>

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/RTALogger.iml" filepath="$PROJECT_DIR$/.idea/RTALogger.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

data/Gemfile

@@ -5,3 +5,4 @@ gemspec
 
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
+gem "jbuilder"

data/Gemfile.lock

@@ -1,26 +1,28 @@
 PATH
   remote: .
   specs:
-    RTALogger (0.1.0)
-      fluentd (~> 1.11, >= 1.11.4)
+    RTALogger (1.0.0)
+      fluent-logger (~> 0.9)
+      jbuilder (~> 2.10)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (6.0.3.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      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)
+      activesupport (>= 5.0.0)
+    minitest (5.14.2)
     msgpack (1.3.3)
     rake (12.3.3)
     rspec (3.10.0)
@@ -36,21 +38,17 @@ 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)
-    tzinfo (2.0.2)
-      concurrent-ruby (~> 1.0)
-    tzinfo-data (1.2020.4)
-      tzinfo (>= 1.0.0)
-    yajl-ruby (1.4.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   RTALogger!
+  jbuilder
   rake (~> 12.0)
   rspec (~> 3.0)
 

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,9 +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.
+
+### 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'
+
+    # 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'
+
+    # update specific topic log level if necessary
+    log_manager.update_topic_severity_level(topic_title, RTALogger::SeverityLevel::INFO)
+
+    # update all topics severity level if necessary
+    log_manager.update_all_topics_severity_level(RTALogger::SeverityLevel::INFO)
+
+    # enable or disable specific topic if necessary
+    log_manager.update_topic_enable(topic_title, [true/false])
+
+    # 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'
+
+module RTALogger
+  # show log items on console out put
+  class LogRepositoryConsole < LogRepository
+    def initialize
+      super
 
-TODO: Write usage instructions here
+      @formatter = RTALogger::LogFactory.log_formatter_default
+    end
+
+    protected
+
+    def flush_and_clear
+      semaphore.synchronize do
+        @log_records.each { |log_record| puts @formatter.format(log_record) }
+      end
+      super
+    end
+  end
+end
+```
 
 ## Development
 
@@ -32,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