event_logger_rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95ba9a01dfc949b290f6142ac959cc206e705f5b286e2768381a82d6477f424d
-  data.tar.gz: aa992346f7623bb36cd0d12fd83aed155a92a8645c0cfbe8b47ec8c7d22fcc3e
+  metadata.gz: 110cf01af709d86d2e848b9d11363ca58a0ab433eb444c05b9e9044d22ed35a3
+  data.tar.gz: 4b338f9e6f937e16195fc6f184bbad7e376409dcf44e545c50c3cec101b58123
 SHA512:
-  metadata.gz: 7783f0fae629d0bf417b922a5b93257f22946b7b6b5f5304420341cf9e55f3a6471071fcd3bb36f1b00ed3862f181b6f222306f4975239c1353d24b57a3c94f8
-  data.tar.gz: 6abc431c12d4395ae0b119fb62b26731a8509d22f4b98ac3eeb868a8de27a8255b6ff6b81fc83a8ebb4764643eda90d946a36cf3c1ba81db63b34cf1c26d6e8b
+  metadata.gz: 46be7cf18342e29d39b60f7cc4858858b5b880f16f049d65d89f69dccc0f0add12053be5020d6856a8db059f75f7f7b86f05e7733a55cadda3b3ed83dfe1e9c5
+  data.tar.gz: e69a33c9979e4bea40ec4ed0c723821c574586ab6a6ac29cea0f8e181fc0c545acf763b985d69b98899c5b2336262add45055479c3411673fc87ce20f760bc6f

data/README.md

@@ -1,55 +1,294 @@
-# EventLoggerRails
+## 🔌 EventLoggerRails 💾
 
-Rails gem that facilitates logging events for analysis.
+![Elara](elara.png?raw=true)
+*Elara, the mascot for `EventLoggerRails`*
+
+Are you tired of navigating through logs as if you're lost in the labyrinth of the Wired, searching for that elusive piece of data? Say "Hello, World!" to `EventLoggerRails`, the Rails engine transmuting your logs into enlightened gems of understanding. 💎
+
+### Visualize This
+
+In a single, centralized config file, decipher the events that pulse through the veins of your business. Once set, let `EventLoggerRails` weave them into intricate patterns of JSON logs that shimmer like a digital mirage. 🎇
+
+### Yet, The Nexus Expands
+
+Channel these JSON enigmas directly into analytic realms like OpenSearch. There, witness the alchemy of data taking form through real-time visualizations and analysis. 📊✨
+
+### Why Choose `EventLoggerRails`?
+
+- 🚀 **Fast Setup**: Get your logging up and running in minutes, not hours!
+- 🌐 **Team-Friendly Event Registry**: Simplify how your team defines and logs business-critical events.
+- 📚 **Readable**: Logs in a clean, JSON-formatted structure for easy parsing and analysis.
+- 🔍 **In-Depth Insight**: Elevate your business process analysis with granular, structured logging.
+
+Don't let crucial events get lost in the digital void. Make your app's logging as unforgettable as your first journey into the Wired with `EventLoggerRails`!
+
+### Huh?
+
+Ok, so Elara might be a little zealous about our project, and she seems to be stuck in a 90's anime. Don't let that dissuade you from using this engine, though.
+
+Our no-nonsense project description: **`EventLoggerRails` is a Rails engine for emitting structured events in logs during the execution of business processes for analysis and visualization.
+It allows teams to define events in a simple, centralized configuration file, and then log those events in JSON format for further processing.**
 
 ## Usage
 
-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.
+You can define a registry of events your application emits via the config file (`config/event_logger_rails.yml`).
+The events you define are placed in the config file under the corresponding environment. Most events belong in `shared`, though you may want to define different
+events or event characteristics per environment.
 
-For example, to register a user signup event, first define the event as a registered event:
+For example, to register a user signup event, first define the event as a registered event. You must include a `description` for the event, and you may
+optionally include a `level` to use for that specific event.
 
 ```yaml
-registered_events:
+shared:
   user:
     signup:
-      success: 'Indicates a user signup was successful.'
-      failure: 'Indicates a user signup was not successful.'
+      success:
+        description: 'Indicates a successful user signup.'
+      failure:
+        description: 'Indicates a user signup was not successful.'
+        level: 'error'
 ```
 
