mr_loga_loga 0.1.0

data/README.md

@@ -0,0 +1,196 @@
+<div align="center">
+
+# Mr. Loga Loga
+
+<img alt="logo" src="logo.png" width="300px" height="auto">
+
+### The simply bombastic, fantastic logger for Ruby 💎
+
+[![Gem Version](https://badge.fury.io/rb/mr_loga_loga.svg)](https://badge.fury.io/rb/mr_loga_loga)
+[![Main](https://github.com/hschne/mr-loga-loga/actions/workflows/main.yml/badge.svg)](https://github.com/hschne/mr-loga-loga/actions/workflows/main.yml)
+![License](https://img.shields.io/github/license/hschne/mr-loga-loga)
+
+## What's this?
+
+MrLogaLoga is a logger for Ruby that allows you to easily attach contextual information to your log messages. When writing logs, messages only tell half the story. MrLogaLoga allows you to make the most of your logs:
+
+```ruby
+logger.info('message', user: 'name', data: 1)
+# I, [2022-01-01T12:00:00.000000 #19074]  INFO -- Main: message user=user data=1
+```
+
+You can find out more about the motivation behind the project [here](#why-mrlogaloga). For usage read [Usage](#usage) or [Advanced Usage](#advanced-usage)
+
+**Note**: This gem is in early development. Try it out and leave some feedback, it really goes a long way in helping me out with development. Any [feature request](https://github.com/hschne/mr-loga-loga/issues/new?assignees=&labels=type%3ABug&template=FEATURE_REQUEST.md&title=) or [bug report](https://github.com/hschne/mr-loga-loga/issues/new?assignees=&labels=type%3AEnhancement&template=BUG_REPORT.md&title=) is welcome. If you like this project, leave a star to show your support! ⭐
+
+## Getting Started
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mr_loga_loga'
+```
+
+And then execute:
+
+```
+bundle install
+```
+
+## Usage
+
+MrLogaLoga provides the same interface as the Ruby default logger you are used to. In addition, however, you can attach contextual information to your log messages:
+
+```ruby
+require 'mr_loga_loga'
+
+logger = MrLogaLoga::Logger.new
+logger.info('message', user: 'name', data: 1) 
+# I, [2022-01-01T12:00:00.000000 #19074]  INFO -- Main: message user=user data=1
+logger.context(class: 'classname').warn('message') 
+# W, [2022-01-01T12:00:00.000000 #19074]  WARN -- Main: message class=classname
+```
+
+To customize how log messages are formatted see [Formatters][#formatters].
+
+## Advanced Usage
+
+MrLogaLoga provides a fluent interface to build log messages. For example, to attach an additional `user` field to a log message you can use any of the following:
+
+```ruby
+logger.info('message', user: 'name')
+logger.context(user: 'name').info('message') # Explicit context
+logger.context { { user: 'name' } }.info('message') # Block context
+logger.user('name').info('message') # Dynamic context method
+logger.user { 'name' }.info('message') # Dynamic context block
+```
+
+The block syntax [ is recommended when logging calculated properties ](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html#class-Logger-label-How+to+log+a+message).
+
+#### Shared Context
+
+If multiple log messages within the same class should share a context include the `MrLogaLoga` module. Using `logger` will result in the defined context being included per default:
+
+```ruby
+class MyClass 
+  include MrLogaLoga
+
+  # This is the default. You may overwrite this in your own classes
+  def loga_context 
+     { class_name: self.class.name } 
+  end
+
+  def log
+   # This includes the class name in the log message now
+   logger.debug('debug') # debug class_name=MyClass
+   # Additional context will be merged
+   logger.debug('debug', user: 'user') # debug class_name=MyClass user=user
+  end
+end
+```
+
+When used with [Rails](#rails) logger will default to `Rails.logger`. If you use MrLogaLoga outside of Rails, you can either configure the logger instance to be used globally, or by overwriting the `loga_loga` method:
+
+```ruby
+# In some configuration class
+MrLogaLoga.configure do |configuration|
+  logger = MrLogaLoga::Logger.new($stdout)
+end
+
+# In the class where you do the logging itself
+class MyClass 
+  include MrLogaLoga
+
+  def loga_loga
+    MrLogaLoga::Logger.new($stdout)
+  end
+
+  def log
+    # ...
+  end
+end
+```
+
+
+### Formatters
+
+MrLogaLoga uses the [KeyValue](https://github.com/hschne/mr-loga-loga/blob/main/lib/mr_loga_loga/formatters/key_value.rb) formatter per default. The [Json](https://github.com/hschne/mr-loga-loga/blob/main/lib/mr_loga_loga/formatters/json.rb) formatter is also included. To use a specific formatter pass it to the logger constructor:
+
+```Ruby
+
+MrLogaLoga::Logger.new(STDOUT, formatter: MrLogaLoga::Formatters::KeyValue.new)
+```
+
+You can implement and add your own formatters like so:
+
+```ruby
+class MyFormatter
+  def call(severity, datetime, progname, message, context)
+    context = context.map { |key, value| "#{key}=#{value}" }.compact.join(' ')
+    "#{severity} #{datetime.strftime('%Y-%m-%dT%H:%M:%S.%6N')} #{progname} #{message} #{context}"
+  end
+end
+
+MrLogaLoga::Logger.new(STDOUT, formatter: MyFormatter.new)
+```
+
+### Rails
+
+Using MrLogaLoga in Ruby on Rails is straightforward. Set up MrLogaLoga as logger in your `application.rb` or environment files and you are off to the races:
+
+```ruby
+# application.rb
+config.logger = MrLogaLoga::Logger.new(STDOUT)
+config.log_level = :info
+```
+
+Note that setting `config.log_formatter` does not work. You must set the formatter in the logger constructor as described in [Formatters](#formatters).
+
+### Lograge
+
+[LogRage](https://github.com/roidrage/lograge) and MrLogaLoga work well together. When using both gems Lograge will be patched so that data will be available as `context` in MrLogaLoga. Make sure that MrLogaLoga is required **after** Lograge: 
+
+```ruby
+gem 'lograge'
+gem 'mr_loga_loga'
+```
+
+Note that Lograge's formatters won't be used. Use MrLogaLoga's own [formatters](#formatters) instead.
+
+## Why MrLogaLoga?
+
+The more context your logs provide, the more use you will get out of them. The standard Ruby logger only takes a string as an argument, so you have to resort to something like this:
+
+```ruby
+logger.debug("my message user=#{user} more_data=#{data}")
+```
+
+This is fine, as long as you do not need to change your log format. Changing your log formatter will not change the format of your message, nor the formatting of the contextual information you provided.
+
+MrLogaLoga addresses this by allowing you to attach contextual information to your logs and giving you full control over how both message and context are formatted.
+
+## Credit
+
+This little library was inspired by [Lograge](https://github.com/roidrage/lograge) first and foremost. I would like to thank the amazing [@LenaSchnedlitz](https://twitter.com/LenaSchnedlitz) for the incredible logo! 🤩
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests and linter. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Thank you for contributing! :heart:
+
+We welcome all support, whether on bug reports, code, design, reviews, tests, documentation, translations, or just feature requests.
+
+Please use [GitHub issues](https://github.com/hschne/rails-mini-profiler/issues) to submit bugs or feature requests.
+
+## License
+
+The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the MrLogaLoga project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/hschne/mr_loga_loga/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'mr_loga_loga'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/mr_loga_loga/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MrLogaLoga
+  # == Description
+  #
+  # The configuration class for MrLogaLoga
+  #
+  # == Usage
+  #
+  #   MrLogaLoga.configure do |configuration|
+  #     configuration.logger = ...
+  #   end
+  class Configuration
+    attr_accessor :logger
+
+    # Initialize the configuration by setting configuration default values
+    def initialize(**kwargs)
+      reset
+      kwargs.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    # Reset the configuration to default values
+    def reset
+      @logger = MrLogaLoga::Logger.new($stdout)
+    end
+  end
+end

data/lib/mr_loga_loga/context.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module MrLogaLoga
+  # == Description
+  #
+  # This class provides a fluent interface to attach contextual information to log messages.
+  class Context
+    def initialize(logger, context = {})
+      @logger = logger
+      @context = context
+    end
+
+    def context(context = {}, &block)
+      @context = merge_context(@context, context)
+      @context = merge_context(@context, block)
+      self
+    end
+
+    def add(severity, message = nil, **context, &block)
+      severity ||= UNKNOWN
+      return true unless @logger.log?(severity)
+
+      context = merge_context(@context, context)
+      context = context.call if context.is_a?(Proc)
+
+      @logger.add(severity, message, **context, &block)
+    end
+
+    alias log add
+
+    %i[debug info warn error fatal unknown].each do |symbol|
+      define_method(symbol) do |message = nil, **context, &block|
+        severity = Object.const_get("Logger::Severity::#{symbol.to_s.upcase}")
+        return true unless @logger.log?(severity)
+
+        context = merge_context(@context, context)
+        context = context.call if context.is_a?(Proc)
+        @logger.public_send(symbol, message, **context, &block)
+      end
+    end
+
+    def method_missing(symbol, *args, &block)
+      context = block ? -> { { symbol => block.call } } : { symbol => unwrap(args) }
+      @context = merge_context(@context, context)
+      self
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      super(name, include_private)
+    end
+
+    private
+
+    def unwrap(args)
+      if args.size == 1
+        args[0]
+      else
+        args
+      end
+    end
+
+    def merge_context(original, new)
+      return original unless new
+
+      return original.merge(new) if original.is_a?(Hash) && new.is_a?(Hash)
+
+      merge_blocks(original, new)
+    end
+
+    def merge_blocks(original, new)
+      return -> { original.merge(new.call) } if original.is_a?(Hash) && new.is_a?(Proc)
+
+      return -> { original.call.merge(new) } if original.is_a?(Proc) && new.is_a?(Hash)
+
+      -> { original.call.merge(new.call) }
+    end
+  end
+end

data/lib/mr_loga_loga/extensions/lograge_patch.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'byebug'
+
+module MrLogaLoga
+  module Adapters
+    # This patches Lograge to forward data as context to MrLogaLoga
+    module LogragePatch
+      class << self
+        def apply
+          return unless defined?(Lograge)
+
+          patch_applies = defined?(Lograge::LogSubscribers::Base) &&
+                          Lograge::LogSubscribers::Base.private_method_defined?(:process_main_event)
+          unless patch_applies
+            puts 'WARNING: Failed to patch Lograge. It looks like '\
+                 "MrLogaLoga's patch no longer applies in "\
+                 "#{__FILE__}. Please contact MrLogaLoga maintainers."
+            return
+          end
+
+          Lograge::LogSubscribers::Base.prepend(self)
+        end
+      end
+
+      def process_main_event(event)
+        return if Lograge.ignore?(event)
+
+        payload = event.payload
+        data = extract_request(event, payload)
+        data = before_format(data, payload)
+        if logger.is_a?(MrLogaLoga::Logger)
+          logger.send(Lograge.log_level, '', **data)
+        else
+          formatted_message = Lograge.formatter.call(data)
+          logger.send(Lograge.log_level, formatted_message)
+        end
+      end
+    end
+  end
+end
+
+MrLogaLoga::Adapters::LogragePatch.apply

data/lib/mr_loga_loga/formatters/json.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MrLogaLoga
+  module Formatters
+    # == Description
+    #
+    # A simple Json formatter for MrLogaLoga.
+    #
+    # == Format
+    #
+    # The json formatter renders messages into a single-line json. Context keys are embedded on the top level.
+    #
+    # Log Format:
+    #
+    #   { "severity": "Severity", .. "message": "Message", "key1": "Key1" }
+    #
+    class Json < Logger::Formatter
+      # Render a log message in JSON
+      #
+      # @param severity [String] The message severity
+      # @param datetime [DateTime] The message date time
+      # @param progname [DateTime] The program name
+      # @param message [String] The log message
+      # @param context [Hash] The log message context
+      #
+      # @return [String] the formatted log message
+      def call(severity, datetime, progname, message, context)
+        message = message.nil? || message.empty? ? nil : msg2str(message)
+
+        message_hash = {
+          severity: severity,
+          datetime: datetime.strftime('%Y-%m-%dT%H:%M:%S.%6N'),
+          pid: Process.pid,
+          progname: progname,
+          message: message,
+          **context
+        }.compact
+        "#{message_hash.to_json}\n"
+      end
+    end
+  end
+end

data/lib/mr_loga_loga/formatters/key_value.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MrLogaLoga
+  module Formatters
+    # == Description
+    #
+    # A simple key value formatter that extends the standard formatter by rendering additional contextual information.
+    #
+    # == Format
+    #
+    # The key-value formatter renders messages into the following format:
+    #
+    # Log format:
+    #
+    #   SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message key1=value1 key2=value2
+    #
+    class KeyValue < Logger::Formatter
+      # Render a log message
+      #
+      # @param severity [String] The message severity
+      # @param datetime [DateTime] The message date time
+      # @param progname [DateTime] The program name
+      # @param message [String] The log message
+      # @param context [Hash] The log message context
+      #
+      # @return [String] the formatted log message
+      def call(severity, datetime, progname, message, context)
+        message = context.map { |key, value| "#{key}=#{value}" }
+                    .prepend(message)
+                    .compact
+                    .join(' ')
+        super(severity, datetime, progname, message)
+      end
+    end
+  end
+end

data/lib/mr_loga_loga/instance_methods.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MrLogaLoga
+  # == Description
+  #
+  # Instance methods to be attached when including the main module.
+  #
+  # @api private
+  module InstanceMethods
+    def loga_context
+      { class_name: self.class.name }
+    end
+
+    def logger
+      MrLogaLoga::LoggerProxy.new(loga_loga, -> { loga_context })
+    end
+
+    def loga_loga
+      @loga_loga ||= if defined?(Rails.application.logger)
+                       Rails.application.logger
+                     else
+                       MrLogaLoga.configuration.logger
+                     end
+    end
+  end
+end

data/lib/mr_loga_loga/logger.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module MrLogaLoga
+  # == Description
+  #
+  # This class extends the default Ruby Logger to allow users to attach contextual information to log messages.
+  #
+  # === Example
+  #
+  # This creates a Logger that outputs to the standard output stream, with a
+  # level of +WARN+:
+  #
+  #   require 'mr_loga_loga'
+  #
+  #   logger = MrLogaLoga::Logger.new(STDOUT)
+  #   logger.level = Logger::WARN
+  #
+  #   logger.debug("Default")
+  #   logger.context(user: 1).debug('with context')
+  class Logger < ::Logger
+    def context(**kwargs, &block)
+      context = block ? -> { kwargs.merge(block.call) } : kwargs
+      Context.new(self, context)
+    end
+
+    def message(message, &block)
+      message ||= block
+      Message.new(self, message)
+    end
+
+    def add(severity, message = nil, progname = nil, **context, &block)
+      severity ||= UNKNOWN
+      return true unless log?(severity)
+
+      message = block.call if block
+      @logdev.write(format(format_severity(severity), Time.now, progname, message, context))
+      true
+    end
+
+    alias log add
+
+    %i[debug info warn error fatal unknown].each do |symbol|
+      define_method(symbol) do |message = nil, **context, &block|
+        # Map the symbol (e.g. :debug) to the severity constant (e.g. DEBUG)
+        severity = Object.const_get("Logger::Severity::#{symbol.to_s.upcase}")
+        add(severity, message, **context, &block)
+      end
+    end
+
+    def method_missing(symbol, *args, &block)
+      context = block ? -> { { symbol => block.call } } : { symbol => unwrap(args) }
+      Context.new(self, context)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      super(name, include_private)
+    end
+
+    def log?(severity)
+      !@logdev.nil? && severity >= level
+    end
+
+    private
+
+    def unwrap(args)
+      if args.size == 1
+        args[0]
+      else
+        args
+      end
+    end
+
+    def format(severity, datetime, progname, message, context)
+      formatter.call(severity, datetime, progname, message, context)
+    end
+
+    def formatter
+      @formatter ||= MrLogaLoga::Formatters::KeyValue.new
+    end
+  end
+end

data/lib/mr_loga_loga/logger_proxy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module MrLogaLoga
+  # == Description
+  #
+  # A proxy that attaches contextual information to the underlying logger when called.
+  #
+  # @api private
+  class LoggerProxy
+    def initialize(logger, context_proc)
+      @logger = logger
+      @context_proc = context_proc
+    end
+
+    def add(severity, message = nil, **context, &block)
+      severity ||= UNKNOWN
+      return true unless @logger.log?(severity)
+
+      context = @context_proc.call.merge(context)
+
+      @logger.add(severity, message, **context, &block)
+    end
+
+    alias log add
+
+    %i[debug info warn error fatal unknown].each do |symbol|
+      define_method(symbol) do |message = nil, **context, &block|
+        severity = Object.const_get("Logger::Severity::#{symbol.to_s.upcase}")
+        return true unless @logger.log?(severity)
+
+        context = @context_proc.call.merge(context)
+
+        @logger.public_send(symbol, message, **context, &block)
+      end
+    end
+  end
+end

data/lib/mr_loga_loga/version.rb

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

data/lib/mr_loga_loga.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'byebug'
+
+require_relative 'mr_loga_loga/version'
+require_relative 'mr_loga_loga/configuration'
+require_relative 'mr_loga_loga/logger_proxy'
+require_relative 'mr_loga_loga/instance_methods'
+require_relative 'mr_loga_loga/context'
+require_relative 'mr_loga_loga/logger'
+require_relative 'mr_loga_loga/formatters/key_value'
+require_relative 'mr_loga_loga/formatters/json'
+
+require_relative 'mr_loga_loga/extensions/lograge_patch'
+
+# == Description
+#
+# The MrLogaLoga module provides additional logging functionality when included in your classes.
+#
+module MrLogaLoga
+  class Error < StandardError; end
+
+  def self.included(base)
+    base.send :include, InstanceMethods
+  end
+
+  class << self
+    # Create a new configuration object
+    #
+    # @return [Configuration] a new configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end