green_log 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3c301ce67ee757ddf2093b93fc973ff46ad005f2ea7e8da3e693ca01a6c7444
+  data.tar.gz: 0ec5551c9554ec465acfd815f4a95514f8dbf48529427a0187d51b02657e2671
+SHA512:
+  metadata.gz: 889da34f831f8d7b95bb79343b6905f88d0ffde04a308773ec6775ed70f2b7ffd8668f7eb9c0c8b6ec5fc4d7a2ffbbc6ff59ccecbbdac34fec6ac598c35bba0b
+  data.tar.gz: f72a8e18d791b8d57a6a413d40c870c7dfb3b34414dc6e00862972acf927ef34d3520676cc973f2fdb7c29f0d92b9d15a69fed230d257b8f19c069b9f8523e7e

data/README.md

@@ -0,0 +1,194 @@
+# GreenLog
+
+![](https://github.com/greensync/green_log/workflows/CI/badge.svg)
+
+GreenLog is a logging library for Ruby applications.  It:
+
+- focuses on [structured logging](https://www.thoughtworks.com/radar/techniques/structured-logging) - treating log entries as data
+- is optimised for use in modern "cloud-native" applications
+- can be used in place of Ruby's stdlib `Logger`
+
+## Design approach
+
+GreenLog:
+
+- [avoids global state](doc/adr/0002-avoid-global-configuration.md)
+- avoids mutable objects
+- explicitly [decouples log entry generation and handling](doc/adr/0003-decouple-generation-and-handling.md)
+- uses [an approach similar to Rack middleware](doc/adr/0004-use-stacked-handlers-to-solve-many-problems.md) for flexible log processing
+- uses [lock-free IO](doc/adr/0006-use-lock-free-io.md) for performance
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'green_log'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+### tl;dr
+
+```ruby
+require 'green_log'
+
+logger = GreenLog::Logger.build
+
+logger.info("Stuff happened")
+# outputs: I -- Stuff happened
+```
+
+### Basic logging
+
+GreenLog implements all the expected logging shortcuts:
+
+```ruby
+logger.debug("Nitty gritty detail")
+# outputs: D -- Nitty gritty detail
+logger.info("Huh, interesting.")
+# outputs: I -- Huh, interesting.
+logger.warn("Careful now.")
+# outputs: W -- Careful now.
+logger.error("Oh, that's really not good!")
+# outputs: E -- Oh, that's really not good!
+logger.fatal("Byeeee ...")
+# outputs: F -- Byeeee ...
+```
+
+### Adding context
+
+`Logger#with_context` adds detail about the _source_ of log messages.
+
+```ruby
+logger = GreenLog::Logger.build.with_context(pid: Process.pid, thread: Thread.current.object_id)
+logger.info("Hello")
+# outputs: I [pid=13545 thread=70260187418160] -- Hello
+```
+
+It can be chained to inject additional context:
+
+```ruby
+logger.with_context(request: 16273).info("Handled")
+# outputs: I [pid=13545 thread=70260187418160 request=16273] -- Handled
+```
+
+Context can also be calculated dynamically, using a block:
+
+```ruby
+logger = GreenLog::Logger.build.with_context do
+  {
+    request_id: Thread.current[:request_id]
+  }
+end
+# outputs: I [pid=13545 thread=70260187418160 request=16273] -- Handled
+```
+
+### Including data and exceptions
+
+A Hash of data can be included along with the log message:
+
+```ruby
+logger = GreenLog::Logger.build
+logger.info("New widget", id: widget.id)
+# outputs: I -- New widget [id=12345]
+```
+
+And/or, you can attach an exception:
+
+```ruby
+begin
+  Integer("abc")
+rescue => e
+  logger.error("parse error", e)
+end
+# outputs: E -- parse error
+#            ! ArgumentError: invalid value for Integer(): "abc"
+#              (irb):50:in `Integer'
+#              (irb):50:in `irb_binding'
+#              ...
+```
+
+### Alternate output format
+
+By default GreenLog logs with a human-readable format; specify an alternate `format`
+class if you want a different serialisation format. It comes bundled with a JSON writer, e.g.
+
+```ruby
+logger = GreenLog::Logger.build(format: GreenLog::JsonWriter)
+# OR
+logger = GreenLog::Logger.build(format: "json")
+
+logger.info("Structured!", foo: "bar")
+```
+
+outputs
+
+```json
+{"severity":"INFO","message":"Structured!","data":{"foo":"bar"},"context":{}}
+```
+
+### Alternate output destination
+
+Logs go to STDOUT by default; specify `dest` to override, e.g.
+
+```ruby
+logger = GreenLog::Logger.build(dest: STDERR)
+```
+
+### Filtering by log severity
+
+By default all log entries will result in output. You can add a severity-threshold to avoid emitting debug-level log messages, e.g.
+
+```ruby
+logger = GreenLog::Logger.build(severity_threshold: :INFO)
+# OR
+logger = GreenLog::Logger.build.with_severity_threshold(:INFO)
+
+log.debug("Whatever") # ignored
+```
+
+### Block form
+
+Rather than passing arguments, you can provide a block to generate log messages:
+
+```ruby
+logger.info do
+  "generated message"
+end
+# outputs: I -- generated message
+```
+
+The block may be ignored, if a severity-threshold is in effect:
+
+```ruby
+logger = GreenLog::Logger.build(severity_threshold: :INFO)
+
+log.debug do
+  # not evaluated
+end
+```
+
+### Compatibility with stdlib Logger
+
+GreenLog includes a backward-compatibile adapter for code written to use Ruby's built-in [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html):
+
+```ruby
+require 'green_log/classic_logger'
+
+legacy_logger = logger.to_classic_logger
+legacy_logger.warn("Old skool")
+# outputs: W -- Old skool
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/greensync/green_log.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

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

data/bin/setup

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

data/doc/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2019-12-18
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

data/doc/adr/0002-avoid-global-configuration.md

@@ -0,0 +1,35 @@
+# 2. Avoid global configuration
+
+Date: 2019-12-18
+
+## Status
+
+Accepted
+
+## Context
+
+Applications require a way to configure their logging, e.g. what should be logged, where should logs be sent, and how should they be formatted.
+
+Some Ruby logging libraries involve global configuration, and other state, e.g.
+
+```ruby
+require 'some_logger'
+SomeLogger.default_level = :trace
+SomeLogger.add_appender(file_name: 'development.log', formatter: :color)
+SomeLogger["MyClass"].info("Stuff happened")
+```
+
+but global state can have unintended consequences, and make testing difficult.
+
+## Decision
+
+GreenLog will avoid global configuration. `GreenLog::Logger` instances should be created and configured explicitly, and injected as dependencies where needed.
+
+## Consequences
+
+- Testing of logging logic should be straightforward.
+- Libraries and applications can make their own logging arrangements.
+
+BUT
+
+- Applications will need to determine their own conventions for configuration of logging.

data/doc/adr/0003-decouple-generation-and-handling.md

@@ -0,0 +1,30 @@
+# 3. Decouple log generation from handling
+
+Date: 2019-12-19
+
+## Status
+
+Accepted
+
+## Context
+
+We want the logging API used by applications to be consistent, while allowing for logs to be filed, forwarded, filtered and formatted in a variety of ways.
+
+## Decision
+
+De-couple generation of log message/entries from how they are handled.
+
+* A `logger` object provides an API that can be used to generate log entries.
+* Log "entries" are strongly typed structures.
+* Log entry "handlers" provide a simple, consistent interface.
+
+```mermaid
+sequenceDiagram
+
+App ->> Logger:       info("Message")
+Logger ->> Handler:   <<(entry)
+```
+
+## Consequences
+
+* We can plug in different "handlers" relatively easily.

data/doc/adr/0004-use-stacked-handlers-to-solve-many-problems.md

@@ -0,0 +1,51 @@
+# 4. Use stacked handlers to solve many problems
+
+Date: 2019-12-19
+
+## Status
+
+Accepted
+
+## Context
+
+GreenLog "loggers" push generated log "entries" to log "handlers".
+
+Formatting/filing/forwarding logs in different ways is achieved by using a different handler.
+
+However, there are some cross-cutting concerns that might apply regardless of the way log entries are formatted, stored or forwarded. For example:
+
+- we may want to inject context into log entries (e.g. process id, thread name, trace id)
+- we may want to "tee" log entries to multiple destinations
+- we may want to buffer log entries in-memory and output/forward them asyncronously
+
+## Decision
+
+We will favour "stacking" handlers to solve such problems. That is:
+
+* the source 'logger' will push entries to an intermediate handler
+* the intermediate handler can
+  - transform the input entries as required
+  - forward them to one or more "downstream" handlers, as required
+* handler "stacks" of arbitrary depth can be created
+
+```mermaid
+sequenceDiagram
+
+App ->> Logger:         info("Message")
+Logger ->> Middleware:  <<(entry)
+Middleware ->> Writer:  <<(entry)
+```
+
+This approach is based on [Rack](https://github.com/rack/rack)'s "middleware" concept.
+
+### Alternatives considered
+
+I considered supporting "filters", which could take an `Entry` and return a transformed `Entry`, but that would not allow for:
+
+* "tee-ing" the log to multiple destinations
+* buffering or filtering of logs
+
+## Consequences
+
+* There will be many and various "middleware" handlers.
+* Handler stacks could get deep.

data/doc/adr/0005-restrict-data-types-allowable-in-log-entries.md

@@ -0,0 +1,27 @@
+# 5. Restrict data-types allowable in log entries
+
+Date: 2019-12-21
+
+## Status
+
+Accepted
+
+## Context
+
+GreenLog allows data to be attached to log entries, either as "context", or "data" associated with the logged event.
+
+Log entries may be consumed by a variety of "handlers", which
+
+## Decision
+
+To make the job of "handlers" easier, GreenLog will restrict the type of value usable as log "context" or "data" to:
+
+- `true`/`false`
+- `Numeric`
+- `String`
+- `Time`
+- `Hash` (with `String` or `Symbol` keys)
+
+## Consequences
+
+- Other data must be converted to one of these types before inclusion in log entries.

data/doc/adr/0006-use-lock-free-io.md

@@ -0,0 +1,29 @@
+# 6. Use lock-free IO
+
+Date: 2019-12-24
+
+## Status
+
+Accepted
+
+## Context
+
+We want to be able to write log entries (to file, or STDOUT), without them being interleaved.
+
+But also, we want logging to perform well.
+
+## Decision
+
+_Unlike_ the Ruby standard `Logger`, GreenLog will use a [lock-free logging](https://www.jstorimer.com/blogs/workingwithcode/7982047-is-lock-free-logging-safe) approach. That is, we will:
+
+- avoid using of mutexes to serialise output
+- perform atomic writes to `IO` streams (using `<<`)
+
+## Consequences
+
+- IO code is simple.
+- Performance should be good.
+
+But:
+
+- We risk interleaving of log entries if the size of the (serialized) entries gets over `PIPE_BUF_MAX` (1Mb on Linux).

data/examples/multi-threaded

@@ -0,0 +1,21 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+require "green_log/logger"
+require "green_log/simple_writer"
+
+logger = GreenLog::Logger.new(GreenLog::SimpleWriter.new(STDOUT))
+
+threads = ("A".."Z").map do |label|
+  Thread.new do
+    1.upto(100) do
+      delay = rand / 10
+      logger.info("Hi", thread: label, delay: delay)
+      sleep(delay)
+    end
+  end
+end
+
+threads.each(&:join)