-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:
+### Logging in Controllers
+
+Continuing this example, we'll want to log the events we registered. To do so, include the `EventLoggerRails::LoggableController` concern in the controller that
+processes user signup's and call the `log_event` method to log details about the event:
 
 ```ruby
 class UsersController < ApplicationController
-  include Loggable
+  include EventLoggerRails::LoggableController
 
   def create
     user = User.new(user_params)
     if user.save
-      log_event :info, 'user.signup.success'
+      log_event 'user.signup.success'
       redirect_to dashboard_path
     else
-      log_event :error, 'user.signup.failure', errors: user.errors
+      log_event 'user.signup.failure', data: { errors: user.errors.full_messages  }
       render :new
-     end
+    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" } }"}
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "2b8f44c1-0e42-4a5f-84b8-52659990d138",
+  "service_name": "DummyApp",
+  "level": "WARN",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "princess@leia.com",
+      "password": "[FILTERED]"
+    }
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T06:47:16.938+00:00",
+  "event_identifier": "user.signup.success",
+  "event_description": "Indicates a user signup was successful.",
+  "email": "princess@leia.com",
+  "action": "create",
+  "controller": "Registrations"
+}
 ```
 
 ...while a failed signup might look like this:
 
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "2b8f44c1-0e42-4a5f-84b8-52656690d138",
+  "service_name": "DummyApp",
+  "level": "ERROR",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "",
+      "password": "[FILTERED]"
+    },
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T06:47:16.928+00:00",
+  "event_identifier": "user.signup.failure",
+  "event_description": "Indicates a user signup was not successful.",
+  "errors": [
+    "Email can't be blank",
+    "Password can't be blank"
+  ],
+  "email": "princess@leia.com",
+  "action": "create",
+  "controller": "Registrations"
+}
 ```
-[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" }"}
+
+Note how the log entry from the previous example contains the data passed in via the optional `data` argument.
+
+You can also provide a logger level as an optional argument if you need to specify a logger level other than the default. If you provide a logger level, it
+will override the configured event level and the default logger level.
+
+```ruby
+log_event 'user.signup.failure', level: :info, data: { errors: user.errors }
+```
+
+This will output an event with the corresponding severity level. You must provide a valid logger level (`:debug, :info, :warn, :error, or :unknown`).
+
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "2b8f44c1-0e42-4a5f-84b8-52656690d138",
+  "service_name": "DummyApp",
+  "level": "INFO",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "",
+      "password": "[FILTERED]"
+    },
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T06:47:16.928+00:00",
+  "event_identifier": "user.signup.failure",
+  "event_description": "Indicates a user signup was not successful.",
+  "errors": [
+    "Email can't be blank",
+    "Password can't be blank"
+  ],
+  "email": "princess@leia.com",
+  "action": "create",
+  "controller": "Registrations"
+}
 ```
 
