twiglet 1.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8780baf991dc54df9731f5cb2f02cbf1472c4f026d4b5a0604fe332b96f84384
-  data.tar.gz: f059d2eafbb0ac5b5ba74c0f430508ca3966326ec832fb4b56df3efc3b436faf
+  metadata.gz: 356d8c7fec6c41823029cc36bef1cc49bacae6157342b251e9b57f49dcb8151f
+  data.tar.gz: bd58a67b48daa9bf6108dc78098f46ad0204f98ca600c29bacd713f6cb54ea2e
 SHA512:
-  metadata.gz: 1d133f5b631a3a192f1dd7d7f54fecb90c481d593a747ee1ce2b9772eb91c6209af78efb0ec1ebfebe06dabbc76946029edc6a70e6c6493f2351be933ffae7e4
-  data.tar.gz: 343cb5284055f7c5172f7451bbdeb73d1fd9f6c9f53c7341a44d997a63ffbc2f90aecece369e63e27b5955d45aa570f787d83e0c5d83cc52267e7329f9073c02
+  metadata.gz: 4bc443482b93b1bba853fbe67605d9b0673830726cf1ef89e941860bc7f832d1efb5f82d5890197ae279b9edf97bf19edf8dc2d8bf61d56d082d6e641f94a245
+  data.tar.gz: 8d5e178fca01957147dca807aab4117958b18514d568440e72f53cfc8931aad62035a71633646776368f4409d9be48ab8598c66aad4347edd59f79a0bfc281ae

data/.github/CODEOWNERS

@@ -1,4 +1,3 @@
 # Add your project owners info here
 # More information: https://help.github.com/articles/about-codeowners/
 * @simplybusiness/application-tooling
-*

data/.github/workflows/ruby.yml

@@ -28,5 +28,5 @@ jobs:
     - name: Rubocop Check
       run: bundle exec rubocop
     - name: Run all tests
