twiglet 2.3.9 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd37b7e4eb03587c77c448d986a57dea2db5c119208c9588d400614785c9ab00
-  data.tar.gz: 2087e6acf11a7944083c81a493f8dc1608f8789ea5e5fb09cdbe8fbad7391456
+  metadata.gz: 65c3f0028e0ac918736f63a2475fb45231586d51256a8778d4730ebd7792675c
+  data.tar.gz: 98d3607d5e1aad68f00d0ced7ccce24f0dba0c8b3eede84620a4a37a102a9849
 SHA512:
-  metadata.gz: 15599c765672e0bcbdbd03f717dde89ccb99ac2142bbb9aad56337466f31c0e9355aa18cd07b4f6cbe9cf53768d9e8efc59042c98aa66aacf82a3ce4e1296993
-  data.tar.gz: 67c1dae018c5fa57e4bffc0144b58ae5e9316faf4a1190d919d5828a44240955d246a12e6dde07b34b459694eb4808ac81d02fe2b08bc0187dce3562c8d94e6f
+  metadata.gz: '0418346dbb4f5d486062caa13b7d1859a96309d00061b3e818563c9c399601f73035e2c89c64888e168d2a040fbb96c18a47e150c505859a58c067cfe46fe76f'
+  data.tar.gz: 9437cae3f2662746cd059a660f9e0884c5c0edd7e56de77771d81678c01f6e55006e048b50bd44f7a99d240b9a5d3527b70a15528d0f4e8711ca2e0954c73235

data/.github/workflows/ruby.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby-version: [2.5, 2.6, 2.7]
+        ruby-version: [2.6, 2.7]
 
     steps:
     - uses: actions/checkout@v2

data/.rubocop.yml

@@ -2,7 +2,7 @@ inherit_gem:
   simplycop: .simplycop.yml
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.6
   Rails:
     Enabled: false
   Documentation:

data/Gemfile

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
-gem 'simplycop', git: 'https://github.com/simplybusiness/simplycop.git'
 group :development, :test do
   gem 'minitest'
   gem 'rake'
   gem 'simplecov', '0.17.1'
+  gem 'simplycop'
 end

data/Makefile

@@ -1,9 +1,21 @@
-.PHONY: all build test
+.PHONY: all build clean shell test
 
-all: build test
+all: clean build test
 
 build:
 	docker build -t simplybusiness/ruby-dev:2.6.5 .
 
+clean:
+	rm -f *~
+
+shell:
+	docker run -it \
+	-v `pwd`:/var/app \
+	simplybusiness/ruby-dev:2.6.5 \
+	bash
+
 test:
-	docker run -it -v `pwd`:/var/app simplybusiness/ruby-dev:2.6.5 bundle exec rake test
+	docker run -it \
+	-v `pwd`:/var/app \
+	simplybusiness/ruby-dev:2.6.5 \
+	bundle exec rake test

data/README.md

@@ -11,13 +11,13 @@ gem install twiglet
 
 ## How to use
 
-Create a new logger like so:
+### Instantiate the logger
 
 ```ruby
 require 'twiglet/logger'
 logger = Twiglet::Logger.new('service name')
 ```
-
+#### Optional initialization parameters
 A hash can optionally be passed in as a keyword argument for `default_properties`. This hash must be in the Elastic Common Schema format and will be present in every log message created by this Twiglet logger object.
 
 You may also provide an optional `output` keyword argument which should be an object with a `puts` method - like `$stdout`.
@@ -28,7 +28,7 @@ Lastly, you may provide the optional keyword argument `level` to initialize the
 
 The defaults for both `output` and `now` should serve for most uses, though you may want to override them for testing as we have done [here](test/logger_test.rb).
 
-To use, simply invoke like most other loggers:
+### Invoke the Logger
 
 ```ruby
 logger.error({ event: { action: 'startup' }, message: "Emergency! There's an Emergency going on" })
@@ -42,9 +42,10 @@ This will write to STDOUT a JSON string:
 
 Obviously the timestamp will be different.
 
-Alternatively, if you just want to log some error message in text format
+Alternatively, if you just want to log some error string:
+
 ```ruby