-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.
+### Logging in Models
+
+You can also log events from within models by including the `EventLoggerRails::LoggableModel` concern and calling `log_event`.
+
+```ruby
+class User < ApplicationRecord
+  include EventLoggerRails::LoggableModel
+
+  after_create :log_signup
+
+  private
+
+  def log_signup
+    log_event 'user.signup.success', data: { email: }
+  end
+end
+```
+
+By default, `EventLoggerRails` will include the model name, instance ID, and whatever data is passed.
+
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "2b8f44c1-0e42-4a5f-84b8-52652332d138",
+  "service_name": "DummyApp",
+  "level": "WARN",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "princess@leia.com",
+      "password": "[FILTERED]"
+    }
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T06:47:16.817+00:00",
+  "event_identifier": "user.signup.success",
+  "event_description": "Indicates a user signup was successful.",
+  "email": "princess@leia.com",
+  "model": "User",
+  "instance_id": 41
+}
+```
+
+### Logging Everywhere Else
+
+You can log events from anywhere inside of your application by calling `EventLoggerRails.log` directly, though you won't get the additional context
+from the controller or model.
+
+```ruby
+EventLoggerRails.log 'user.signup.success', level: :info, data: { user_id: @user.id }
+```
+
+### Errors
+
+There are two expected errors which are handled by `EventLoggerRails`: an unregistered event and an invalid logger level. Both will result
+in a log entry with an event corresponding to the error, and the severity level will be set to `ERROR`.
+
+If you fail to register an event, the logger will emit an `event_logger_rails.event.unregistered` event:
+
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "94c5ffe9-1bd8-4e04-88a3-478958e242b0",
+  "service_name": "DummyApp",
+  "level": "ERROR",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "",
+      "password": "[FILTERED]"
+    }
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T07:03:34.993+00:00",
+  "event_identifier": "event_logger_rails.event.unregistered",
+  "event_description": "Indicates provided event was unregistered.",
+  "message": "Event provided not registered: foo.bar"
+}
+```
+
+If you provide an invalid log level, the logger will emit an `event_logger_rails.logger_level.invalid` event:
+
+```json
+{
+  "environment": "development",
+  "format": "application/x-www-form-urlencoded;charset=UTF-8",
+  "host": "d6aeb6b0516c",
+  "id": "11541423-0008-4cc7-aef7-1e4af9a801d7",
+  "service_name": "DummyApp",
+  "level": "ERROR",
+  "method": "POST",
+  "parameters": {
+    "authenticity_token": "[FILTERED]",
+    "user": {
+      "email": "",
+      "password": "[FILTERED]"
+    }
+  },
+  "path": "/users",
+  "remote_ip": "172.20.0.1",
+  "timestamp": "2023-09-30T07:04:52.623+00:00",
+  "event_identifier": "event_logger_rails.logger_level.invalid",
+  "event_description": "Indicates provided level was invalid.",
+  "message": "Invalid logger level provided: 'foobar'. Valid levels: :debug, :info, :warn, :error, :unknown."
+}
+```
 
 ## Installation
 
@@ -62,27 +301,54 @@ gem 'event_logger_rails'
 And then execute:
 
 ```bash
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
 
 ```bash
-$ gem install event_logger_rails
+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
+bin/rails generate event_logger_rails:install
 ```
 
 Add your events to the generated config file following the structure of the examples.
 
+You can specify a default level `EventLoggerRails` will use if a level is not included in the call to the logger or configured as a default for the provided event.
+This default level is set to `:warn` unless otherwise specified.
+
+```ruby
+Rails.application.configure do |config|
+  config.event_logger_rails.default_level = :info
+end
+```
+
+By default, `EventLoggerRails` outputs to a separate log file (`log/event_logger_rails.#{Rails.env}.log`) from normal Rails log output, allowing
+you to ingest these logs independently. If you wish to set an alternative log device to capture output, you can configure it in `config/application.rb`:
+
+```ruby
+Rails.application.configure do |config|
+  config.event_logger_rails.logdev = 'path/to/log.file'
+end
+```
+
+Some platforms require logging output to be sent to $STDOUT. You can configure this as an output device easily enough.
+
+```ruby
+Rails.application.configure do |config|
+  config.event_logger_rails.logdev = $stdout
+end
+```
+
 ## Contributing
 
-Contributions are welcome. Feel free to open a PR.
+Your inputs echo in this realm. Venture forth and materialize your thoughts through 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_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Provides event logging with relevant controller/request data.
+  module LoggableController
+    extend ActiveSupport::Concern
+    include EventLoggerRails::Extensions::Loggable
+
+    def optional_data
+      {
+        action: action_name,
+        controller: controller_name.camelcase
+      }
+    end
+
+    private :optional_data
+  end
+end

data/app/models/concerns/event_logger_rails/loggable_model.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Provides event logging with relevant model data.
+  module LoggableModel
+    extend ActiveSupport::Concern
+    include EventLoggerRails::Extensions::Loggable
+
+    def optional_data
+      {
+        model: self.class.name,
+        instance_id: id
+      }
+    end
+
+    private :optional_data
+  end
+end

data/lib/event_logger_rails/current_request.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Provides global state with request details
+  class CurrentRequest < ActiveSupport::CurrentAttributes
+    attribute :id, :format, :method, :parameters, :path, :remote_ip
+  end
+end

