logfmt-tagged_logger 0.1.0.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a95519748d42cf63a14c82f759cc4e3d7b1e486d62de1dc7f0ac32b004c09679
+  data.tar.gz: 6839988ba2c4dbbc70cdf0247a308b696abeca96ffa19976d58f074fbd8d1cbb
+SHA512:
+  metadata.gz: d69856eab735eb407db8002c079301eb866791a368bffeedec4590d66b998818ace0b97d40b25bfa7477d022056c2cf0463a09e39a8c7ba96253a0d6e8ac3124
+  data.tar.gz: 876ef90a4c8a1bad3b54d9e21e5c89bdcf425c44735ad193d0b671f8050d179707b43bd553628aebe75a9555dbc029f28b6c488b084506193778812583319e85

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## \[Unreleased\]
+
+## [0.0.10] 2022-04-30
+### Changed
+  - Autoload the `Logfmt::Parser` when it's used, in preparation for the coming `Logfmt::Logger` and friends.
+    Alternatively you can eager-load it into memory: `require "logfmt/parser"`.
+
+### Added
+  - This CHANGELOG file.

data/README.md

@@ -0,0 +1,154 @@
+# Logfmt
+
+Write and parse structured log lines in the [logfmt style][logfmt-blog].
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem "logfmt"
+```
+
+And then install:
+
+```bash
+$ bundle
+```
+
+Or install it yourself:
+
+```bash
+$ gem install logfmt
+```
+
+### Versioning
+
+This project adheres to [Semantic Versioning][semver].
+
+## Usage
+
+`Logfmt` is composed to two parts: writing structured log lines in the `logfmt` style, and parsing `logfmt`-style log lines.
+
+While writing and parsing `logfmt` are related, we've found that it's common to only need to do one or there other in a single application.
+To support that usage, `Logfmt` leverages Ruby's `autoload` to lazily load the `Logfmt::Parser` or `Logfmt::Logger` (and associated code) into memory.
+In the general case that looks something like:
+
+```ruby
+require "logfmt"
+
+Logfmt # This constant was already loaded, but neither Logfmt::Parser
+       # nor Logfmt::Logger constants are loaded. Yet.
+
+Logfmt.parse("…")
+  # OR
+Logfmt::Parser.parse("…")
+
+# Either of the above will load the Logfmt::Parser constant.
+# Similarly you can autoload the Logfmt::Logger via
+
+Logfmt::Logger.new
+```
+
+If you want to eagerly load the logger or parser, you can do that by requiring them directly
+
+### Parsing log lines
+
+```ruby
+require "logfmt/parser"
+
+Logfmt::Parser.parse('foo=bar a=14 baz="hello kitty" cool%story=bro f %^asdf')
+  #=> {"foo"=>"bar", "a"=>14, "baz"=>"hello kitty", "cool%story"=>"bro", "f"=>true, "%^asdf"=>true}
+```
+
+### Writing log lines
+
+The `Logfmt::Logger` is built on the stdlib `::Logger` and adheres to its API.
+The primary difference is that `Logfmt::Logger` defaults to a `logfmt`-style formatter.
+Specifically, a `Logfmt::Logger::KeyValueFormatter`, which results in log lines something like this:
+
+```ruby
+require "logfmt/logger"
+
+logger = Logfmt::Logger.new($stdout)
+
+logger.info(foo: "bar", a: 14, "baz" => "hello kitty", "cool%story" => "bro", f: true, "%^asdf" => true)
+  #=> time=2022-04-20T23:30:54.647403Z severity=INFO  foo=bar a=14 baz="hello kitty" cool%story=bro f %^asdf
+
+logger.debug("MADE IT HERE!")
+  #=> time=2022-04-20T23:33:44.912595Z severity=DEBUG msg="MADE IT HERE!"
+```
+
+#### Tagged log lines
+
+The `logfmt-tagged_logger` gem adds support for Rails-style [tagged logging][tagged-logger].
+This gem adds a `Logfmt::TaggedLogger` which is built on `ActiveSupport::TaggedLogger`, but emits the tags in logfmt-style, as key/value pairs.
+For example
+
+```ruby
+logger = Logfmt::TaggedLogger.new($stdout)
+
+logger.tagged(source: "api") do
+  logger.info(foo: "bar")
+end
+
+#=> time=2022-04-20T23:33:44.912595Z severity=info source=api foo=bar"
+```
+
+You can also pass "bare" tags and they'll be collected and emitted under the `tags` key.
+
+```ruby
+logger = Logfmt::TaggedLogger.new($stdout)
+
+logger.tagged("API", "1.2.3.4") do
+  logger.info(foo: "bar")
+end
+
+#=> time=2022-04-20T23:33:44.912595Z severity=info tags="[API] [1.2.3.4]" foo=bar"
+```
+
+It's likely more helpful and useful to use meaningful key/values for your tags, rather than bare tags.
+
+#### Expected key/value transformations
+
+When writing a log line with the `Logfmt::Logger::KeyValueFormatter` the keys and/or values will be transformed thusly:
+
+* "Bare messages" (those with no key given when invoking the logger) will be wrapped in the `msg` key.
+
+    ```ruby
+    logger.info("here")
+      #=> time=2022-04-20T23:33:49.912997Z severity=INFO  msg=here
+    ```
+
+* Values, including bare messages, containing white space or control characters (spaces, tabs, newlines, emoji, etc…) will be wrapped in double quotes (`""`) and fully escaped.
+
+    ```ruby
+    logger.info("👻 Boo!")
+      #=> time=2022-04-20T23:33:35.912595Z severity=INFO  msg="\u{1F47B} Boo!"
+
+    logger.info(number: 42, with_quotes: %{These "are" 'quotes', OK?})
+      #=> time=2022-04-20T23:33:36.412183Z severity=INFO  number=42 with_quotes="These \"are\" 'quotes', OK?"
+    ```
+
+* Floating point values are truncated to three digits.
+
+* Time values are formatted as ISO8601 strings, with six digits sub-second precision.
+
+* A value that is an Array is wrapped in square brackets, and then the above rules applied to each Array value.
+  This works well for arrays of simple values - like numbers, symbols, or simple strings.
+  But complex data structures will result in human mind-breaking escape sequences.
+  So don't do that.
+  Keep values simple.
+
+  ```ruby
+  logger.info(an_array: [1, "two", :three])
+    #=> time=2022-04-20T23:33:36.412183Z severity=INFO  an_array="[1, two, three]"
+  ```
+
+**NOTE**: it is **not** expected that log lines generated by `Logfmt` can be round-tripped by parsing the log line with `Logfmt`.
+Specifically, this applies to Unicode and some control characters, as well as bare messages which will be wrapped in the `msg` key when writing.
+Additionally, symbol keys will be parsed back into string keys.
+
+[logfmt-blog]: https://brandur.org/logfmt "Structured log lines with key/value pairs"
+[semver]: https://semver.org/spec/v2.0.0.html "Semantic Versioning 2.0.0"
+[tagged-logger]: https://guides.rubyonrails.org/debugging_rails_applications.html#tagged-logging "Tagged Logging"

data/lib/logfmt/tagged_logger.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "logger"
+require "active_support"
+
+module Logfmt
+  class TaggedLogger < ActiveSupport::Logger
+    include ActiveSupport::TaggedLogging
+
+    def initialize(*args, formatter: nil, **kwargs)
+      super
+      # There is a bug in ActiveSupport::Logger where it ignores the formatter:
+      # kwarg given as part of ::new and instead always sets the logger to an
+      # instance of ActiveSupport::Logger::SimpleFormatter.
+      # see: https://github.com/rails/rails/pull/44942
+      #
+      # When that's addressed we can change this line to:
+      #
+      # ```ruby
+      # self.formatter ||= KeyValueFormatter.new
+      # ```
+      self.formatter = formatter || Logger::KeyValueFormatter.new
+
+      # Wrap the base formatter in our tagging-aware formatter
+      self.formatter = Formatter.new(self.formatter)
+    end
+
+    class Formatter < SimpleDelegator
+      include ActiveSupport::TaggedLogging::Formatter
+
+      def call(severity, timestamp, progname, msg)
+        tag_pairs, bare_tags = current_tags.partition { |t| t.respond_to?(:to_hash) }
+
+        pairs = {tags: format_bare_tags(bare_tags)}
+        pairs = tag_pairs.map(&:to_hash)
+          .inject(pairs, :merge)
+          .merge(message_to_hash(msg))
+          .compact
+
+        __getobj__.call(severity, timestamp, progname, pairs)
+      end
+
+      private
+
+      def format_bare_tags(tags)
+        tags = Array(tags).compact
+
+        return nil if tags.empty?
+
+        tags.map { |tag| "[#{tag}]" }.join(" ")
+      end
+
+      def message_to_hash(message)
+        return message.to_hash if message.respond_to?(:to_hash)
+
+        {msg: message}
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: logfmt-tagged_logger
+version: !ruby/object:Gem::Version
+  version: 0.1.0.beta.1
+platform: ruby
+authors:
+- Steven Harman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logfmt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.beta.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.beta.1
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Make logfmt aware of ActiveSupport::TaggedLogging to write logfmt-styled
+  log lines, with tags!
+email:
+- steven@harmanly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/logfmt/tagged_logger.rb
+homepage: https://github.com/cyberdelia/logfmt-ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/cyberdelia/logfmt-ruby/issues
+  changelog_uri: https://github.com/cyberdelia/logfmt-ruby/blog/master/CHANGELOG.md
+  documentation_uri: https://github.com/cyberdelia/logfmt-ruby
+  source_code_uri: https://github.com/cyberdelia/logfmt-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: An ActiveSupport::TaggedLogging compatible logger for logfmt.
+test_files: []