event_logger_rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f372aa5098db4fbac8a61ffb11d350226a5b0df839e38f1b75907e35407e1a73
-  data.tar.gz: 91960c8aee0f2adb82ad167c51b62207111dca9a7cbf5ec44750d3e585e0a430
+  metadata.gz: 95ba9a01dfc949b290f6142ac959cc206e705f5b286e2768381a82d6477f424d
+  data.tar.gz: aa992346f7623bb36cd0d12fd83aed155a92a8645c0cfbe8b47ec8c7d22fcc3e
 SHA512:
-  metadata.gz: e08ed66560764cf5fc761b3a74fcbee08d435f132c4e154053f3e9628c8de9b9c5806e9c4c0edbc8f76369dccffe0ea50898311bc5463a1579e947768daa0747
-  data.tar.gz: 72e6f058450d7462e6c86f80789492cfc737b6b0d6fac2e376a30c172005f378b8220490201bcbc02ab76ccb690e0aa269a5d0451fc89f145df3e983a184d687
+  metadata.gz: 7783f0fae629d0bf417b922a5b93257f22946b7b6b5f5304420341cf9e55f3a6471071fcd3bb36f1b00ed3862f181b6f222306f4975239c1353d24b57a3c94f8
+  data.tar.gz: 6abc431c12d4395ae0b119fb62b26731a8509d22f4b98ac3eeb868a8de27a8255b6ff6b81fc83a8ebb4764643eda90d946a36cf3c1ba81db63b34cf1c26d6e8b

data/README.md

@@ -1,28 +1,88 @@
 # EventLoggerRails
-Short description and motivation.
+
+Rails gem that facilitates logging events for analysis.
 
 ## Usage