data/lib/event_logger_rails/emitter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Processes events, sending data to logger.
+  class Emitter
+    def initialize(logdev:)
+      @logger = JsonLogger.new(logdev)
+    end
+
+    def log(event, level:, data: {})
+      Event.new(event).validate! do |validated_event|
+        message = Message.new(event: validated_event, data:)
+        level = level || validated_event.level || EventLoggerRails.default_level
+        log_message(message, level.to_sym)
+      end
+    rescue Exceptions::UnregisteredEvent, Exceptions::InvalidLoggerLevel => error
+      log(error.event, level: :error, data: { message: error.message })
+    end
+
+    private
+
+    attr_reader :logger
+
+    def log_message(message, level)
+      logger.send(level) { message }
+    rescue NoMethodError
+      raise Exceptions::InvalidLoggerLevel.new(logger_level: level)
+    end
+  end
+end

data/lib/event_logger_rails/engine.rb

@@ -1,7 +1,30 @@
 # frozen_string_literal: true
 
 module EventLoggerRails
+  ##
+  # Engine for plugging into Rails
   class Engine < ::Rails::Engine
     isolate_namespace EventLoggerRails
+
+    config.generators do |generator|
+      generator.test_framework :rspec
+    end
+
+    config.event_logger_rails = ActiveSupport::OrderedOptions.new
+    config.event_logger_rails.logdev = "log/event_logger_rails.#{Rails.env}.log"
+    config.event_logger_rails.default_level = :warn
+
+    initializer 'event_logger_rails.add_middleware' do |app|
+      app.middleware.use Middleware::CaptureRequestDetails
+    end
+
+    config.after_initialize do |app|
+      EventLoggerRails.setup do |engine|
+        engine.default_level = app.config.event_logger_rails.default_level
+        engine.logdev = app.config.event_logger_rails.logdev
+        engine.registered_events = Rails.application.config_for(:event_logger_rails)
+        engine.sensitive_fields = app.config.filter_parameters
+      end
+    end
   end
 end

data/lib/event_logger_rails/event.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Models an event for logging.
+  class Event
+    DEFAULT_EVENTS = {
+      'event_logger_rails.logger_level.invalid' => {
+        description: 'Indicates provided level was invalid.',
+        level: :error
+      },
+      'event_logger_rails.event.unregistered' => {
+        description: 'Indicates provided event was unregistered.',
+        level: :error
+      },
+      'event_logger_rails.event.testing' => {
+        description: 'Event reserved for testing.',
+        level: :warn
+      }
+    }.freeze
+    private_constant :DEFAULT_EVENTS
+
+    attr_reader :identifier, :description, :level
+
+    def initialize(provided_identifier)
+      @provided_identifier = provided_identifier.to_s
+
+      if (default_event = DEFAULT_EVENTS[@provided_identifier])
+        default_registration = [@provided_identifier, *default_event&.values]
+      end
+
+      @identifier, @description, @level = default_registration || config_registration
+    end
+
+    def merge(...)
+      to_hash.merge(...)
+    end
+
+    def valid?
+      identifier.present?
+    end
+
+    def validate!
+      raise Exceptions::UnregisteredEvent.new(unregistered_event: self) unless valid?
+
+      yield(self)
+    end
+
+    def to_hash
+      {
+        event_identifier: identifier,
+        event_description: description
+      }
+    end
+
+    def to_s
+      identifier&.to_s || provided_identifier.to_s
+    end
+
+    def ==(other)
+      to_s == other.to_s
+    end
+
+    private
+
+    attr_reader :provided_identifier
+
+    def config_registration
+      parsed_event = provided_identifier.split('.').map(&:to_sym)
+      config = EventLoggerRails.registered_events.dig(*parsed_event)
+      case config
+      in { description:, level: }
+        [provided_identifier, description, level]
+      in { description: }
+        [provided_identifier, description, nil]
+      else
+        [nil, nil, nil]
+      end
+    end
+  end
+end

data/lib/event_logger_rails/exceptions/invalid_logger_level.rb

