logfmt 0.0.10 → 0.1.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d357083dac3dea75a9cd937ac2ba24b8cfff5c11f0656749a084cc16fb6cd4a
-  data.tar.gz: 97aad097b305ded6c753de8c233cd2317c12dcb9834fec52047ea799d842f8ff
+  metadata.gz: 6a4ffa4696a5c33a721cbe1c0e440af8d790cac06a9d2c5d1439798d5419186d
+  data.tar.gz: 2b7137ed007f395f5f74eb59c247f086e6f30b7e4b9deb5948a35bb1a0bfb3cd
 SHA512:
-  metadata.gz: 8a140be6a60d67ca2f7eb8373689e7f246e7ffadae3fba22da5820992b38df1410a5faaabc0e37ab6e318434db0ba4973b4844e74e86f3e60ef9df19aff574c8
-  data.tar.gz: 9df321f5d270af2e288a6de8e2391d9a05159e680ae3bfa669751a92bd0e155e30d6fc86c55f246896c20d5d274e45b93878a5f365ebb0c652c94b52d53379a2
+  metadata.gz: 27fe0c766d112a51224bb4850ed153a2afac3a881535f502678d4c855bce8cb36416b5711cf4eaa811004cbd195ecc7ea24eae12922a6225bb475c663f51e6c2
+  data.tar.gz: a604b0fdde0f5160ad76c17f589731f50be22703a7c631ac78d16a6edceca0dfab4f5656a176624d66c6e6408167cffa3f4217092c53e47c6df538f72506c380

data/CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## \[Unreleased\]
 
+## [0.1.0.beta.1] 2022-10-21
+### Added
+  - Add `Logfmt::Logger` and `Logfmt::TaggedLogger`.
+    The later is distributed as its own gem, `logfmt-tagged_logger`, but lives in this repo.
+
 ## [0.0.10] 2022-04-30
 ### Changed
   - Autoload the `Logfmt::Parser` when it's used, in preparation for the coming `Logfmt::Logger` and friends.

data/Gemfile

@@ -1,3 +1,4 @@
 source "https://rubygems.org"
 
-gemspec
+gemspec name: "logfmt"
+gemspec name: "logfmt-tagged_logger"

data/README.md

@@ -1,6 +1,58 @@
 # Logfmt
 
-Parse log lines in the logfmt style:
+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"
@@ -8,3 +60,95 @@ 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/Rakefile

@@ -1,8 +1,37 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
+require "bundler/gem_helper"
 require "rspec/core/rake_task"
 
+desc "Run all specs"
 RSpec::Core::RakeTask.new(:spec)
 
+namespace "logfmt" do
+  Bundler::GemHelper.install_tasks name: "logfmt"
+end
+
+# Inspired by how dotenv/dotenv-rails handles mulitple Gems in a single repo
+class LogFmtTaggedLoggerGemHelper < Bundler::GemHelper
+  def guard_already_tagged
+    # noop
+  end
+
+  def tag_version
+    # noop
+  end
+end
+
+namespace "logfmt-tagged_logger" do
+  LogFmtTaggedLoggerGemHelper.install_tasks name: "logfmt-tagged_logger"
+end
+
+desc "Build logfmt and logfmt-tagged_logger into the pkg directory"
+task build: ["logfmt:build", "logfmt-tagged_logger:build"]
+
+desc "Build and install logfmt and logfmt-tagged_logger into system gems"
+task install: ["logfmt:install", "logfmt-tagged_logger:install"]
+
+desc "Create tag, build, and push logfmt and logfmt-tagged_logger to rubygems.org"
+task release: ["logfmt:release", "logfmt-tagged_logger:release"]
+
 task default: :spec