-logger.error( "Emergency! There's an Emergency going on")
+logger.error("Emergency! There's an Emergency going on")
 ```
 
 This will write to STDOUT a JSON string:
@@ -53,14 +54,27 @@ This will write to STDOUT a JSON string:
 {"service":{"name":"service name"},"@timestamp":"2020-05-14T10:54:59.164+01:00","log":{"level":"error"}, "message":"Emergency! There's an Emergency going on"}
 ```
 
-Errors can be logged as well, and this will log the error message and backtrace in the relevant ECS compliant fields:
+A message is always required unless a block is provided. The message can be an object or a string.
+
+#### Error logging
+An optional error can also be provided, in which case the error message and backtrace will be logged in the relevant ECS compliant fields:
 
 ```ruby
 db_err = StandardError.new('Connection timed-out')
 logger.error({ message: 'DB connection failed.' }, db_err)
+
+# this is also valid
+logger.error('DB connection failed.', db_err)
+```
+
+These will both result in the same JSON string written to STDOUT:
+
+```json
+{"ecs":{"version":"1.5.0"},"@timestamp":"2020-08-21T15:44:37.890Z","service":{"name":"service name"},"log":{"level":"error"},"message":"DB connection failed.","error":{"message":"Connection timed-out"}}
 ```
 
-Add log event specific information simply as attributes in a hash:
+#### Custom fields
+Log custom event-specific information simply as attributes in a hash:
 
 ```ruby
 logger.info({
@@ -81,18 +95,18 @@ This writes:
 {"service":{"name":"service name"},"@timestamp":"2020-05-14T10:56:49.527+01:00","log":{"level":"info"},"event":{"action":"HTTP request"},"message":"GET /pets success","trace":{"id":"1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb"},"http":{"request":{"method":"get"},"response":{"status_code":200}},"url":{"path":"/pets"}}
 ```
 
-Similar to error you can use text logging here as:
+Similar to error you can use string logging here as:
 
 ```
 logger.info('GET /pets success')
 ```
+
 This writes:
 
 ```json
 {"service":{"name":"service name"},"@timestamp":"2020-05-14T10:56:49.527+01:00","log":{"level":"info"}}
 ```
 
-
 It may be that when making a series of logs that write information about a single event, you may want to avoid duplication by creating an event specific logger that includes the context:
 
 ```ruby
@@ -117,6 +131,15 @@ which will print:
 {"service":{"name":"service name"},"@timestamp":"2020-05-14T10:58:30.780+01:00","log":{"level":"error"},"event":{"action":"HTTP request"},"trace":{"id":"126bb6fa-28a2-470f-b013-eefbf9182b2d"},"message":"Error 500 in /pets/buy","http":{"request":{"method":"post","url.path":"/pet/buy"},"response":{"status_code":500}}}
 ```
 
+### Log formatting
+Some third party applications will allow you to optionally specify a [log formatter](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger/Formatter.html).
+Supplying a Twiglet log formatter will format those third party logs so that they are ECS compliant and have the same default parameters as your application's internal logs.
+
+To access the formatter:
+```ruby
+logger.formatter
+```
+
 ## Use of dotted keys (DEPRECATED)
 
 Writing nested json objects could be confusing. This library has a built-in feature to convert dotted keys into nested objects, so if you log like this:

data/example_app.rb

@@ -8,27 +8,27 @@ logger = Twiglet::Logger.new('petshop')
 
 # Start our petshop
 logger.info({
-              event: {
-                action: 'startup'
-              },
-              message: "Ready to go, listening on port #{PORT}",
-              server: {
-                port: PORT
-              }
-            })
+  event: {
+    action: 'startup'
+  },
+  message: "Ready to go, listening on port #{PORT}",
+  server: {
+    port: PORT
+  }
+})
 
 # Use text logging
 logger.info("Ready to go, listening on port #{PORT}")
 #
 # We get a request
 request_logger = logger.with({
-                               event: {
-                                 action: 'HTTP request'
-                               },
-                               trace: {
-                                 id: '126bb6fa-28a2-470f-b013-eefbf9182b2d'
-                               }
-                             })
+  event: {
+    action: 'HTTP request'
+  },
+  trace: {
+    id: '126bb6fa-28a2-470f-b013-eefbf9182b2d'
+  }
+})
 
 # Oh noes!
 db_err = StandardError.new('Connection timed-out')