@@ -5,11 +5,22 @@ module EventLoggerRails
     ##
     # Indicates invalid log level provided.
     class InvalidLoggerLevel < StandardError
-      attr_reader :logger_level
+      attr_reader :event
 
       def initialize(logger_level:)
-        super("Invalid logger level provided: '#{logger_level}'. Valid levels: debug, info, warn, error, fatal.")
+        super
+        @event = Event.new('event_logger_rails.logger_level.invalid')
+        @logger_level = logger_level
+      end
+
+      def message
+        "Invalid logger level provided: '#{logger_level.to_sym}'. " \
+          'Valid levels: :debug, :info, :warn, :error, :unknown.'
       end
+
+      private
+
+      attr_reader :logger_level
     end
   end
 end

data/lib/event_logger_rails/exceptions/unregistered_event.rb

@@ -5,11 +5,21 @@ module EventLoggerRails
     ##
     # Indicates event provided not registered.
     class UnregisteredEvent < StandardError
-      attr_reader :unregistered_event
+      attr_reader :event
 
       def initialize(unregistered_event:)
-        super("Event provided not registered: #{unregistered_event}")
+        super()
+        @event = Event.new('event_logger_rails.event.unregistered')
+        @unregistered_event = unregistered_event
+      end
+
+      def message
+        "Event provided not registered: #{unregistered_event}"
       end
+
+      private
+
+      attr_reader :unregistered_event
     end
   end
 end

data/lib/event_logger_rails/extensions/loggable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  module Extensions
+    ##
+    # Provides event logging with relevant model data.
+    module Loggable
+      def log_event(event, **kwargs)
+        EventLoggerRails.log(
+          event,
+          level: kwargs[:level] || nil,
+          data: (kwargs[:data] || {}).merge(optional_data)
+        )
+      end
+
+      private
+
+      def optional_data
+        {}
+      end
+    end
+  end
+end

data/lib/event_logger_rails/json_logger.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Writes log entries in JSON format
+  class JsonLogger < ::Logger
+    def initialize(...)
+      super(...)
+      @formatter = proc do |level, timestamp, _progname, message|
+        output = Output.new(level:, timestamp:, message:)
+        "#{output.to_json}\n"
+      end
+    end
+  end
+end

data/lib/event_logger_rails/message.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Models a message sent to the logger containing event and optional data
+  class Message
+    def initialize(event:, data: {})
+      @event = event
+      @data = data
+    end
+
+    def to_hash
+      event.merge(data)
+    end
+
+    private
+
+    attr_reader :event, :data
+  end
+end

data/lib/event_logger_rails/middleware/capture_request_details.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../current_request'
+
+module EventLoggerRails
+  module Middleware
+    ##
+    # Middleware to capture request details and store in global state
+    class CaptureRequestDetails
+      def initialize(app)
+        @app = app
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def call(env)
+        begin
+          request = ActionDispatch::Request.new(env)
+
+          CurrentRequest.id = env['action_dispatch.request_id']
+          CurrentRequest.format = request.headers['Content-Type']
+          CurrentRequest.method = request.method
+          CurrentRequest.parameters = request.parameters.except(:controller, :action, :format)
+          CurrentRequest.path = request.path
+          CurrentRequest.remote_ip = request.remote_ip
+
+          status, headers, body = @app.call(env)
+        ensure
+          CurrentRequest.reset
+        end
+
+        [status, headers, body]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/event_logger_rails/output.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module EventLoggerRails
+  ##
+  # Merges data from application, request, and logger message for structured output
+  class Output
+    def initialize(level:, timestamp:, message:)
+      @current_request = EventLoggerRails::CurrentRequest
+      @level = level
+      @timestamp = timestamp.iso8601(3)
+      @message = message.respond_to?(:to_hash) ? sanitizer.filter(**message) : { message: }
+    end
+
+    def to_json(*args)
+      JSON.generate(to_hash, *args)
+    end
+
+    def to_hash
+      application_data.merge(**current_request_data, **logger_data)
+    end
+
+    private
+
+    attr_reader :level, :timestamp, :message, :current_request
+
+    def sanitizer
+      @sanitizer ||= ActiveSupport::ParameterFilter.new(EventLoggerRails.sensitive_fields)
+    end
+
+    def application_data
+      {
+        environment: Rails.env,
+        host: Socket.gethostname,
+        service_name: Rails.application.class.module_parent_name
+      }
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def current_request_data
+      return {} if CurrentRequest.instance.attributes.blank?
+
+      {
+        format: current_request.format,
+        id: current_request.id,
+        method: current_request.method,
+        parameters: sanitizer.filter(current_request.parameters),
+        path: current_request.path,
+        remote_ip: current_request.remote_ip
+      }
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def logger_data
+      {
+        level:,
+        timestamp:,
+        **message
+      }
+    end
+  end
+end

