chalk-log 0.1.2

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.tddium*

data/Gemfile

@@ -0,0 +1,8 @@
+# Execute bundler hook if present
+['~/.', '/etc/'].any? do |file|
+ File.lstat(path = File.expand_path(file + 'bundle-gemfile-hook')) rescue next
+ eval(File.read(path), binding, path); break true
+end || source('https://rubygems.org/')
+
+gemspec
+gem 'pry'

data/History.txt

@@ -0,0 +1,6 @@
+=== 0.1.0 2014-05-25
+
+* Started being more strict with arguments passed. In particular,
+  stopped accepting nil or boolean trailing arguments.
+* Switched to using Chalk::Config, eliminating Chalk::Log::Config.
+* You now disable Chalk::Log by setting either of `configatron.chalk.log.disabled || LSpace[:'chalk.log.disabled']`. `ENV["CHALK_NOLOG"]` and `LSpace[:logging_disabled] are now ignored.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Stripe
+
+MIT License
+
+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,142 @@
+# Chalk::Log
+
+`Chalk::Log` adds a logger object to any class, which can be used for
+unstructured or semi-structured logging. Use it as follows:
+
+```ruby
+class A
+  include Chalk::Log
+end
+
+A.log.info('hello', key: 'value')
+#=> [2013-06-18 22:18:28.314756] [64682] hello: key="value"
+```
+
+The output is both human-digestable and easily parsed by log indexing
+systems such as [Splunk](http://www.splunk.com/) or
+[Logstash](http://logstash.net/).
+
+It can also pretty-print exceptions for you:
+
+```ruby
+module A; include Chalk::Log; end
+begin; raise "hi"; rescue => e; end
+A.log.error('Something went wrong', e)
+#=> Something went wrong: hi (RuntimeError)
+#     (irb):8:in `irb_binding'
+#     /Users/gdb/.rbenv/versions/1.9.3-p362/lib/ruby/1.9.1/irb/workspace.rb:80:in `eval#     /Users/gdb/.rbenv/versions/1.9.3-p362/lib/ruby/1.9.1/irb/workspace.rb:80:in `evaluate'
+#     /Users/gdb/.rbenv/versions/1.9.3-p362/lib/ruby/1.9.1/irb/context.rb:254:in `evaluate'
+#     /Users/gdb/.rbenv/versions/1.9.3-p362/lib/ruby/1.9.1/irb.rb:159:in `block (2 levels) in eval_input'
+#     [...]
+```
+
+The log methods accept a message and/or an exception and/or an info
+hash (if multiple are passed, they must be provided in that
+order). The log methods will never throw an exception, but will
+instead print an log message indicating they had a fault.
+
+## Overview
+
+Including `Chalk::Log` creates a `log` method as both a class an
+instance method, which returns a class-specific logger.
+
+By default, it tags loglines with auxiliary information: a
+microsecond-granularity timestamp, the PID, and an action_id (which
+should tie together all lines for a single logical action in your
+system, such as a web request).
+
+You can turn off tagging, or just turn off timestamping, through
+appropriate configatron settings (see [config.yaml](/config.yaml)).
+
+There are also two `LSpace` dynamic settings available:
+
+- `LSpace[:action_id]`: Set the action_id dynamically for this action. (This is used automatically by things like `Chalk::Web` which have a well-defined action.)
+- `LSpace[:'chalk.log.disabled']`: Disable all logging.
+
+You can use `LSpace` settings as follows:
+
+```ruby
+class A; include Chalk::Log; end
+foo = A.new
+
+LSpace.with(action_id: 'request-123') do
+  foo.log.info('Test')
+  #=> [2014-05-26 01:12:28.485822] [47325|request-123] Test
+end
+```
+
+## Log methods
+
+`Chalk::Log` provides five log levels:
+
+    debug, info, warn, error, fatal
+
+## Inheritance
+
+`Chalk::Log` makes a heroic effort to ensure that inclusion chaining
+works, so you can do things like:
+
+```ruby
+module A
+  include Chalk::Log
+end
+
+module B
+ include A
+end
+
+class C
+  include B
+end
+```
+
+and still have `C.log` and `C.new.log` work. (Normally you'd expect
+for the class-method version to be left behind.)
+
+## Best practices
+
+- You should never use string interpolation in your log
+  message. Instead, always use the structured logging keys. So for
+  example:
+
+```ruby
+# Bad
+log.info("Just printed #{lines.length} lines")
+# Good
+log.info("Printed", lines: lines.length)
+```
+
+- Don't end messages with a punctuation -- `Chalk::Log` will
+  automatically add a colon if an info hash is provided; if not, it's
+  fine to just end without trailing punctutaion. Case in point
+
+- In most projects, you'll find most of your classes start including
+  `Chalk::Log` -- it's pretty cheap to add it, and it's quite
+  lightweight to use. (In contrast, there's no good way to autoinclude
+  it, since that would likely break many classes which aren't
+  expecting a magical `log` method to appear.)
+
+## Limitations
+
+`Chalk::Log` is not very configurable. Our usage at Stripe tends to be
+fairly opinionated, so there hasn't been much demand for increased
+configurability. We would be open to making it less rigid,
+however. (In any case, under the hood `Chalk::Log` is just using the
+`logging` gem, so if the need arises it wouldn't be hard to acquire
+the full flexibility of `logging`.)
+
+# Contributors
+
+- Greg Brockman
+- Andreas Fuchs
+- Andy Brody
+- Anurag Goel
+- Evan Broder
+- Nelson Elhage
+- Brian Krausz
+- Christian Anderson
+- Jeff Balogh
+- Jeremy Hoon
+- Julia Evans
+- Russell Davis
+- Steven Noble

data/Rakefile

@@ -0,0 +1,17 @@
+require 'bundler/gem_tasks'
+require 'bundler/setup'
+require 'chalk-rake/gem_tasks'
+require 'rake/testtask'
+
+task :default do
+  sh 'rake -T'
+end
+
+Rake::TestTask.new do |t|
+  t.libs = ["lib"]
+  # t.warning = true
+  t.verbose = true
+  t.test_files = FileList['test/**/*.rb'].reject do |file|
+    file.end_with?('_lib.rb') || file.include?('/_lib/')
+  end
+end

data/chalk-log.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chalk-log/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'chalk-log'
+  gem.version       = Chalk::Log::VERSION
+  gem.authors       = ['Stripe']
+  gem.email         = ['oss@stripe.com']
+  gem.description   = %q{Extends classes with a `log` method}
+  gem.summary       = %q{Chalk::Log makes any class loggable. It provides a logger that can be used for both structured and unstructured log.}
+  gem.homepage      = 'https://github.com/stripe/chalk-log'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+  gem.add_dependency 'chalk-config'
+  gem.add_dependency 'logging'
+  gem.add_dependency 'lspace'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'minitest', '~> 3.2.0'
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'chalk-rake'
+end

data/config.yaml

@@ -0,0 +1,22 @@
+chalk:
+  log:
+    # The default log level
+    default_level: 'INFO'
+
+    # Whether to enable tagging (with timestamp, PID, action_id).
+    tagging: true
+
+    # Whether to enable tagging with PID (can be subsumed by
+    # `tagging: false`)
+    pid: true
+
+    # Whether to enable tagging with timestamp (can be subsumed by
+    # `tagging: false`). This option is set automatically in
+    # lib/chalk-log.rb.
+    timestamp: null
+
+    # Whether to show logs at all
+    disabled: false
+
+    # Whether to remove gem lines from backtraces
+    compress_backtraces: false

data/lib/chalk-log.rb

@@ -0,0 +1,137 @@
+require 'logging'
+require 'lspace'
+require 'set'
+
+require 'chalk-config'
+require 'chalk-log/version'
+
+# Include `Chalk::Log` in a class or module to make that class (and
+# all subclasses / includees / extendees) loggable. This creates a
+# class and instance `log` method which you can call from within your
+# loggable class.
+#
+# Loggers are per-class and can be manipulated as you'd expect:
+#
+# ```ruby
+# class A
+#   include Chalk::Log
+#
+#   log.level = 'DEBUG'
+#   log.debug('Now you see me!')
+#   log.level = 'INFO'
+#   log.debug('Now you do not!')
+# end
+# ```
+#
+# You shouldn't need to directly access any of the methods on
+# `Chalk::Log` itself.
+module Chalk::Log
+  require 'chalk-log/errors'
+  require 'chalk-log/logger'
+  require 'chalk-log/layout'
+  require 'chalk-log/utils'
+
+  # The set of available log methods. (Changing these is not currently
+  # a supported interface, though if the need arises it'd be easy to
+  # add.)
+  LEVELS = [:debug, :info, :warn, :error, :fatal].freeze
+
+  @included = Set.new
+
+  # Method which goes through heroic efforts to ensure that the whole
+  # inclusion hierarchy has their `log` accessors.
+  def self.included(other)
+    if other == Object
+      raise "You have attempted to `include Chalk::Log` onto Object. This is disallowed, since otherwise it might shadow any `log` method on classes that weren't expecting it (including, for example, `configatron.chalk.log`)."
+    end
+
+    # Already been through this ordeal; no need to repeat it. (There
+    # shouldn't be any semantic harm to doing so, just a potential
+    # performance hit.)
+    return if @included.include?(other)
+    @included << other
+
+    # Make sure to define the .log class method
+    other.extend(ClassMethods)
+
+    # If it's a module, we need to make sure both inclusion/extension
+    # result in virally carrying Chalk::Log inclusion downstream.
+    if other.instance_of?(Module)
+      other.class_eval do
+        included = method(:included)
+        extended = method(:extended)
+
+        define_singleton_method(:included) do |other|
+          other.send(:include, Chalk::Log)
+          included.call(other)
+        end
+
+        define_singleton_method(:extended) do |other|
+          other.send(:include, Chalk::Log)
+          extended.call(other)
+        end
+      end
+    end
+  end
+
+  # Public-facing initialization method for all `Chalk::Log`
+  # state. Unlike most other Chalk initializers, this will be
+  # automatically run (invoked on first logger instantiation). It is
+  # idempotent.
+  def self.init
+    return if @init
+    @init = true
+
+    # Load relevant configatron stuff
+    Chalk::Config.register(File.expand_path('../../config.yaml', __FILE__),
+      raw: true)
+
+    # The assumption is you'll pipe your logs through something like
+    # [Unilog](https://github.com/stripe/unilog) in production, which
+    # does its own timestamping.
+    Chalk::Config.register_raw(chalk: {log: {timestamp: STDERR.tty?}})
+
+    ::Logging.init(*LEVELS)
+    ::Logging.logger.root.add_appenders(
+      ::Logging.appenders.stderr(layout: layout)
+      )
+
+    Chalk::Log::Logger.init
+  end
+
+  # The default layout to use for the root `Logging::Logger`.
+  def self.layout
+    @layout ||= Chalk::Log::Layout.new
+  end
+
+  # Home of the backend `log` method people call; included *and*
+  # extended everywhere that includes Chalk::Log.
+  module ClassMethods
+    # The backend `log` method exposed to everyone. (In practice, the
+    # method people call directly is one wrapper above this.)
+    #
+    # Sets a `@__chalk_log` variable to hold the logger instance.
+    def log
+      @__chalk_log ||= Chalk::Log::Logger.new(self.name)
+    end
+  end
+
+  # Make the `log` method inheritable.
+  include ClassMethods
+
+  # The technique here is a bit tricky. The same `log` implementation
+  # defined on any class needs to be callable by either an instance or
+  # class. (See the "correctly make the end class loggable when it has
+  # already included loggable" test for why. In particular, someone
+  # may have already included me, and then clobbered the class
+  # implementations by extending me.) Hence we do this "defer to
+  # class, unless I am a class" logic.
+  log = instance_method(:log)
+  define_method(:log) do
+    if self.kind_of?(Class)
+      log.bind(self).call
+    else
+      self.class.log
+    end
+  end
+end

