twiglet 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8780baf991dc54df9731f5cb2f02cbf1472c4f026d4b5a0604fe332b96f84384
+  data.tar.gz: f059d2eafbb0ac5b5ba74c0f430508ca3966326ec832fb4b56df3efc3b436faf
+SHA512:
+  metadata.gz: 1d133f5b631a3a192f1dd7d7f54fecb90c481d593a747ee1ce2b9772eb91c6209af78efb0ec1ebfebe06dabbc76946029edc6a70e6c6493f2351be933ffae7e4
+  data.tar.gz: 343cb5284055f7c5172f7451bbdeb73d1fd9f6c9f53c7341a44d997a63ffbc2f90aecece369e63e27b5955d45aa570f787d83e0c5d83cc52267e7329f9073c02

data/.github/CODEOWNERS

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

data/.github/workflows/ruby.yml

@@ -0,0 +1,32 @@
+name: Ruby CI
+
+on:
+  push:
+    branches:
+      - '*'         # matches every branch
+      - '*/*'       # matches every branch containing a single '/'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./
+
+    strategy:
+      matrix:
+        ruby-version: [2.6, 2.7]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Rubocop Check
+      run: bundle exec rubocop
+    - name: Run all tests
+      run: bundle exec ruby test/*
+      shell: bash

data/.gitignore

@@ -0,0 +1,56 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.rubocop.yml

@@ -0,0 +1,15 @@
+inherit_gem:
+  simplycop: .simplycop.yml
+
+AllCops:
+  TargetRubyVersion: 2.6
+  Rails:
+    Enabled: false
+  Documentation:
+    Enabled: false
+Metrics/BlockLength:
+  Max: 200
+Metrics/AbcSize:
+  Max: 20
+Metrics/MethodLength:
+  Max: 25

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at tech@simplybusiness.co.uk. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,60 @@
+GIT
+  remote: https://github.com/simplybusiness/simplycop.git
+  revision: 02b417277e3ff9eeab34d6b7c30a95a17d876731
+  specs:
+    simplycop (0.5.4)
+      rubocop (~> 0.80.0)
+      rubocop-rails
+      rubocop-rspec
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.0.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    ast (2.4.0)
+    concurrent-ruby (1.1.6)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    minitest (5.14.0)
+    parallel (1.19.1)
+    parser (2.7.1.3)
+      ast (~> 2.4.0)
+    rack (2.2.2)
+    rainbow (3.0.0)
+    rexml (3.2.4)
+    rubocop (0.80.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    rubocop-rails (2.5.2)
+      activesupport
+      rack (>= 1.1)
+      rubocop (>= 0.72.0)
+    rubocop-rspec (1.39.0)
+      rubocop (>= 0.68.1)
+    ruby-progressbar (1.10.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.6.1)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest
+  simplycop!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Simply Business
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# 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.
+
+## Installation
+
+```bash
+gem install twiglet
+```
+
+## How to use
+
+Create a new logger like so:
+
+```ruby
+require 'twiglet/logger'
+logger = Twiglet::Logger.new(conf: { service: 'petshop' })
+```
+
+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).
+
+To use, simply invoke like most other loggers:
+
+```ruby
+logger.error({ event: { action: 'startup' }, message: "Emergency! There's an Emergency going on" })
+```
+
+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"}
+```
+
+Obviously the timestamp will be different.
+
+Add log event specific information simply as attributes in a hash:
+
+```ruby
+logger.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' }
+})
+```
+
+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"}}
+```
+
+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
+request_log = logger.with({ event: { action: 'HTTP request'}, trace: { id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb' }})
+```
+
+This can be used like any other Logger instance:
+
+```ruby
+request_logger.error({
+    message: 'Error 500 in /pets/buy',
+    http: {
+        request: { method: 'post', 'url.path': '/pet/buy' },
+        response: { status_code: 500 }
+    }
+})
+```
+
+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}}}
+```
+
+## Use of dotted keys
+
+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:
+
+```ruby
+logger.info({
+    'event.action': 'HTTP request',
+    message: 'GET /pets success',
+    'trace.id': '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
+    'http.request.method': 'get',
+    'http.response.status_code': 200,
+    'url.path': '/pets'
+})
+```
+
+or mix between dotted keys and nested objects:
+
+```ruby
+logger.info({
+    'event.action': 'HTTP request',
+    message: 'GET /pets success',
+    trace: { id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb' },
+    'http.request.method': 'get',
+    'http.response.status_code': 200,
+    url: { path: '/pets' }
+})
+```
+
+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"}}
+```
+
+## How to contribute
+
+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
+```
+
+Then please feel free to submit a PR.

data/example_app.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'lib/twiglet/logger'
+
+PORT = 8080
+
+logger = Logger.new(conf: { service: 'petshop' })
+
+# Start our petshop
+logger.info({
+              event: {
+                action: 'startup'
+              },
+              message: "Ready to go, listening on port #{PORT}",
+              server: {
+                port: PORT
+              }
+            })
+
+# We get a request
+request_logger = logger.with({
+                               event: {
+                                 action: 'HTTP request'
+                               },
+                               trace: {
+                                 id: '126bb6fa-28a2-470f-b013-eefbf9182b2d'
+                               }
+                             })
+
+# Oh noes!
+db_err = StandardError.new('Connection timed-out')
+
+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
+                        }
+                      }
+                    })
+
+# Logging with a non-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/elastic_common_schema.rb

@@ -0,0 +1,29 @@
+# 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

data/lib/twiglet/logger.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'json'
+require_relative '../elastic_common_schema'
+
+module Twiglet
+  class Logger
+    include ElasticCommonSchema
+
+    def initialize(conf:, scoped_properties: {})
+      @service = conf[:service]
+      @now = conf[:now] || -> { Time.now.utc }
+      @output = conf[:output] || $stdout
+
+      raise 'configuration must have a service name' \
+        unless @service.is_a?(String) && !@service.strip.empty?
+
+      @scoped_properties = scoped_properties
+    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)
+      if error
+        message = message.merge({
+                                  error_name: error.message,
+                                  backtrace: error.backtrace
+                                })
+      end
+
+      log(level: 'error', message: message)
+    end
+
+    def critical(message)
+      log(level: 'critical', message: message)
+    end
+
+    def with(scoped_properties)
+      Logger.new(conf: { service: @service,
+                         now: @now,
+                         output: @output },
+                 scoped_properties: scoped_properties)
+    end
+
+    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
+    end
+  end
+end

data/lib/twiglet/version.rb

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

data/test/elastic_common_schema_test.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../lib/elastic_common_schema'
+
+describe ElasticCommonSchema do
+  before do
+    @ecs = Object.new
+    @ecs.extend(ElasticCommonSchema)
+  end
+
+  it 'should retain an object without . in any keys' do
+    actual = {
+      message: 'Out of pets exception',
+      service: {
+        name: 'petshop'
+      },
+      log: {
+        level: 'error'
+      },
+      "@timestamp": '2020-05-09T15:13:20.736Z'
+    }
+
+    expected = @ecs.to_nested(actual)
+    assert_equal actual, expected
+  end
+
+  it 'should convert keys with . into nested objects' do
+    actual = {
+      "service.name": 'petshop',
+      "log.level": 'error'
+    }
+
+    nested = @ecs.to_nested(actual)
+
+    assert_equal 'petshop', nested[:service][:name]
+    assert_equal 'error', nested[:log][:level]
+  end
+
+  it 'should group nested objects' do
+    actual = {
+      "service.name": 'petshop',
+      "service.id": 'ps001',
+      "service.version": '0.9.1',
+      "log.level": 'error'
+    }
+
+    nested = @ecs.to_nested(actual)
+
+    assert_equal 'petshop', nested[:service][:name]
+    assert_equal 'ps001', nested[:service][:id]
+    assert_equal '0.9.1', nested[:service][:version]
+    assert_equal 'error', nested[:log][:level]
+  end
+
+  it 'should cope with more than two levels' do
+    actual = {
+      "http.request.method": 'get',
+      "http.request.body.bytes": 112,
+      "http.response.bytes": 1564,
+      "http.response.status_code": 200
+    }
+
+    nested = @ecs.to_nested(actual)
+
+    assert_equal 'get', nested[:http][:request][:method]
+    assert_equal 112, nested[:http][:request][:body][:bytes]
+    assert_equal 1564, nested[:http][:response][:bytes]
+    assert_equal 200, nested[:http][:response][:status_code]
+  end
+
+  it '#deep_merge() should work with two hashes without common keys' do
+    first = { id: 1, name: 'petshop' }
+    second = { level: 'debug', code: 5 }
+
+    actual = @ecs.deep_merge(first, second)
+
+    assert_equal 1, actual[:id]
+    assert_equal 'petshop', actual[:name]
+    assert_equal 'debug', actual[:level]
+    assert_equal 5, actual[:code]
+  end
+
+  it '#deep_merge() should use the second value for shared keys' do
+    first = { id: 1, name: 'petshop', level: 'debug' }
+    second = { name: 'petstore', level: 'error', code: 5 }
+
+    actual = @ecs.deep_merge(first, second)
+
+    assert_equal 1, actual[:id]
+    assert_equal 'petstore', actual[:name]
+    assert_equal 'error', actual[:level]
+    assert_equal 5, actual[:code]
+  end
+
+  it '#deep_merge() should merge two sub-keys' do
+    first = { service: { name: 'petshop' } }
+    second = { service: { id: 'ps001' } }
+
+    actual = @ecs.deep_merge(first, second)
+    assert_equal 'petshop', actual[:service][:name]
+    assert_equal 'ps001', actual[:service][:id]
+  end
+
+  it '#deep_merge() should merge sub-keys in more than 2 levels' do
+    first = { http: { request: { method: 'get', bytes: 124 } } }
+    second = { http: { response: { status_code: 200, bytes: 5001 } } }
+
+    actual = @ecs.deep_merge(first, second)
+
+    assert_equal 'get', actual[:http][:request][:method]
+    assert_equal 124, actual[:http][:request][:bytes]
+    assert_equal 200, actual[:http][:response][:status_code]
+    assert_equal 5001, actual[:http][:response][:bytes]
+  end
+
+  it '#deep_merge() should work when the first key is empty' do
+    first = {}
+    second = { id: 1 }
+
+    actual = @ecs.deep_merge(first, second)
+
+    assert_equal 1, actual[:id]
+  end
+
+  it '#deep_merge() should work when the second key is empty' do
+    first = { id: 1 }
+    second = {}
+
+    actual = @ecs.deep_merge(first, second)
+
+    assert_equal 1, actual[:id]
+  end
+end

data/test/logger_test.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../lib/twiglet/logger'
+
+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
+                                  })
+  end
+
+  it 'should throw an error with an empty service name' do
+    assert_raises RuntimeError do
+      Twiglet::Logger.new(conf: { service: '  ' })
+    end
+  end
+
+  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({ 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
+
+  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
+
+  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',
+                                   now: @now,
+                                   output: output
+                                 },
+                                 scoped_properties: extra_properties)
+
+    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
+
+  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 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)
+
+    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_name]
+    assert_match 'logger_test.rb', actual_log[:backtrace].first
+  end
+
+  private
+
+  def read_json(buffer)
+    buffer.rewind
+    JSON.parse(buffer.read, symbolize_names: true)
+  end
+end

data/twiglet.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require File.expand_path('lib/twiglet/version', __dir__)
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+
+Gem::Specification.new do |gem|
+  gem.name                  = 'twiglet'
+  gem.version               = Twiglet::VERSION
+  gem.authors               = ['Simply Business']
+  gem.email                 = ['tech@simplybusiness.co.uk']
+  gem.homepage              = 'https://github.com/simplybusiness/twiglet'
+
+  gem.summary               = 'Twiglet'
+  gem.description           = 'Like a log, only smaller.'
+
+  gem.files                 = `git ls-files`.split("\n")
+  gem.test_files            = `git ls-files -- {test}/*`.split("\n")
+
+  gem.require_paths         = ['lib']
+  gem.required_ruby_version = '>= 2.6'
+
+  gem.license               = 'Copyright SimplyBusiness'
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: twiglet
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Simply Business
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-01 00:00:00.000000000 Z
+dependencies: []
+description: Like a log, only smaller.
+email:
+- tech@simplybusiness.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/CODEOWNERS"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- example_app.rb
+- lib/elastic_common_schema.rb
+- lib/twiglet/logger.rb
+- lib/twiglet/version.rb
+- test/elastic_common_schema_test.rb
+- test/logger_test.rb
+- twiglet.gemspec
+homepage: https://github.com/simplybusiness/twiglet
+licenses:
+- Copyright SimplyBusiness
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Twiglet
+test_files: []