data/lib/event_logger_rails/version.rb

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

data/lib/event_logger_rails.rb

@@ -2,24 +2,40 @@
 
 require 'rails'
 require 'active_support/dependencies'
-require 'event_logger_rails/version'
 require 'event_logger_rails/engine'
-require 'event_logger_rails/event_logger'
+require 'event_logger_rails/current_request'
+require 'event_logger_rails/event'
+require 'event_logger_rails/emitter'
 require 'event_logger_rails/exceptions/invalid_logger_level'
 require 'event_logger_rails/exceptions/unregistered_event'
+require 'event_logger_rails/extensions/loggable'
+require 'event_logger_rails/json_logger'
+require 'event_logger_rails/message'
+require 'event_logger_rails/middleware/capture_request_details'
+require 'event_logger_rails/output'
+require 'event_logger_rails/version'
 
 ##
-# Namespace for UtilityClasses gem
+# Namespace for EventLoggerRails gem
 module EventLoggerRails
-  autoload :EventLogger, 'event_logger_rails/event_logger'
-  autoload :InvalidLoggerLevel, 'event_logger_rails/exceptions/invalid_logger_level'
-  autoload :UnregisteredEvent, 'event_logger_rails/exceptions/unregistered_event'
+  mattr_accessor :default_level
+  mattr_accessor :logdev
+  mattr_accessor :registered_events
+  mattr_accessor :sensitive_fields
+
+  def self.setup
+    yield self
+  end
+
+  def self.emitter
+    @emitter ||= Emitter.new(logdev:)
+  end
 
-  def self.logger
-    @logger ||= EventLogger.new
+  def self.log(...)
+    emitter.log(...)
   end
 
-  def self.log(*tags, **params)
-    logger.log(*tags, **params)
+  def self.reset
+    @emitter = nil
   end
 end

data/lib/generators/event_logger_rails/install_generator.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
+require 'rails/generators'
+
 module EventLoggerRails
   module Generators
     ##
-    # Creates basic config file for EventLoggerRails
+    # Creates basic config file and initializer for EventLoggerRails
     class InstallGenerator < Rails::Generators::Base
-      desc 'Create basic config file for EventLoggerRails'
+      desc 'Create event registry file'
       source_root File.expand_path('templates', __dir__)
 
       def copy_config_file
+        return if File.exist?(File.join(destination_root, 'config/event_logger_rails.yml'))
+
         copy_file 'event_logger_rails.yml', 'config/event_logger_rails.yml'
       end
     end

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

@@ -1,15 +1,3 @@
-##
-# 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
@@ -17,9 +5,23 @@ logger_levels:
 #
 # Example event:
 #
-# registered_events:
+# shared:
 #   user:
 #     signup:
-#       success: 'Indicates a successful user signup.'
+#       success:
+#         description: 'Indicates a successful user signup.'
+#       failure:
+#         description: 'Indicates a user signup was not successful.'
+#         level: 'error'
+#
+shared:
+
+##
+# Add events that are unique to specific environments by uncommenting the appropriate
+# environment and adding the event.
+#
+# development:
+#
+# test:
 #
-registered_events:
+# production:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_logger_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dick Davis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-27 00:00:00.000000000 Z
+date: 2023-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,7 +24,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.0.0
-description: Rails gem that facilitates logging events for analysis.
+description: |
+  EventLoggerRails is a Rails engine for emitting structured events in logs during the execution of business processes for analysis and visualization.
+  It allows teams to define events in a simple, centralized configuration file, and then log those events in JSON format for further processing.
 email:
 - dick@hey.com
 executables: []