data/lib/chalk-log/errors.rb

@@ -0,0 +1,7 @@
+module Chalk::Log
+  # Base error class
+  class Error < StandardError; end
+  # Thrown when you call a layout with the wrong arguments. (It gets
+  # swallowed and printed by the fault handling in layout.rb, though.)
+  class InvalidArguments < Error; end
+end

data/lib/chalk-log/layout.rb

@@ -0,0 +1,192 @@
+require 'json'
+require 'set'
+require 'time'
+
+# The layout backend for the Logging::Logger.
+#
+# Accepts a message and/or an exception and/or an info
+# hash (if multiple are passed, they must be provided in that
+# order)
+class Chalk::Log::Layout < ::Logging::Layout
+  # Formats an event, and makes a heroic effort to tell you if
+  # something went wrong. (Logging will otherwise silently swallow any
+  # exceptions that get thrown.)
+  #
+  # @param event provided by the Logging::Logger
+  def format(event)
+    begin
+      begin
+        begin
+          do_format(event)
+        rescue StandardError => e
+          # Single fault!
+          error!('[Chalk::Log fault: Could not format message] ', e)
+        end
+      rescue StandardError => e
+        # Double fault!
+        "[Chalk::Log fault: Double fault while formatting message. This means we couldn't even report the error we got while formatting.] #{e.message}\n"
+      end
+    rescue StandardError => e
+      # Triple fault!
+      "[Chalk::Log fault: Triple fault while formatting message. This means we couldn't even report the error we got while reporting the original error.]\n"
+    end
+  end
+
+  # Formats a hash for logging. This is provided for (rare) use outside of log
+  # methods; you can pass a hash directly to log methods and this formatting
+  # will automatically be applied.
+  #
+  # @param hash [Hash] The hash to be formatted
+  def format_hash(hash)
+    hash.map {|k, v| display(k, v)}.join(' ')
+  end
+
+  private
+
+  def do_format(event)
+    data = event.data
+    time = event.time
+    level = event.level
+
+    # Data provided by blocks may not be arrays yet
+    data = [data] unless data.kind_of?(Array)
+    info = data.pop if data.last.kind_of?(Hash)
+    error = data.pop if data.last.kind_of?(Exception)
+    message = data.pop if data.last.kind_of?(String)
+
+    if data.length > 0
+      raise Chalk::Log::InvalidArguments.new("Invalid leftover arguments: #{data.inspect}")
+    end
+
+    id = action_id
+    pid = Process.pid
+
+    pretty_print(
+      time: timestamp_prefix(time),
+      level: Chalk::Log::LEVELS[level],
+      action_id: id,
+      message: message,
+      error: error,
+      info: (info && info.merge(contextual_info || {})) || contextual_info,
+      pid: pid
+      )
+  end
+
+  def pretty_print(spec)
+    message = build_message(spec[:message], spec[:info], spec[:error])
+    message = tag(message, spec[:time], spec[:pid], spec[:action_id])
+    message
+  end
+
+  def build_message(message, info, error)
+    # Make sure we're not mutating the message that was passed in
+    if message
+      message = message.dup
+    end
+
+    if message && (info || error)
+      message << ':'
+    end
+
+    if info
+      message << ' ' if message
+      message ||= ''
+      info!(message, info)
+    end
+
+    if error
+      message << ' ' if message
+      message ||= ''
+      error!(message, error)
+    end
+
+    message ||= ''
+    message << "\n"
+    message
+  end
+
+  # Displaying info hash
+
+  def info!(message, info)
+    message << format_hash(info.merge(contextual_info || {}))
+  end
+
+  def display(key, value)
+    begin
+      value = json(value)
+    rescue StandardError
+      value = "#{value.inspect} [JSON-FAILED]"
+    end
+
+    # Non-numeric simple strings don't need quotes.
+    if value =~ /\A"\w*[A-Za-z]\w*"\z/ &&
+        !['"true"', '"false"', '"null"'].include?(value)
+      value = value[1...-1]
+    end
+
+    "#{key}=#{value}"
+  end
+
+  # Displaying backtraces
+
+  def error!(message, error)
+    backtrace = error.backtrace || ['[no backtrace]']
+    message << display(:error_class, error.class.to_s) << " "
+    message << display(:error, error.to_s)
+    message << "\n"
+    message << Chalk::Log::Utils.format_backtrace(backtrace)
+    message << "\n"
+    message
+  end
+
+  def json(value)
+    # Use an Array (and trim later) because Ruby's JSON generator
+    # requires an array or object.
+    wrapped = [value]
+
+    # We may alias the raw JSON generation method. We don't care about
+    # emiting raw HTML tags heres, so no need to use the safe
+    # generation method.
+    if JSON.respond_to?(:unsafe_generate)
+      dumped = JSON.unsafe_generate(wrapped)
+    else
+      dumped = JSON.generate(wrapped)
+    end
+
+    dumped[1...-1] # strip off the brackets we added while array-ifying
+  end
+
+  def action_id
+    LSpace[:action_id]
+  end
+
+  def contextual_info
+    LSpace[:'chalk.log.contextual_info']
+  end
+
+  def tag(message, time, pid, action_id)
+    return message unless configatron.chalk.log.tagging
+
+    metadata = []
+    metadata << pid if configatron.chalk.log.pid
+    metadata << action_id if action_id
+    prefix = "[#{metadata.join('|')}] " if metadata.length > 0
+
+    if configatron.chalk.log.timestamp
+      prefix = "[#{time}] #{prefix}"
+    end
+
+    out = ''
+    message.split("\n").each do |line|
+      out << prefix << line << "\n"
+    end
+
+    out
+  end
+
+  def timestamp_prefix(now)
+    now_fmt = now.strftime("%Y-%m-%d %H:%M:%S")
+    ms_fmt = sprintf("%06d", now.usec)
+    "#{now_fmt}.#{ms_fmt}"
+  end
+end