@@ -37,16 +37,16 @@ request_logger.error({ message: 'DB connection failed.' }, db_err) if db_err
 
 # We return an error to the requester
 request_logger.info({
-                      message: 'Internal Server Error',
-                      http: {
-                        request: {
-                          method: 'get'
-                        },
-                        response: {
-                          status_code: 500
-                        }
-                      }
-                    })
+  message: 'Internal Server Error',
+  http: {
+    request: {
+      method: 'get'
+    },
+    response: {
+      status_code: 500
+    }
+  }
+})
 
 # Logging with an empty message is an anti-pattern and is therefore forbidden
 # Both of the following lines would throw an error

data/lib/hash_extensions.rb

@@ -22,8 +22,8 @@ module HashExtensions
 
   def build_nested_object(key, val)
     key.to_s
-      .split('.')
-      .reverse
-      .reduce(val) { |nested, key_part| Hash[key_part.to_sym, nested] }
+       .split('.')
+       .reverse
+       .reduce(val) { |nested, key_part| Hash[key_part.to_sym, nested] }
   end
 end

data/lib/twiglet/formatter.rb

@@ -1,5 +1,6 @@
 require 'logger'
 require_relative '../hash_extensions'
+require_relative 'message'
 
 module Twiglet
   class Formatter < ::Logger::Formatter
@@ -17,38 +18,12 @@ module Twiglet
 
     def call(severity, _time, _progname, msg)
       level = severity.downcase
-      log(level: level, message: msg)
+      log(level: level, message: Message.new(msg))
     end
 
     private
 
     def log(level:, message:)
-      case message
-      when String
-        log_text(level, message: message)
-      when Hash
-        log_object(level, message: message)
-      else
-        raise('Message must be String or Hash')
-      end
-    end
-
-    def log_text(level, message:)
-      raise('The \'message\' property of log object must not be empty') if message.strip.empty?
-
-      message = { message: message }
-      log_message(level, message: message)
-    end
-
-    def log_object(level, message:)
-      message = message.transform_keys(&:to_sym)
-      message.key?(:message) || raise('Log object must have a \'message\' property')
-      message[:message].strip.empty? && raise('The \'message\' property of log object must not be empty')
-
-      log_message(level, message: message)
-    end
-
-    def log_message(level, message:)
       base_message = {
         ecs: {
           version: '1.5.0'

data/lib/twiglet/logger.rb

@@ -5,6 +5,7 @@ require 'time'
 require 'json'
 require_relative 'formatter'
 require_relative '../hash_extensions'
+require_relative 'message'
 
 module Twiglet
   class Logger < ::Logger
@@ -29,15 +30,16 @@ module Twiglet
       super(output, formatter: formatter, level: level)
     end
 
-    def error(message = {}, error = nil, &block)
+    def error(message = nil, error = nil, &block)
       if error
         error_fields = {
           'error': {
+            'type': error.class,
             'message': error.message
           }
         }
         add_stack_trace(error_fields, error)
-        message.is_a?(Hash) ? message.merge!(error_fields) : error_fields.merge!(message: message)
+        message = Message.new(message).merge(error_fields)
       end
 
       super(message, &block)

data/lib/twiglet/message.rb

@@ -0,0 +1,24 @@
+module Twiglet
+  class Message < Hash
+    def initialize(msg)
+      case msg
+      when String
+        self[:message] = msg
+      when Hash
+        replace(msg.transform_keys!(&:to_sym))
+      end
+
+      validate!
+    end
+
+    private
+
+    def validate!
+      raise 'Message must be initialized with a String or a non-empty Hash' if empty?
+
+      raise 'Log object must have a \'message\' property' unless self[:message]
+
+      raise 'The \'message\' property of the log object must not be empty' if self[:message].strip.empty?
+    end
+  end
+end

data/lib/twiglet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Twiglet
-  VERSION = '2.3.9'
+  VERSION = '3.0.1'
 end

data/test/logger_test.rb

@@ -3,6 +3,16 @@
 require 'minitest/autorun'
 require_relative '../lib/twiglet/logger'
 
+LEVELS = [
+  { method: :debug, level: 'debug' },
+  { method: :info, level: 'info' },
+  { method: :warning, level: 'warn' },
+  { method: :warn, level: 'warn' },
+  { method: :critical, level: 'fatal' },
+  { method: :fatal, level: 'fatal' },
+  { method: :error, level: 'error' }
+].freeze
+
 # rubocop:disable Metrics/BlockLength
 describe Twiglet::Logger do
   before do
@@ -13,16 +23,6 @@ describe Twiglet::Logger do
                                   output: @buffer)
   end
 
-  LEVELS = [
-    { method: :debug, level: 'debug' },
-    { method: :info, level: 'info' },
-    { method: :warning, level: 'warn' },
-    { method: :warn, level: 'warn' },
-    { method: :critical, level: 'fatal' },
-    { method: :fatal, level: 'fatal' },
-    { method: :error, level: 'error' }
-  ].freeze
-
   it 'should throw an error with an empty service name' do
     assert_raises RuntimeError do
       Twiglet::Logger.new('  ')
@@ -105,16 +105,16 @@ describe Twiglet::Logger do
     it "should be able to add properties with '.with'" do
       # Let's add some context to this customer journey
       purchase_logger = @logger.with({
-                                       trace: {id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'},
-                                       customer: {full_name: 'Freda Bloggs'},
-                                       event: {action: 'pet purchase'}
-                                     })
+        trace: {id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'},
+        customer: {full_name: 'Freda Bloggs'},
+        event: {action: 'pet purchase'}
+      })
 
       # do stuff
       purchase_logger.info({
-                             message: 'customer bought a dog',
-                             pet: {name: 'Barker', species: 'dog', breed: 'Bitsa'}
-                           })
+        message: 'customer bought a dog',
+        pet: {name: 'Barker', species: 'dog', breed: 'Bitsa'}
+      })
 
       log = read_json @buffer
 