@@ -33,25 +35,33 @@ extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
-- app/controllers/concerns/event_logger_rails/loggable.rb
+- app/controllers/concerns/event_logger_rails/loggable_controller.rb
+- app/models/concerns/event_logger_rails/loggable_model.rb
 - config/routes.rb
 - lib/event_logger_rails.rb
+- lib/event_logger_rails/current_request.rb
+- lib/event_logger_rails/emitter.rb
 - lib/event_logger_rails/engine.rb
-- lib/event_logger_rails/event_logger.rb
+- lib/event_logger_rails/event.rb
 - lib/event_logger_rails/exceptions/invalid_logger_level.rb
 - lib/event_logger_rails/exceptions/unregistered_event.rb
+- lib/event_logger_rails/extensions/loggable.rb
+- lib/event_logger_rails/json_logger.rb
+- lib/event_logger_rails/message.rb
+- lib/event_logger_rails/middleware/capture_request_details.rb
+- lib/event_logger_rails/output.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
+homepage: https://github.com/dickdavis/event_logger_rails
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  homepage_uri: https://github.com/d3d1rty/event_logger_rails
-  source_code_uri: https://github.com/d3d1rty/event_logger_rails
-  changelog_uri: https://github.com/d3d1rty/event_logger_rails/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/dickdavis/event_logger_rails
+  source_code_uri: https://github.com/dickdavis/event_logger_rails/tree/0.3.0
+  changelog_uri: https://github.com/dickdavis/event_logger_rails/blob/0.3.0/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -60,15 +70,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: 3.1.4
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: Rails gem that facilitates logging events for analysis.
+summary: Rails gem weaving the fabric of logged events into tapestries for analytic
+  reverie.
 test_files: []

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

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module EventLoggerRails
-  ##
-  # Provides event logging with relevant controller/request data.
-  module Loggable
-    extend ActiveSupport::Concern
-
-    def log_event(level, event, **data)
-      data_to_log = data_from_request.merge(data)
-      EventLoggerRails.log(level, event, **data_to_log)
-    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
-      {
-        controller: controller_name.camelcase,
-        action: action_name,
-        method: request.method,
-        path: request.path,
-        remote_ip: request.remote_ip,
-        parameters: request.query_parameters.to_json
-      }
-    end
-  end
-end

data/lib/event_logger_rails/event_logger.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-
-require_relative 'exceptions/invalid_logger_level'
-require_relative 'exceptions/unregistered_event'
-
-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
-      @last_updated = File.ctime(config_file)
-    end
-
-    def log(*tags, **params)
-      reload_config if config_changed?
-
-      level, event = *tags
-      validate_tags(level, event)
-      logger = ActiveSupport::TaggedLogging.new(Logger.new(output_device))
-      logger.tagged("#{level.to_s.upcase} | #{DateTime.current} | #{event}") { logger.send(level, **params.as_json) }
-    end
-
-    private
-
-    attr_reader :logger_levels, :registered_events, :last_updated
-
-    def logger_levels_from_config
-      data_from_config[:logger_levels].map(&:to_sym)
-    end
-
-    def registered_events_from_config
-      data_from_config[:registered_events]
-    end
-
-    def data_from_config
-      YAML.safe_load(File.read(config_file)).deep_symbolize_keys
-    end
-
-    def config_file
-      Rails.root.join('config/event_logger_rails.yml')
-    end
-
-    def reload_config
-      @logger_levels = logger_levels_from_config
-      @registered_events = registered_events_from_config
-      @last_updated = File.ctime(config_file)
-    end
-
-    def config_changed?
-      return false unless Rails.env.development?
-
-      last_updated != File.ctime(config_file)
-    end
-
-    def validate_tags(level, event)
-      validate_logger_level(level) && validate_event(event)
-    end
-
-    def validate_logger_level(level)
-      return true if logger_levels.include?(level)
-
-      raise EventLoggerRails::Exceptions::InvalidLoggerLevel.new(logger_level: level)
-    end
-
-    def validate_event(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?
-
-      File.open(File::NULL, 'w')
-    end
-  end
-end