-      run: bundle exec ruby test/*
+      run: bundle exec rake test
       shell: bash

data/.rubocop.yml

@@ -8,7 +8,7 @@ AllCops:
   Documentation:
     Enabled: false
 Metrics/BlockLength:
-  Max: 200
+  Max: 250
 Metrics/AbcSize:
   Max: 20
 Metrics/MethodLength:

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/Gemfile

@@ -4,4 +4,5 @@ source 'https://rubygems.org'
 gem 'simplycop', git: 'https://github.com/simplybusiness/simplycop.git'
 group :development, :test do
   gem 'minitest'
+  gem 'rake'
 end

data/Gemfile.lock

@@ -27,6 +27,7 @@ GEM
       ast (~> 2.4.0)
     rack (2.2.2)
     rainbow (3.0.0)
+    rake (13.0.1)
     rexml (3.2.4)
     rubocop (0.80.1)
       jaro_winkler (~> 1.5.1)
@@ -54,6 +55,7 @@ PLATFORMS
 
 DEPENDENCIES
   minitest
+  rake
   simplycop!
 
 BUNDLED WITH

data/RATIONALE.md

@@ -0,0 +1,90 @@
+# Twiglet
+
+Why Twiglet? Because it's a log, only micro-sized.
+
+This is a machine-readable first, human-readable second, JSON-based logging micro-library suitable for a wide variety of microservice uses.
+
+This logging library is available in a cornucopia of languages:
+* Ruby - here
+* Python - TBC
+* Node.js - [twiglet-node](https://github.com/simplybusiness/twiglet-node/)
+
+## Design considerations
+
+The design goals of this library are:
+
+- Write logs as JSON
+- One line per log entry
+- One JSON object per log entry
+- Each log entry contains a severity[1]
+- Each log entry contains an ISO8601 UTC timestamp
+- Each log entry contains the name of the service that wrote it
+- Each log entry pertains to an 'event'[2]
+- Each log entry either a) propagates an existing trace.id or b) creates a new trace.id as a correlation ID if one does not already exist[3]
+- Stack traces are written inside a single JSON log object rather than sprawling over several lines (TODO:)
+- Personally Identifiable Information. Don't log it.
+
+[1] It turns out that there isn't a single authoritative standard for severity levels, we chose to go with DEBUG, INFO, WARNING, ERROR and CRITICAL as our choices.
+[2] The ‘event’ here merely refers to the action that the customer (or employee, service, or other actor) is currently attempting. It does not refer specifically to Kafka, or CQRS, though that might be the case.
+[3] A correlation ID is a UUIDv4 string
+
+## Elastic Common Schema (ECS)
+https://www.elastic.co/blog/introducing-the-elastic-common-schema
+We have decided to standardise on the Elastic Common Schema for log attribute names. Whilst some attributes are expected for all logs, service owners should feel free to add relevant entries from the ECS schema if they are needed.
+All application specific information is embedded in the `message` attribute JSON payload.
+
+| Attribute name (mandatory) | Description                     |
+| -------------------------- | ------------------------------- |
+| log.level | text, one of DEBUG, INFO, WARNING, ERROR or CRITICAL. |
+| service.name               | text, the name of the service |
+| @timestamp                 | text, ISO8601 UTC |
+| message                    | text, human-readable summary  |
+
+| Attribute name (optional)  | Description                     |
+| -------------------------- | ------------------------------- |
+| error.stack_trace          | Stack trace, as JSON[4]         |
+| tags                       | Array, e.g. ["production"]      |
+| trace.id                   | text, UUIDv4 - a correlation ID |
+| (other examples)           | ...                             |
+
+[4] Helper method to be provided to allow stack trace objects to be represented cleanly as JSON.
+
+Errors should provide appropriate data using the fields from https://www.elastic.co/guide/en/ecs/current/ecs-error.html
+If any other fields are provided in a log then these should be from the ECS schema rather than in a custom format, if at all possible.
+
+## Example log output (prettified)
+```json
+{
+  "log": {
+    "level": "INFO"
+  },
+  "service": {
+    "name": "payments"
+  },
+  "@timestamp": "2020-05-07T11:51:33.976Z",
+  "event": {
+    "action": "customer-payment-accepted"
+  },
+  "trace": {
+    "id": "bf6f5ea3-614b-42f5-8e73-43deea2d1838"
+  },
+  "tags": ["staging"],
+  "message": "Pet cat Spot purchased",
+  "user": {
+    "email": "sleepyfox@gmail.com"
+  },
+  "pet": {
+    "type": "cat",
+    "name": "Spot",
+    "colour": "Ginger Tabby"
+  }
+}
+```
+
+# Code of conduct
+
+Please see the [code of conduct](CODE_OF_CONDUCT.md) for further info.
+
+# License
+
+This work is licensed under the MIT license - see the [LICENSE](LICENSE) file for further details.

data/README.md

@@ -1,7 +1,7 @@
 # Twiglet: Ruby version
 Like a log, only smaller.
 
-This library provides a minimal JSON logging interface suitable for use in (micro)services. See the [README](../README.md) for design rationale and an explantion of the Elastic Common Schema that we are using for log attribute naming.
+This library provides a minimal JSON logging interface suitable for use in (micro)services.  See the [RATIONALE](RATIONALE.md) for design rationale and an explantion of the Elastic Common Schema that we are using for log attribute naming.
 
 ## Installation
 
@@ -15,10 +15,16 @@ Create a new logger like so:
 
 ```ruby
 require 'twiglet/logger'
-logger = Twiglet::Logger.new(conf: { service: 'petshop' })
+logger = Twiglet::Logger.new('service name')
 ```
 
-The logger may be passed in the configuration object an optional `output` attribute which should be an object with a `puts` method - like `$stdout`. The configuration object may also have an optional `now` attribute, which should be a function returning a `Time` object. The defaults should serve for most uses, though you may want to override them for testing as we have done [here](test/logger_test.rb).
+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`.
+
+Lastly, you can provide another optional keyword argument called `now`, which should be a function returning a `Time` string in ISO8601 format.
+
+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:
 
@@ -29,11 +35,29 @@ logger.error({ event: { action: 'startup' }, message: "Emergency! There's an Eme
 This will write to STDOUT a JSON string:
 
 ```json
-{"service":{"name":"petshop"},"@timestamp":"2020-05-14T10:54:59.164+01:00","log":{"level":"error"},"event":{"action":"startup"},"message":"Emergency! There's an Emergency going on"}
+{"service":{"name":"service name"},"@timestamp":"2020-05-14T10:54:59.164+01:00","log":{"level":"error"},"event":{"action":"startup"},"message":"Emergency! There's an Emergency going on"}
 ```
 
 Obviously the timestamp will be different.
 
+Alternatively, if you just want to log some error message in text format
+```ruby
+logger.error( "Emergency! There's an Emergency going on")
+```
+
+This will write to STDOUT a JSON string:
+
+```json
+{"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:
+
+```ruby
+db_err = StandardError.new('Connection timed-out')
+logger.error({ message: 'DB connection failed.' }, db_err)
+```
+
 Add log event specific information simply as attributes in a hash:
 
 ```ruby
@@ -52,9 +76,21 @@ logger.info({
 This writes:
 
 ```json
-{"service":{"name":"petshop"},"@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"}}
+{"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:
+
+```
+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
@@ -76,7 +112,7 @@ request_logger.error({
 which will print:
 
 ```json
-{"service":{"name":"petshop"},"@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}}}
+{"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}}}
 ```
 
 ## Use of dotted keys
@@ -110,7 +146,7 @@ logger.info({
 Both cases would print out exact the same log item:
 
 ```json
-{"service":{"name":"petshop"},"@timestamp":"2020-05-14T10:59:31.183+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"}}
+{"service":{"name":"service name"},"@timestamp":"2020-05-14T10:59:31.183+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"}}
 ```
 
 ## How to contribute
@@ -120,7 +156,7 @@ First: Please read our project [Code of Conduct](../CODE_OF_CONDUCT.md).
 Second: run the tests and make sure your changes don't break anything:
 
 ```bash
-for file in test/*test.rb; do ruby $file; done
+bundle exec rake test
 ```
 
 Then please feel free to submit a PR.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end

data/example_app.rb

@@ -4,7 +4,7 @@ require_relative 'lib/twiglet/logger'
 
 PORT = 8080
 
-logger = Logger.new(conf: { service: 'petshop' })
+logger = Twiglet::Logger.new('petshop')
 
 # Start our petshop
 logger.info({
@@ -17,6 +17,9 @@ logger.info({
               }
             })
 
+# Use text logging
+logger.info("Ready to go, listening on port #{PORT}")
+#
 # We get a request
 request_logger = logger.with({
                                event: {
@@ -45,7 +48,7 @@ request_logger.info({
                       }
                     })
 
-# Logging with a non-empty message is an anti-pattern and is therefore forbidden
+# Logging with an empty message is an anti-pattern and is therefore forbidden
 # Both of the following lines would throw an error
 # request_logger.error({ message: "" })
 # logger.debug({ message: " " })

data/lib/hash_extensions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module HashExtensions
+  def to_nested
+    self unless contains_dotted_key?
+
+    keys.reduce({}) do |nested, key|
+      nested.deep_merge(build_nested_object(key, self[key]))
+    end
+  end
+
+  def deep_merge(hash_to_merge)
+    merger = proc { |_, val1, val2| val1.is_a?(Hash) && val2.is_a?(Hash) ? val1.merge(val2, &merger) : val2 }
+    merge(hash_to_merge, &merger)
+  end
+
+  private
+
+  def contains_dotted_key?
+    keys.any? { |x| x.to_s.include?('.') }
+  end
+
+  def build_nested_object(key, val)
+    key.to_s
+      .split('.')
+      .reverse
+      .reduce(val) { |nested, key_part| Hash[key_part.to_sym, nested] }
+  end
+end

data/lib/twiglet/formatter.rb

@@ -0,0 +1,68 @@
+require 'logger'
+require_relative '../hash_extensions'
+
+module Twiglet
+  class Formatter < ::Logger::Formatter
+    Hash.include HashExtensions
+
+    def initialize(service_name,
+                   default_properties: {},
+                   now: -> { Time.now.utc })
+      @service_name = service_name
+      @now = now
+      @default_properties = default_properties
+
+      super()
+    end
+
+    def call(severity, _time, _progname, msg)
+      level = severity.downcase
+      log(level: level, message: 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 = {
+        "@timestamp": @now.call.iso8601(3),
+        service: {
+          name: @service_name
+        },
+        log: {
+          level: level
+        }
+      }
+
+      base_message
+        .deep_merge(@default_properties.to_nested)
+        .deep_merge(message.to_nested)
+        .to_json
+    end
+  end
+end

data/lib/twiglet/logger.rb

@@ -1,82 +1,60 @@
 # frozen_string_literal: true
 
+require 'logger'
 require 'time'
 require 'json'
-require_relative '../elastic_common_schema'
+require 'twiglet/formatter'
+require_relative '../hash_extensions'
 
 module Twiglet
-  class Logger
-    include ElasticCommonSchema
+  class Logger < ::Logger
+    Hash.include HashExtensions
 
-    def initialize(conf:, scoped_properties: {})
-      @service = conf[:service]
-      @now = conf[:now] || -> { Time.now.utc }
-      @output = conf[:output] || $stdout
+    def initialize(
+      service_name,
+      default_properties: {},
+      now: -> { Time.now.utc },
+      output: $stdout
+    )
+      @service_name = service_name
+      @now = now
+      @output = output
 
-      raise 'configuration must have a service name' \
-        unless @service.is_a?(String) && !@service.strip.empty?
+      raise 'Service name is mandatory' \
+        unless service_name.is_a?(String) && !service_name.strip.empty?
 
-      @scoped_properties = scoped_properties
+      formatter = Twiglet::Formatter.new(service_name, default_properties: default_properties, now: now)
+      super(output, formatter: formatter)
     end
 
-    def debug(message)
-      log(level: 'debug', message: message)
-    end
-
-    def info(message)
-      log(level: 'info', message: message)
-    end
-
-    def warning(message)
-      log(level: 'warning', message: message)
-    end
-
-    def error(message, error = nil)
+    def error(message = {}, error = nil, &block)
       if error
-        message = message.merge({
-                                  error_name: error.message,
-                                  backtrace: error.backtrace
-                                })
+        error_fields = {
+          'error': {
+            'message': error.message
+          }
+        }
+        add_stack_trace(error_fields, error)
+        message.is_a?(Hash) ? message.merge!(error_fields) : error_fields.merge!(message: message)
       end
 
-      log(level: 'error', message: message)
+      super(message, &block)
     end
 
-    def critical(message)
-      log(level: 'critical', message: message)
+    def with(default_properties)
+      Logger.new(@service_name,
+                 default_properties: default_properties,
+                 now: @now,
+                 output: @output)
     end
 
-    def with(scoped_properties)
-      Logger.new(conf: { service: @service,
-                         now: @now,
-                         output: @output },
-                 scoped_properties: scoped_properties)
-    end
+    alias_method :warning, :warn
+    alias_method :critical, :fatal
 
     private
 
-    def log(level:, message:)
-      raise 'Message must be a Hash' unless message.is_a?(Hash)
-
-      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')
-
-      total_message = {
-        service: {
-          name: @service
-        },
-        "@timestamp": @now.call.iso8601(3),
-        log: {
-          level: level
-        }
-      }
-      total_message = total_message.merge(@scoped_properties)
-                                   .merge!(message)
-                                   .then { |log_entry| to_nested(log_entry) }
-
-      @output.puts total_message.to_json
+    def add_stack_trace(hash_to_add_to, error)
+      hash_to_add_to[:error][:stack_trace] = error.backtrace.join("\n") if error.backtrace
     end
   end
 end

data/lib/twiglet/version.rb

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

data/test/formatter_test.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'json'
+require_relative '../lib/twiglet/formatter'
+
+describe Twiglet::Formatter do
+  before do
+    @now = -> { Time.utc(2020, 5, 11, 15, 1, 1) }
+    @formatter = Twiglet::Formatter.new('petshop', now: @now)
+  end
+
+  it 'initializes an instance of a Ruby Logger Formatter' do
+    assert @formatter.is_a?(::Logger::Formatter)
+  end
+
+  it 'returns a formatted log from a string message' do
+    msg = @formatter.call('warn', nil, nil, 'shop is running low on dog food')
+    expected_log = {
+      "@timestamp" => '2020-05-11T15:01:01.000Z',
+      "service" => {
+        "name" => 'petshop'
+      },
+      "log" => {
+        "level" => 'warn'
+      },
+      "message" => 'shop is running low on dog food'
+    }
+    assert_equal JSON.parse(msg), expected_log
+  end
+end

data/test/{elastic_common_schema_test.rb → hash_extensions_test.rb}

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require 'minitest/autorun'
-require_relative '../lib/elastic_common_schema'
+require_relative '../lib/hash_extensions'
 
-describe ElasticCommonSchema do
+describe HashExtensions do
   before do
-    @ecs = Object.new
-    @ecs.extend(ElasticCommonSchema)
+    Hash.include HashExtensions
   end
 
   it 'should retain an object without . in any keys' do
@@ -21,7 +20,7 @@ describe ElasticCommonSchema do
       "@timestamp": '2020-05-09T15:13:20.736Z'
     }
 
-    expected = @ecs.to_nested(actual)
+    expected = actual.to_nested
     assert_equal actual, expected
   end
 
@@ -31,7 +30,7 @@ describe ElasticCommonSchema do
       "log.level": 'error'
     }
 
-    nested = @ecs.to_nested(actual)
+    nested = actual.to_nested
 
     assert_equal 'petshop', nested[:service][:name]
     assert_equal 'error', nested[:log][:level]
@@ -45,7 +44,7 @@ describe ElasticCommonSchema do
       "log.level": 'error'
     }
 
-    nested = @ecs.to_nested(actual)
+    nested = actual.to_nested
 
     assert_equal 'petshop', nested[:service][:name]
     assert_equal 'ps001', nested[:service][:id]
@@ -61,7 +60,7 @@ describe ElasticCommonSchema do
       "http.response.status_code": 200
     }
 
-    nested = @ecs.to_nested(actual)
+    nested = actual.to_nested
 
     assert_equal 'get', nested[:http][:request][:method]
     assert_equal 112, nested[:http][:request][:body][:bytes]
@@ -73,7 +72,7 @@ describe ElasticCommonSchema do
     first = { id: 1, name: 'petshop' }
     second = { level: 'debug', code: 5 }
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
 
     assert_equal 1, actual[:id]
     assert_equal 'petshop', actual[:name]
@@ -85,7 +84,7 @@ describe ElasticCommonSchema do
     first = { id: 1, name: 'petshop', level: 'debug' }
     second = { name: 'petstore', level: 'error', code: 5 }
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
 
     assert_equal 1, actual[:id]
     assert_equal 'petstore', actual[:name]
@@ -97,7 +96,7 @@ describe ElasticCommonSchema do
     first = { service: { name: 'petshop' } }
     second = { service: { id: 'ps001' } }
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
     assert_equal 'petshop', actual[:service][:name]
     assert_equal 'ps001', actual[:service][:id]
   end
@@ -106,7 +105,7 @@ describe ElasticCommonSchema do
     first = { http: { request: { method: 'get', bytes: 124 } } }
     second = { http: { response: { status_code: 200, bytes: 5001 } } }
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
 
     assert_equal 'get', actual[:http][:request][:method]
     assert_equal 124, actual[:http][:request][:bytes]
@@ -118,7 +117,7 @@ describe ElasticCommonSchema do
     first = {}
     second = { id: 1 }
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
 
     assert_equal 1, actual[:id]
   end
@@ -127,7 +126,7 @@ describe ElasticCommonSchema do
     first = { id: 1 }
     second = {}
 
-    actual = @ecs.deep_merge(first, second)
+    actual = first.deep_merge(second)
 
     assert_equal 1, actual[:id]
   end

data/test/logger_test.rb

@@ -7,178 +7,288 @@ describe Twiglet::Logger do
   before do
     @now = -> { Time.utc(2020, 5, 11, 15, 1, 1) }
     @buffer = StringIO.new
-    @logger = Twiglet::Logger.new(conf: {
-                                    service: 'petshop',
-                                    now: @now,
-                                    output: @buffer
-                                  })
+    @logger = Twiglet::Logger.new('petshop',
+                                  now: @now,
+                                  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(conf: { service: '  ' })
+      Twiglet::Logger.new('  ')
     end
   end
 
-  it 'should throw an error with an empty message' do
-    assert_raises RuntimeError do
-      @logger.info('')
+  it 'conforms to the standard Ruby Logger API' do
+    [:debug, :debug?, :info, :info?, :warn, :warn?, :fatal, :fatal?, :error, :error?,
+     :level, :level=, :sev_threshold=].each do |call|
+      assert @logger.respond_to?(call), "Logger does not respond to #{call}"
     end
   end
 
-  it 'should log mandatory attributes' do
-    @logger.error({ message: 'Out of pets exception' })
-    actual_log = read_json(@buffer)
-
-    expected_log = {
-      message: 'Out of pets exception',
-      "@timestamp": '2020-05-11T15:01:01.000Z',
-      service: {
-        name: 'petshop'
-      },
-      log: {
-        level: 'error'
+  describe 'JSON logging' do
+    it 'should throw an error with an empty message' do
+      assert_raises RuntimeError do
+        @logger.info({message: ''})
+      end
+    end
+
+    it 'should log mandatory attributes' do
+      @logger.error({message: 'Out of pets exception'})
+      actual_log = read_json(@buffer)
+
+      expected_log = {
+        message: 'Out of pets exception',
+        "@timestamp": '2020-05-11T15:01:01.000Z',
+        service: {
+          name: 'petshop'
+        },
+        log: {
+          level: 'error'
+        }
       }
-    }
 
-    assert_equal expected_log, actual_log
-  end
+      assert_equal expected_log, actual_log
+    end
 
-  it 'should log the provided message' do
-    @logger.error({ event:
-                      { action: 'exception' },
-                    message: 'Emergency! Emergency!' })
-    log = read_json(@buffer)
+    it 'should log the provided message' do
+      @logger.error({event:
+                       {action: 'exception'},
+                     message: 'Emergency! Emergency!'})
+      log = read_json(@buffer)
 
-    assert_equal 'exception', log[:event][:action]
-    assert_equal 'Emergency! Emergency!', log[:message]
-  end
+      assert_equal 'exception', log[:event][:action]
+      assert_equal 'Emergency! Emergency!', log[:message]
+    end
+
+    it 'should log scoped properties defined at creation' do
+      extra_properties = {
+        trace: {
+          id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'
+        },
+        service: {
+          type: 'shop'
+        },
+        request: {method: 'get'},
+        response: {status_code: 200}
+      }
 
-  it 'should log scoped properties defined at creation' do
-    extra_properties = {
-      trace: {
-        id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'
-      },
-      request: { method: 'get' },
-      response: { status_code: 200 }
-    }
-
-    output = StringIO.new
-    logger = Twiglet::Logger.new(conf: {
-                                   service: 'petshop',
+      output = StringIO.new
+      logger = Twiglet::Logger.new('petshop',
                                    now: @now,
-                                   output: output
-                                 },
-                                 scoped_properties: extra_properties)
+                                   output: output,
+                                   default_properties: extra_properties)
 
-    logger.error({ message: 'GET /cats' })
-    log = read_json output
+      logger.error({message: 'GET /cats'})
+      log = read_json output
 
-    assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
-    assert_equal 'get', log[:request][:method]
-    assert_equal 200, log[:response][:status_code]
-  end
+      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
+      assert_equal 'petshop', log[:service][:name]
+      assert_equal 'shop', log[:service][:type]
+      assert_equal 'get', log[:request][:method]
+      assert_equal 200, log[:response][:status_code]
+    end
 
-  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' }
-                                   })
-
-    # do stuff
-    purchase_logger.info({
-                           message: 'customer bought a dog',
-                           pet: { name: 'Barker', species: 'dog', breed: 'Bitsa' }
-                         })
-
-    log = read_json @buffer
-
-    assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
-    assert_equal 'Freda Bloggs', log[:customer][:full_name]
-    assert_equal 'pet purchase', log[:event][:action]
-    assert_equal 'customer bought a dog', log[:message]
-    assert_equal 'Barker', log[:pet][:name]
-  end
+    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'}
+                                     })
 
-  it "should log 'message' string property" do
-    message = {}
-    message['message'] = 'Guinea pigs arrived'
-    @logger.debug(message)
-    log = read_json(@buffer)
+      # do stuff
+      purchase_logger.info({
+                             message: 'customer bought a dog',
+                             pet: {name: 'Barker', species: 'dog', breed: 'Bitsa'}
+                           })
 
-    assert_equal 'Guinea pigs arrived', log[:message]
-  end
+      log = read_json @buffer
 
-  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
+      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
+      assert_equal 'Freda Bloggs', log[:customer][:full_name]
+      assert_equal 'pet purchase', log[:event][:action]
+      assert_equal 'customer bought a dog', log[:message]
+      assert_equal 'Barker', log[:pet][:name]
+    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 log 'message' string property" do
+      message = {}
+      message['message'] = 'Guinea pigs arrived'
+      @logger.debug(message)
+      log = read_json(@buffer)
+
+      assert_equal 'Guinea pigs arrived', log[:message]
+    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'
+      }
+      event = {}
+      log['event'] = event
+      log['message'] = 'customer bought a dog'
+      pet = {}
+      pet['name'] = 'Barker'
+      pet['breed'] = 'Bitsa'
+      pet[:species] = 'dog'
+      log[:pet] = pet
+
+      @logger.debug(log)
+      actual_log = read_json(@buffer)
 
-  it 'should work with mixed string and symbol properties' do
-    log = {
-      "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'
-    }
-    event = {}
-    log['event'] = event
-    log['message'] = 'customer bought a dog'
-    pet = {}
-    pet['name'] = 'Barker'
-    pet['breed'] = 'Bitsa'
-    pet[:species] = 'dog'
-    log[:pet] = pet
-
-    @logger.debug(log)
-    actual_log = read_json(@buffer)
-
-    assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', actual_log[:trace][:id]
-    assert_equal 'customer bought a dog', actual_log[:message]
-    assert_equal 'Barker', actual_log[:pet][:name]
-    assert_equal 'dog', actual_log[:pet][:species]
-    assert_equal 'Bitsa', actual_log[:pet][:breed]
+      assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', actual_log[:trace][:id]
+      assert_equal 'customer bought a dog', actual_log[:message]
+      assert_equal 'Barker', actual_log[:pet][:name]
+      assert_equal 'dog', actual_log[:pet][:species]
+      assert_equal 'Bitsa', actual_log[:pet][:breed]
+    end
+
+    it 'should log an error with backtrace' do
+      begin
+        1 / 0
+      rescue StandardError => e
+        @logger.error({message: 'Artificially raised exception'}, e)
+      end
+
+      actual_log = read_json(@buffer)
+
+      assert_equal 'Artificially raised exception', actual_log[:message]
+      assert_equal 'divided by 0', actual_log[:error][:message]
+      assert_match 'logger_test.rb', actual_log[:error][:stack_trace].lines.first
+    end
+
+    it 'should log an error without backtrace' do
+      e = StandardError.new('Connection timed-out')
+      @logger.error({message: 'Artificially raised exception'}, e)
+
+      actual_log = read_json(@buffer)
+
+      assert_equal 'Artificially raised exception', actual_log[:message]
+      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)
+
+        assert_equal attrs[:level], actual_log[:log][:level]
+        assert_equal 'a log message', actual_log[:message]
+      end
+    end
   end
 
-  it 'should log an error with backtrace' do
-    begin
-      1 / 0
-    rescue StandardError => e
-      @logger.error({ message: 'Artificially raised exception' }, e)
+  describe 'text logging' do
+    it 'should throw an error with an empty message' do
+      assert_raises RuntimeError do
+        @logger.info('')
+      end
+    end
+
+    it 'should log mandatory attributes' do
+      @logger.error('Out of pets exception')
+      actual_log = read_json(@buffer)
+
+      expected_log = {
+        message: 'Out of pets exception',
+        "@timestamp": '2020-05-11T15:01:01.000Z',
+        service: {
+          name: 'petshop'
+        },
+        log: {
+          level: 'error'
+        }
+      }
+
+      assert_equal expected_log, actual_log
+    end
+
+    it 'should log the provided message' do
+      @logger.error('Emergency! Emergency!')
+      log = read_json(@buffer)
+
+      assert_equal 'Emergency! Emergency!', log[:message]
+    end
+
+    LEVELS.each do |attrs|
+      it "should correctly log level when calling #{attrs[:method]}" do
+        @logger.public_send(attrs[:method], '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
 
-    actual_log = read_json(@buffer)
+  describe 'logging with a block' do
+    LEVELS.each do |attrs|
+      it "should correctly log the block when calling #{attrs[:method]}" do
+        block = proc { 'a block log message' }
+        @logger.public_send(attrs[:method], &block)
+        actual_log = read_json(@buffer)
 
-    assert_equal 'Artificially raised exception', actual_log[:message]
-    assert_equal 'divided by 0', actual_log[:error_name]
-    assert_match 'logger_test.rb', actual_log[:backtrace].first
+        assert_equal attrs[:level], actual_log[:log][:level]
+        assert_equal 'a block log message', actual_log[:message]
+      end
+    end
+  end
+
+  describe 'logger level' do
+    [
+      { expression: :info, level: 1 },
+      { expression: 'warn', level: 2 },
+      { expression: Logger::DEBUG, level: 0 }
+    ].each do |args|
+      it "sets the severity threshold to level #{args[:level]}" do
+        @logger.level = args[:expression]
+        assert_equal args[:level], @logger.level
+      end
+    end
   end
 
   private

data/twiglet.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |gem|
   gem.version               = Twiglet::VERSION
   gem.authors               = ['Simply Business']
   gem.email                 = ['tech@simplybusiness.co.uk']
-  gem.homepage              = 'https://github.com/simplybusiness/twiglet'
+  gem.homepage              = 'https://github.com/simplybusiness/twiglet-ruby'
 
   gem.summary               = 'Twiglet'
   gem.description           = 'Like a log, only smaller.'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twiglet
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Simply Business
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-01 00:00:00.000000000 Z
+date: 2020-06-22 00:00:00.000000000 Z
 dependencies: []
 description: Like a log, only smaller.
 email:
@@ -21,19 +21,24 @@ files:
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- ".ruby-version"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- RATIONALE.md
 - README.md
+- Rakefile
 - example_app.rb
-- lib/elastic_common_schema.rb
+- lib/hash_extensions.rb
+- lib/twiglet/formatter.rb
 - lib/twiglet/logger.rb
 - lib/twiglet/version.rb
-- test/elastic_common_schema_test.rb
+- test/formatter_test.rb
+- test/hash_extensions_test.rb
 - test/logger_test.rb
 - twiglet.gemspec
-homepage: https://github.com/simplybusiness/twiglet
+homepage: https://github.com/simplybusiness/twiglet-ruby
 licenses:
 - Copyright SimplyBusiness
 metadata: {}
@@ -52,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Twiglet

data/lib/elastic_common_schema.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module ElasticCommonSchema
-  def to_nested(log)
-    log unless contains_dotted_key?(log)
-
-    log.keys.reduce({}) do |nested, key|
-      deep_merge(nested, build_nested_object(key, log[key]))
-    end
-  end
-
-  def deep_merge(hash1, hash2)
-    merger = proc { |_, val1, val2| val1.is_a?(Hash) && val2.is_a?(Hash) ? val1.merge(val2, &merger) : val2 }
-    hash1.merge(hash2, &merger)
-  end
-
-  private
-
-  def contains_dotted_key?(log)
-    log.keys.any? { |x| x.to_s.include?('.') }
-  end
-
-  def build_nested_object(key, val)
-    key.to_s
-       .split('.')
-       .reverse
-       .reduce(val) { |nested, key_part| Hash[key_part.to_sym, nested] }
-  end
-end