-How to use my plugin.
+
+You can define a registry of events that your application emits via the config file (`config/event_logger_rails.yml`).
+The events that you define are placed in the `registered_events` structure in the config file.
+
+For example, to register a user signup event, first define the event as a registered event:
+
+```yaml
+registered_events:
+  user:
+    signup:
+      success: 'Indicates a user signup was successful.'
+      failure: 'Indicates a user signup was not successful.'
+```
+
+Then, from the controller action that processes user signup's, include the `Loggable` concern and use the `log_event` method to log details about the event:
+
+```ruby
+class UsersController < ApplicationController
+  include Loggable
+
+  def create
+    user = User.new(user_params)
+    if user.save
+      log_event :info, 'user.signup.success'
+      redirect_to dashboard_path
+    else
+      log_event :error, 'user.signup.failure', errors: user.errors
+      render :new
+     end
+  end
+end
+```
+
+In this example, a possible successful signup could be structured like this:
+
+```
+[INFO | 2021-12-27T20:57:06+00:00 | user.signup.success] {"controller"=>"Users", "action"=>"create", "method"=>"POST", "path"=>"/users", "remote_ip"=>"::1", "parameters"=>"{ "user"=>{ "email"=>"validemail@example.com", "first_name"=>"Test", "last_name"=>"User" } }"}
+```
+
+...while a failed signup might look like this:
+
+```
+[ERROR | 2021-12-27T20:57:06+00:00 | user.signup.failure] {"controller"=>"Users", "action"=>"create", "method"=>"POST", "path"=>"/users", "remote_ip"=>"::1", "parameters"=>"{ "user"=>{ "first_name"=>"Test", "last_name"=>"User" } }", "errors"=>"{ "email"=>"is missing" }"}
+```
+
+The log entry indicates the logger level (useful for filtering results), the registered event, and more useful information from the controller and request.
+This makes it simple use a tool like `awk` or another monitoring solution to parse the logs for emitted events, facilitating troubleshooting and analytics.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "event_logger_rails"
+gem 'event_logger_rails'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install event_logger_rails
 ```
 
+Run the install generator to create a config file (`config/event_logger_rails.yml`):
+
+```bash
+$ bin/rails generate event_logger_rails:install
+```
+
+Add your events to the generated config file following the structure of the examples.
+
 ## Contributing
-Contribution directions go here.
+
+Contributions are welcome. Feel free to open a PR.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/concerns/event_logger_rails/loggable.rb

@@ -9,10 +9,10 @@ module EventLoggerRails
     def log_event(level, event, **data)
       data_to_log = data_from_request.merge(data)
       EventLoggerRails.log(level, event, **data_to_log)
-    rescue EventLogger::UnregisteredEvent => e
-      log_event :error, 'event-logger-rails.unregistered-event.failure', message: e.message
-    rescue EventLogger::InvalidLoggerLevel => e
-      log_event :error, 'event-logger-rails.logger-level.failure', message: e.message
+    rescue EventLoggerRails::Exceptions::UnregisteredEvent => e
+      log_event :error, 'event_logger_rails.event.unregistered', message: e.message
+    rescue EventLoggerRails::Exceptions::InvalidLoggerLevel => e
+      log_event :error, 'event_logger_rails.logger_level.invalid', message: e.message
     end
 
     def data_from_request

data/lib/event_logger_rails/event_logger.rb

@@ -9,6 +9,13 @@ module EventLoggerRails
   ##
   # Outputs event and related data logs.
   class EventLogger
+    DEFAULT_EVENTS = [
+      'event_logger_rails.logger_level.invalid',
+      'event_logger_rails.event.unregistered',
+      'event_logger_rails.event.testing'
+    ].freeze
+    private_constant :DEFAULT_EVENTS
+
     def initialize
       @logger_levels = logger_levels_from_config
       @registered_events = registered_events_from_config
@@ -37,11 +44,11 @@ module EventLoggerRails
     end
 
     def data_from_config
-      @data_from_config ||= YAML.safe_load(File.read(config_file)).deep_symbolize_keys
+      YAML.safe_load(File.read(config_file)).deep_symbolize_keys
     end
 
     def config_file
-      Rails.root.join('config/event_logger.yml')
+      Rails.root.join('config/event_logger_rails.yml')
     end
 
     def reload_config
@@ -67,11 +74,20 @@ module EventLoggerRails
     end
 
     def validate_event(event)
-      return true if registered_events.include?(event)
+      return true if event_registered?(event) || default_event?(event)
 
       raise EventLoggerRails::Exceptions::UnregisteredEvent.new(unregistered_event: event)
     end
 
+    def event_registered?(event)
+      parsed_event = event.split('.').map(&:to_sym)
+      registered_events.dig(*parsed_event)
+    end
+
+    def default_event?(event)
+      DEFAULT_EVENTS.include?(event)
+    end
+
     def output_device
       return $stdout unless Rails.env.test?
 

data/lib/event_logger_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EventLoggerRails
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/generators/event_logger_rails/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  module Generators
+    ##
+    # Creates basic config file for EventLoggerRails
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Create basic config file for EventLoggerRails'
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_config_file
+        copy_file 'event_logger_rails.yml', 'config/event_logger_rails.yml'
+      end
+    end
+  end
+end

data/lib/generators/event_logger_rails/templates/event_logger_rails.yml

@@ -0,0 +1,25 @@
+##
+# Allowed logger levels for use with EventLoggerRails
+# You can add/remove levels, if desired; however, an exception will occur
+# when using a logger level that is not enumerated here.
+#
+logger_levels:
+  - 'debug'
+  - 'info'
+  - 'warn'
+  - 'error'
+  - 'fatal'
+
+##
+# Registered events for use with EventLoggerRails
+# Add your custom event definitions to this section; attempting to log events
+# that are not registered here will result in an exception.
+#
+# Example event:
+#
+# registered_events:
+#   user:
+#     signup:
+#       success: 'Indicates a successful user signup.'
+#
+registered_events:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_logger_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dick Davis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-24 00:00:00.000000000 Z
+date: 2021-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,6 +41,8 @@ files:
 - lib/event_logger_rails/exceptions/invalid_logger_level.rb
 - lib/event_logger_rails/exceptions/unregistered_event.rb
 - lib/event_logger_rails/version.rb
+- lib/generators/event_logger_rails/install_generator.rb
+- lib/generators/event_logger_rails/templates/event_logger_rails.yml
 - lib/tasks/event_logger_rails_tasks.rake
 homepage: https://github.com/d3d1rty/event_logger_rails
 licenses: