green_log 0.1.0

data/examples/try-it

@@ -0,0 +1,21 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+require "green_log/logger"
+require "green_log/json_writer"
+require "green_log/simple_writer"
+require "pry"
+
+case ARGV.first
+when "json"
+  writer_class = GreenLog::JsonWriter
+when "simple", nil
+  writer_class = GreenLog::SimpleWriter
+else
+  raise ArgumentError, "bad format: #{ARGV.first}"
+end
+
+logger = GreenLog::Logger.new(writer_class.new(STDOUT))
+logger.pry

data/green_log.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "green_log/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "green_log"
+  spec.version       = GreenLog::VERSION
+  spec.authors       = ["Mike Williams"]
+  spec.email         = ["mike.williams@greensync.com.au"]
+
+  spec.summary       = "Structured logging for cloud-native systems."
+  spec.homepage      = "https://github.com/greensync/green_log"
+  spec.license       = "MIT"
+
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob("{bin,doc,examples,lib}/**/*") + %w[
+      README.md green_log.gemspec
+    ]
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "values", "~> 1.8"
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "pry", "~> 0.12.2"
+  spec.add_development_dependency "rack"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 0.77"
+
+end

data/lib/green_log.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "green_log/json_writer"
+require "green_log/logger"
+require "green_log/simple_writer"
+require "green_log/version"

data/lib/green_log/classic_logger.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "green_log/contextualizer"
+require "green_log/entry"
+require "green_log/severity"
+require "green_log/severity_threshold_support"
+
+module GreenLog
+
+  # An alternative to `GreenLog::Logger` for older code, which implements the
+  # same interface as the built-in Ruby `::Logger`.
+  class ClassicLogger
+
+    def initialize(downstream)
+      @downstream = downstream
+    end
+
+    attr_reader :downstream
+
+    include SeverityThresholdSupport
+
+    def add(severity, message = :unspecified, &block)
+      severity = Integer(severity)
+      return if severity < severity_threshold
+
+      entry = Entry.build(severity, resolve_message(message, &block))
+
+      downstream << entry
+
+      true
+    end
+
+    Severity::NAMES.each_with_index do |name, severity|
+
+      define_method(name.downcase) do |message = :unspecified, &block|
+        add(severity, message, &block)
+      end
+
+      define_method("#{name.downcase}?") do
+        severity >= severity_threshold
+      end
+
+    end
+
+    private
+
+    def resolve_message(message, &block)
+      normalise_message(extract_message(message, &block))
+    end
+
+    def extract_message(message, &block)
+      if block
+        raise ArgumentError, "both message and block provided" unless message == :unspecified
+
+        return block.call
+      end
+      raise ArgumentError, "no message provided" if message == :unspecified
+
+      message
+    end
+
+    def normalise_message(message)
+      return message if message.is_a?(Exception)
+      return message.to_str if message.respond_to?(:to_str)
+
+      message.inspect
+    end
+
+  end
+
+  # :rubocop:disable: Style/Documentation
+  class Logger
+
+    def to_classic_logger
+      GreenLog::ClassicLogger.new(downstream)
+    end
+
+  end
+
+end

data/lib/green_log/contextualizer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "green_log/severity_threshold_support"
+
+module GreenLog
+
+  # Log middleware that adds context.
+  class Contextualizer
+
+    def initialize(downstream, &context_generator)
+      @downstream = downstream
+      @context_generator = context_generator
+    end
+
+    attr_reader :downstream
+    attr_reader :context_generator
+
+    def <<(entry)
+      downstream << entry.in_context(context_generator.call)
+    end
+
+    include SeverityThresholdSupport
+
+  end
+
+end

data/lib/green_log/core_refinements.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module GreenLog
+
+  # Refine
+  module CoreRefinements
+
+    refine ::Hash do
+
+      def to_loggable_value
+        {}.tap do |result|
+          each do |k, v|
+            result[k.to_sym] = v.to_loggable_value
+          end
+        end.freeze
+      end
+
+      def integrate(other)
+        other = other.to_hash
+        merge(other) do |_key, old_value, new_value|
+          if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+            old_value.integrate(new_value)
+          else
+            new_value
+          end
+        end
+      end
+
+    end
+
+    refine ::Numeric do
+
+      def to_loggable_value
+        self
+      end
+
+    end
+
+    refine ::String do
+
+      def to_loggable_value
+        frozen? ? self : dup.freeze
+      end
+
+    end
+
+    refine ::NilClass do
+
+      def to_loggable_value
+        self
+      end
+
+    end
+
+    refine ::TrueClass do
+
+      def to_loggable_value
+        self
+      end
+
+    end
+
+    refine ::FalseClass do
+
+      def to_loggable_value
+        self
+      end
+
+    end
+
+  end
+
+end

data/lib/green_log/entry.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "green_log/core_refinements"
+require "green_log/severity"
+require "values"
+
+module GreenLog
+
+  # Represents a structured log entry.
+  class Entry < Value.new(:severity, :message, :context, :data, :exception)
+
+    using CoreRefinements
+
+    class << self
+
+      def with(**args)
+        args[:severity] = Severity.resolve(
+          args.fetch(:severity, Severity::INFO),
+        )
+        args[:message] ||= nil
+        args[:context] = args.fetch(:context, {}).to_loggable_value
+        args[:data] = args.fetch(:data, {}).to_loggable_value
+        args[:exception] ||= nil
+        super(**args)
+      end
+
+      def build(severity, *args, &block)
+        Builder.new(severity).build(*args, &block)
+      end
+
+    end
+
+    def in_context(extra_context)
+      with(context: extra_context.integrate(context).to_loggable_value)
+    end
+
+    # A builder for entries.
+    class Builder
+
+      def initialize(severity)
+        @severity = severity
+      end
+
+      attr_reader :severity
+      attr_reader :message
+      attr_reader :data
+      attr_reader :exception
+
+      def message=(arg)
+        raise ArgumentError, ":message already specified" if defined?(@message)
+
+        @message = arg
+      end
+
+      def data=(arg)
+        raise ArgumentError, ":data already specified" if defined?(@data)
+
+        @data = arg
+      end
+
+      def exception=(arg)
+        raise ArgumentError, ":exception already specified" if defined?(@exception)
+
+        @exception = arg
+      end
+
+      def build(*args, &block)
+        args.each(&method(:handle_arg))
+        if block
+          if block.arity.zero?
+            Array(block.call).each(&method(:handle_arg))
+          else
+            block.call(self)
+          end
+        end
+        Entry.with(severity: severity, message: message, data: data, exception: exception)
+      end
+
+      private
+
+      def handle_arg(arg)
+        public_send("#{arg_type(arg)}=", arg)
+      end
+
+      def arg_type(arg)
+        case arg
+        when String
+          :message
+        when Hash
+          :data
+        when Exception
+          :exception
+        else
+          raise ArgumentError, "un-loggable argument: #{arg.inspect}"
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/green_log/json_writer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "green_log/entry"
+require "green_log/severity"
+require "json"
+
+module GreenLog
+
+  # A JSON-formated log.
+  class JsonWriter
+
+    def initialize(dest)
+      @dest = dest
+    end
+
+    attr_reader :dest
+
+    def <<(entry)
+      raise ArgumentError, "GreenLog::Entry expected" unless entry.is_a?(GreenLog::Entry)
+
+      dest << JSON.dump(entry_details(entry)) + "\n"
+    end
+
+    protected
+
+    def entry_details(entry)
+      {
+        "severity" => Severity.name(entry.severity).upcase,
+        "message" => entry.message,
+        "data" => entry.data,
+        "context" => entry.context,
+        "exception" => exception_details(entry.exception),
+      }.compact
+    end
+
+    def exception_details(exception)
+      return nil if exception.nil?
+
+      {
+        "class" => exception.class.name,
+        "message" => exception.message,
+        "backtrace" => exception.backtrace,
+      }
+    end
+
+  end
+
+end

data/lib/green_log/logger.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "green_log/contextualizer"
+require "green_log/entry"
+require "green_log/severity"
+require "green_log/severity_filter"
+require "green_log/severity_threshold_support"
+require "green_log/simple_writer"
+
+module GreenLog
+
+  # Log entry generator.
+  class Logger
+
+    def initialize(downstream)
+      @downstream = downstream
+    end
+
+    attr_reader :downstream
+
+    include SeverityThresholdSupport
+
+    # Generate a log entry.
+    # Arguments may include:
+    #   - a message string
+    #   - arbitrary data
+    #   - an exception
+    def log(severity, *rest, &block)
+      severity = Severity.resolve(severity)
+      return false if severity < severity_threshold
+
+      entry = Entry.build(severity, *rest, &block)
+      downstream << entry
+      true
+    end
+
+    Severity::NAMES.each_with_index do |name, severity|
+
+      define_method(name.downcase) do |*args, &block|
+        log(severity, *args, &block)
+      end
+
+    end
+
+    # Add a middleware in front of the downstream handler.
+    # Return a new Logger with the expanded handler-stack.
+    def with_middleware
+      self.class.new(yield(downstream))
+    end
+
+    # Add a middleware that adds context.
+    # Return a new Logger with the expanded handler-stack.
+    def with_context(static_context = nil, &context_generator)
+      with_middleware do |current_downstream|
+        downstream = current_downstream
+        downstream = Contextualizer.new(downstream) { static_context } unless static_context.nil?
+        downstream = Contextualizer.new(downstream, &context_generator) unless context_generator.nil?
+        downstream
+      end
+    end
+
+    # Add a middleware that filters by severity.
+    # Return a new Logger with the expanded handler-stack.
+    def with_severity_threshold(threshold)
+      with_middleware do |downstream|
+        SeverityFilter.new(downstream, threshold: threshold)
+      end
+    end
+
+    class << self
+
+      # Build a Logger.
+      def build(dest: $stdout, format: SimpleWriter, severity_threshold: nil)
+        format = resolve_format(format)
+        downstream = format.new(dest)
+        downstream = SeverityFilter.new(downstream, threshold: severity_threshold) if severity_threshold
+        new(downstream)
+      end
+
+      def resolve_format(format)
+        return format if format.is_a?(Class)
+
+        format = format.to_s if format.is_a?(Symbol)
+        GreenLog.const_get("#{format.capitalize}Writer")
+      end
+
+    end
+
+  end
+
+end