@@ -149,39 +149,6 @@ describe Twiglet::Logger do
       assert_equal expected_output, @buffer.string
     end
 
-    it 'should be able to convert dotted keys to nested objects' do
-      @logger.debug({
-                      "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
-                      message: 'customer bought a dog',
-                      "pet.name": 'Barker',
-                      "pet.species": 'dog',
-                      "pet.breed": 'Bitsa'
-                    })
-      log = read_json(@buffer)
-
-      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
-      assert_equal 'customer bought a dog', log[:message]
-      assert_equal 'Barker', log[:pet][:name]
-      assert_equal 'dog', log[:pet][:species]
-      assert_equal 'Bitsa', log[:pet][:breed]
-    end
-
-    it 'should be able to mix dotted keys and nested objects' do
-      @logger.debug({
-                      "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
-                      message: 'customer bought a dog',
-                      pet: {name: 'Barker', breed: 'Bitsa'},
-                      "pet.species": 'dog'
-                    })
-      log = read_json(@buffer)
-
-      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
-      assert_equal 'customer bought a dog', log[:message]
-      assert_equal 'Barker', log[:pet][:name]
-      assert_equal 'dog', log[:pet][:species]
-      assert_equal 'Bitsa', log[:pet][:breed]
-    end
-
     it 'should work with mixed string and symbol properties' do
       log = {
         "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'
@@ -205,6 +172,18 @@ describe Twiglet::Logger do
       assert_equal 'Bitsa', actual_log[:pet][:breed]
     end
 
+    LEVELS.each do |attrs|
+      it "should correctly log level when calling #{attrs[:method]}" do
+        @logger.public_send(attrs[:method], {message: 'a log message'})
+        actual_log = read_json(@buffer)
+
+        assert_equal attrs[:level], actual_log[:log][:level]
+        assert_equal 'a log message', actual_log[:message]
+      end
+    end
+  end
+
+  describe 'logging an exception' do
     it 'should log an error with backtrace' do
       begin
         1 / 0
@@ -216,6 +195,7 @@ describe Twiglet::Logger do
 
       assert_equal 'Artificially raised exception', actual_log[:message]
       assert_equal 'divided by 0', actual_log[:error][:message]
+      assert_equal 'ZeroDivisionError', actual_log[:error][:type]
       assert_match 'logger_test.rb', actual_log[:error][:stack_trace].lines.first
     end
 
@@ -226,18 +206,20 @@ describe Twiglet::Logger do
       actual_log = read_json(@buffer)
 
       assert_equal 'Artificially raised exception', actual_log[:message]
+      assert_equal 'StandardError', actual_log[:error][:type]
       assert_equal 'Connection timed-out', actual_log[:error][:message]
       refute actual_log[:error].key?(:stack_trace)
     end
 
-    LEVELS.each do |attrs|
-      it "should correctly log level when calling #{attrs[:method]}" do
-        @logger.public_send(attrs[:method], {message: 'a log message'})
-        actual_log = read_json(@buffer)
+    it 'should log an error with string message' do
+      e = StandardError.new('Unknown error')
+      @logger.error('Artificially raised exception with string message', e)
 
-        assert_equal attrs[:level], actual_log[:log][:level]
-        assert_equal 'a log message', actual_log[:message]
-      end
+      actual_log = read_json(@buffer)
+
+      assert_equal 'Artificially raised exception with string message', actual_log[:message]
+      assert_equal 'StandardError', actual_log[:error][:type]
+      assert_equal 'Unknown error', actual_log[:error][:message]
     end
   end
 
@@ -300,6 +282,41 @@ describe Twiglet::Logger do
     end
   end
 
+  describe 'dotted keys' do
+    it 'should be able to convert dotted keys to nested objects' do
+      @logger.debug({
+        "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
+        message: 'customer bought a dog',
+        "pet.name": 'Barker',
+        "pet.species": 'dog',
+        "pet.breed": 'Bitsa'
+      })
+      log = read_json(@buffer)
+
+      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
+      assert_equal 'customer bought a dog', log[:message]
+      assert_equal 'Barker', log[:pet][:name]
+      assert_equal 'dog', log[:pet][:species]
+      assert_equal 'Bitsa', log[:pet][:breed]
+    end
+
+    it 'should be able to mix dotted keys and nested objects' do
+      @logger.debug({
+        "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
+        message: 'customer bought a dog',
+        pet: {name: 'Barker', breed: 'Bitsa'},
+        "pet.species": 'dog'
+      })
+      log = read_json(@buffer)
+
+      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
+      assert_equal 'customer bought a dog', log[:message]
+      assert_equal 'Barker', log[:pet][:name]
+      assert_equal 'dog', log[:pet][:species]
+      assert_equal 'Bitsa', log[:pet][:breed]
+    end
+  end
+
   describe 'logger level' do
     [
       { expression: :info, level: 1 },

data/test/message_test.rb

@@ -0,0 +1,31 @@
+require 'minitest/autorun'
+require_relative '../lib/twiglet/message'
+
+describe Twiglet::Message do
+  it 'raises if message is empty' do
+    assert_raises RuntimeError do
+      Twiglet::Message.new('   ')
+    end
+  end
+
+  it 'raises if message is not provided' do
+    assert_raises RuntimeError do
+      Twiglet::Message.new(foo: 'bar')
+    end
+  end
+
+  it 'raises on unrecognized inputs' do
+    assert_raises RuntimeError do
+      Twiglet::Message.new(OpenStruct.new(message: 'hello'))
+    end
+  end
+
+  it 'returns a message hash from a string' do
+    assert_equal Twiglet::Message.new('hello, world'), { message: 'hello, world' }
+  end
+
+  it 'returns a message hash with symbolized keys' do
+    input_message = { 'key' => 'value', 'message' => 'hello, world' }
+    assert_equal Twiglet::Message.new(input_message), { key: 'value', message: 'hello, world' }
+  end
+end

data/twiglet.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |gem|
   gem.test_files            = `git ls-files -- {test}/*`.split("\n")
 
   gem.require_paths         = ['lib']
-  gem.required_ruby_version = '>= 2.5'
+  gem.required_ruby_version = '>= 2.6'
 
   gem.license               = 'Copyright SimplyBusiness'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twiglet
 version: !ruby/object:Gem::Version
-  version: 2.3.9
+  version: 3.0.1
 platform: ruby
 authors:
 - Simply Business
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-13 00:00:00.000000000 Z
+date: 2020-12-22 00:00:00.000000000 Z
 dependencies: []
 description: Like a log, only smaller.
 email:
@@ -39,10 +39,12 @@ files:
 - lib/hash_extensions.rb
 - lib/twiglet/formatter.rb
 - lib/twiglet/logger.rb
+- lib/twiglet/message.rb
 - lib/twiglet/version.rb
 - test/formatter_test.rb
 - test/hash_extensions_test.rb
 - test/logger_test.rb
+- test/message_test.rb
 - test/test_coverage.rb
 - twiglet.gemspec
 homepage: https://github.com/simplybusiness/twiglet-ruby
@@ -57,14 +59,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Twiglet