data/lib/logfmt/logger.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../logfmt"
+require "logger"
+require "time"
+
+module Logfmt
+  class Logger < ::Logger
+    def initialize(*args, **kwargs)
+      super
+      @formatter ||= KeyValueFormatter.new
+    end
+
+    class KeyValueFormatter < ::Logger::Formatter
+      def call(severity, timestamp, progname, msg)
+        %(time=#{format_datetime(timestamp)} severity=#{severity.ljust(5)}#{format_progname(progname)} #{format_message(msg)}\n)
+      end
+
+      private
+
+      def format_datetime(time)
+        time.utc.iso8601(6)
+      end
+
+      def format_message(msg)
+        return unless msg
+
+        if msg.respond_to?(:to_hash)
+          pairs = msg.to_hash.map { |k, v| format_pair(k, v) }
+          pairs.compact.join(" ")
+        else
+          format_pair("msg", msg)
+        end
+      end
+
+      def format_pair(key, value)
+        return nil if value.nil?
+
+        # Return a bare key when the value is a `TrueClass`
+        return key if value == true
+
+        "#{key}=#{format_value(value)}"
+      end
+
+      def format_progname(progname)
+        return nil unless progname
+
+        # Format this pair like any other to ensure quoting, escaping, etc…,
+        # But we also need a leading space so we can interpolate the resulting
+        # key/value pair into our log line.
+        " #{format_pair(" progname", progname)}"
+      end
+
+      def format_value(value)
+        if value.is_a?(Float)
+          format("%.3f", value)
+        elsif value.is_a?(Time)
+          format_datetime(value)
+        elsif value.respond_to?(:to_ary)
+          format_value(
+            "[#{Array(value).map { |v| format_value(v) }.join(", ")}]"
+          )
+        else
+          # Interpolating due to a weird/subtle behaviour possible in #to_s.
+          # Namely, it's possible it doesn't actually return a String:
+          # https://github.com/ruby/spec/blob/3affe1e54fcd11918a242ad5d4a7ba895ee30c4c/language/string_spec.rb#L130-L141
+          value = "#{value}" # rubocop:disable Style/RedundantInterpolation
+          value = value.dump if value.match?(/[[:space:]]|[[:cntrl:]]/) # wrap in quotes and escape control characters
+          value
+        end
+      end
+    end
+  end
+end

data/lib/logfmt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logfmt
-  VERSION = "0.0.10"
+  VERSION = "0.1.0.beta.2"
 end

data/lib/logfmt.rb

@@ -3,6 +3,7 @@
 require "logfmt/version"
 
 module Logfmt
+  autoload(:Logger, "logfmt/logger")
   autoload(:Parser, "logfmt/parser")
 
   def self.parse(line)

data/logfmt.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/logfmt/version"
+require "English"
+
+Gem::Specification.new do |spec|
+  spec.name = "logfmt"
+  spec.version = Logfmt::VERSION
+  spec.authors = ["Timothée Peignier"]
+  spec.email = ["timothee.peignier@tryphon.org"]
+
+  spec.summary = "Write and parse logfmt messages."
+  spec.description = "Write and parse log lines in the logfmt style."
+  spec.homepage = "https://github.com/cyberdelia/logfmt-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.5.0"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blog/master/CHANGELOG.md",
+    "documentation_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
+      .reject { |f|
+        (f == __FILE__) ||
+          f.match?(%r{\A(?:(?:bin|spec|features)/|\.(?:git|github))}) ||
+          f.match?(/tagged_logger/)
+      }
+  end
+  spec.bindir = "bin"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "pry-byebug", "~> 3.9"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logfmt
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.0.beta.2
 platform: ruby
 authors:
 - Timothée Peignier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-04-30 00:00:00.000000000 Z
+date: 2022-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry-byebug
@@ -52,7 +52,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Parse log lines in the logfmt style.
+description: Write and parse log lines in the logfmt style.
 email:
 - timothee.peignier@tryphon.org
 executables: []
@@ -65,13 +65,11 @@ files:
 - README.md
 - Rakefile
 - bench.rb
-- bin/bundle
-- bin/console
-- bin/rake
-- bin/rspec
 - lib/logfmt.rb
+- lib/logfmt/logger.rb
 - lib/logfmt/parser.rb
 - lib/logfmt/version.rb
+- logfmt.gemspec
 homepage: https://github.com/cyberdelia/logfmt-ruby
 licenses:
 - MIT
@@ -88,15 +86,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
-summary: Parse logfmt messages.
+summary: Write and parse logfmt messages.
 test_files: []

data/bin/bundle

@@ -1,114 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'bundle' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-require "rubygems"
-
-m = Module.new do
-  module_function
-
-  def invoked_as_script?
-    File.expand_path($0) == File.expand_path(__FILE__)
-  end
-
-  def env_var_version
-    ENV["BUNDLER_VERSION"]
-  end
-
-  def cli_arg_version
-    return unless invoked_as_script? # don't want to hijack other binstubs
-    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
-    bundler_version = nil
-    update_index = nil
-    ARGV.each_with_index do |a, i|
-      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
-        bundler_version = a
-      end
-      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
-      bundler_version = $1
-      update_index = i
-    end
-    bundler_version
-  end
-
-  def gemfile
-    gemfile = ENV["BUNDLE_GEMFILE"]
-    return gemfile if gemfile && !gemfile.empty?
-
-    File.expand_path("../../Gemfile", __FILE__)
-  end
-
-  def lockfile
-    lockfile =
-      case File.basename(gemfile)
-      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
-      else "#{gemfile}.lock"
-      end
-    File.expand_path(lockfile)
-  end
-
-  def lockfile_version
-    return unless File.file?(lockfile)
-    lockfile_contents = File.read(lockfile)
-    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
-    Regexp.last_match(1)
-  end
-
-  def bundler_requirement
-    @bundler_requirement ||=
-      env_var_version || cli_arg_version ||
-        bundler_requirement_for(lockfile_version)
-  end
-
-  def bundler_requirement_for(version)
-    return "#{Gem::Requirement.default}.a" unless version
-
-    bundler_gem_version = Gem::Version.new(version)
-
-    requirement = bundler_gem_version.approximate_recommendation
-
-    return requirement unless Gem.rubygems_version < Gem::Version.new("2.7.0")
-
-    requirement += ".a" if bundler_gem_version.prerelease?
-
-    requirement
-  end
-
-  def load_bundler!
-    ENV["BUNDLE_GEMFILE"] ||= gemfile
-
-    activate_bundler
-  end
-
-  def activate_bundler
-    gem_error = activation_error_handling do
-      gem "bundler", bundler_requirement
-    end
-    return if gem_error.nil?
-    require_error = activation_error_handling do
-      require "bundler/version"
-    end
-    return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION))
-    warn "Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`"
-    exit 42
-  end
-
-  def activation_error_handling
-    yield
-    nil
-  rescue StandardError, LoadError => e
-    e
-  end
-end
-
-m.load_bundler!
-
-if m.invoked_as_script?
-  load Gem.bin_path("bundler", "bundle")
-end

data/bin/console

@@ -1,8 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "logfmt"
-
-require "pry"
-Pry.start

data/bin/rake

@@ -1,29 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'rake' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-require "pathname"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
-  Pathname.new(__FILE__).realpath)
-
-bundle_binstub = File.expand_path("../bundle", __FILE__)
-
-if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
-    load(bundle_binstub)
-  else
-    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
-Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
-  end
-end
-
-require "rubygems"
-require "bundler/setup"
-
-load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -1,29 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'rspec' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-require "pathname"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
-  Pathname.new(__FILE__).realpath)
-
-bundle_binstub = File.expand_path("../bundle", __FILE__)
-
-if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
-    load(bundle_binstub)
-  else
-    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
-Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
-  end
-end
-
-require "rubygems"
-require "bundler/setup"
-
-load Gem.bin_path("rspec-core", "rspec")