traceable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc0fb1daa3bcf7f643a76c12767cb4b6879de019
+  data.tar.gz: a477c637eefd5b76b28105a83279d7faa5880650
+SHA512:
+  metadata.gz: 3384130f5711e0c854c9b00d093b82cca25e8b9f7333c2be73b61d58eb741df9abab464ed07a5cbd3f50dafbaeee8b11aa062a1a9ef20d19699e5c06b9c883aa
+  data.tar.gz: 34a461846b43e0015c1e5c67b53eeb306233729270283f5c546d2e42140930bf54d4472b7726cb31b8502829c935e55f16be910ec7df039f7109f5215634634a

data/lib/traceable/class_methods.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Traceable
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    # Put an automatic '#trace' call around the specified method,
+    # so that entry and exit from the method will be automatically logged.
+    #
+    # Can be used when defining the method:
+    #
+    #     class X
+    #       include SISApp::Traceable
+    #       traced_method def foo
+    #         ...
+    #       end
+    #     end
+    #
+    # or it can be called after defining the method:
+    #
+    #    class X
+    #      include SISApp::Traceable
+    #      def foo
+    #        ...
+    #      end
+    #      traced_method :foo
+    #     end
+    #
+    # The generated log message(s) will include the class name and method name
+    def traced_method(method_name)
+      klass = self
+      trace_name = "#{klass.name}##{method_name}"
+      orig_method = klass.instance_method(method_name)
+
+      klass.send(:define_method, method_name) do |*args, &block|
+        trace trace_name do
+          if block
+            orig_method.bind(self).call(*args) { |*block_args| block.call(*block_args) }
+          else
+            orig_method.bind(self).call(*args)
+          end
+        end
+      end
+
+      method_name
+    end
+
+    # For the (relatively rare) case of calling trace() in a class method
+    # of a Traceable class - creates a new Tracer instance
+    def trace(msg = nil, **tags)
+      tracer = Tracer.new(Tracer.default_parent)
+
+      if block_given?
+        tracer.do_block(msg, **tags) { yield }
+      elsif msg
+        tracer.info msg, **tags
+      else
+        tracer
+      end
+    end
+  end
+end

data/lib/traceable/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Traceable
+  class Config
+    attr_accessor :default_tags
+    attr_accessor :logger
+
+    def initialize
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::INFO
+
+      @default_tags = {}
+    end
+  end
+
+  def self.configure(&_)
+    yield config
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+end

data/lib/traceable/tracer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Traceable
+  # An instance of this class is used by each Traceable object to
+  # generate log entries. Each log entry consists of a key/value
+  # map ("tags"). Tags will be inherited from a parent instance,
+  # if provided.
+  class Tracer
+    attr_reader :logger
+    attr_reader :id
+    attr_reader :parent
+    attr_reader :tags
+
+    def initialize(parent_tracer, tags: nil)
+      @logger = Traceable.config.logger
+
+      @parent = case parent_tracer
+                when nil
+                  nil
+                when Tracer
+                  parent_tracer
+                when Traceable
+                  parent_tracer.local_tracer
+                else
+                  raise(ArgumentError, "#{parent_tracer} (#{parent_tracer.class})")
+                end
+
+      @tags = @parent ? @parent.tags.dup : Tracer.default_tags
+      @tags.merge!(tags) if tags
+    end
+
+    def self.default_tags
+      tags = Traceable.config.default_tags.merge(
+        trace: SecureRandom.uuid
+      )
+      tags.each_key do |k|
+        value = tags[k]
+        tags[k] = value.call if value.respond_to?(:call)
+      end
+      tags
+    end
+
+    def emit(method, msg, **tags)
+      final_tags = make_tags(message: msg, **tags)
+      emit_tags(method, final_tags)
+    end
+
+    def make_tags(**tags)
+      @tags.merge(tags)
+    end
+
+    def emit_tags(method, tags)
+      logger.send(method, tags)
+    rescue StandardError => ex
+      warn "EXCEPTION in trace: #{ex}"
+    end
+
+    def fatal(msg, **tags)
+      emit :fatal, msg, **tags
+    end
+
+    def error(msg, **tags)
+      emit :error, msg, **tags
+    end
+
+    def warn(msg, **tags)
+      emit :warn, msg, **tags
+    end
+
+    def info(msg, **tags)
+      emit :info, msg, **tags
+    end
+
+    def debug(msg, **tags)
+      emit :debug, msg, **tags
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
+    def do_block(msg, **tags, &_)
+      info "START: #{msg}", enter: true, **tags
+      block_start_time = Time.now.utc
+
+      begin
+        push
+        yield
+      rescue StandardError => ex
+        elapsed = Time.now.utc - block_start_time
+        if ex.instance_variable_defined?(:@traceable_rescued)
+          origin = ex.instance_variable_get(:@traceable_rescued)
+          ex_message = " [propagated from #{origin}]"
+        else
+          ex.instance_variable_set(:@traceable_rescued, msg)
+          ex_message = ", #{ex.message}"
+          tags[:backtrace] ||= ex.backtrace.join('\n')
+        end
+
+        warn "EXCEPTION: #{msg} => #{ex.class.name}#{ex_message}",
+             exception: true, elapsed: elapsed, class: ex.class.name, **tags
+
+        raise
+      ensure
+        pop
+
+        unless ex
+          elapsed = Time.now.utc - block_start_time
+          info "END: #{msg}", exit: true, elapsed: elapsed, **tags
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+
+    def self.default_parent
+      tracer_stack.last # nil if nothing currently on the stack
+    end
+
+    # The tracer stack is a thread-local list of tracer instances, allowing the
+    # current tracer context to be automatically inherited by any other tracer
+    # instances created further down in the stack.
+    #
+    # The current tracer is pushed onto the stack when entering a traced block,
+    # then popped from the stack when leaving the traced block.
+
+    def self.tracer_stack
+      Thread.current[:tracer_stack] ||= []
+    end
+
+    def push
+      Tracer.tracer_stack.push self
+    end
+
+    def pop
+      Tracer.tracer_stack.pop
+    end
+  end
+end

data/lib/traceable/version.rb

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

data/lib/traceable.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Traceable
+  # A module for enhanced logging facilities.
+  #
+  # The intent of the Traceable functionality is to have log
+  # messages that provide runtime diagnostics as well as
+  # code documentation.
+
+  # Generate a log message
+  # When called without a block, generates a single log message:
+  #
+  #     trace "this is a single message"
+  #     trace.error "something bad happened"
+  #
+  # When called with a block, the given message is used to compose
+  # a log output at the entry and exit of the block.
+  #
+  #     trace "doing something nifty" do
+  #        do_something
+  #     end
+  def trace(msg = nil, **tags)
+    tracer = local_tracer
+
+    if block_given?
+      tracer.do_block(msg, **tags) { yield }
+    elsif msg
+      tracer.info msg, **tags
+    else
+      tracer
+    end
+  end
+
+  def local_tracer
+    @tracer ||= init_tracer
+  end
+
+  # Create the tracer instance used for generating log messages.
+  # If a parent is givent, tags and other settings will be
+  # inherited from it. If a parent is not given, it will automatically
+  # inherit from the next highest tracer in the call stack, if any.
+  #
+  # The default set of tags includes a unique ID string, so all
+  # log messages generated from that tracer will have the same
+  # ID string. In combination with auto-inheriting from a parent
+  # tracer, this means that all tracing messages starting from
+  # some common root will have the same ID string to be able
+  # to group together related messages in the log.
+  def init_tracer(parent: nil, tags: nil)
+    parent ||= Tracer.default_parent
+    @tracer = Tracer.new(parent, tags: tags)
+  end
+end
+
+require 'traceable/class_methods'
+require 'traceable/config'
+require 'traceable/tracer'

data/spec/spec_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+if /^2\.4/ =~ RUBY_VERSION # Limit coverage to one build
+  require 'simplecov'
+
+  SimpleCov.start do
+    add_filter 'lib/traceable/version.rb'
+    add_filter 'spec'
+    track_files 'lib/**/*.rb'
+  end
+
+  SimpleCov.minimum_coverage(100)
+end
+
+require 'traceable'
+
+require 'byebug'
+require 'pry'
+
+RSpec.configure do |config|
+  config.expect_with(:rspec) do |c|
+    c.syntax = %i[should expect]
+  end
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  config.order = :random
+  Kernel.srand config.seed
+end

data/spec/traceable_spec.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+RSpec.describe Traceable do
+  class FakeLogger
+    attr_reader :logs
+    def initialize
+      @logs = []
+    end
+
+    %i[info debug warn error fatal].each do |method|
+      define_method(method) do |tags|
+        logs << { method: method, tags: tags }
+      end
+    end
+  end
+
+  let(:fake_logger) { FakeLogger.new }
+  let(:logs) { fake_logger.logs }
+
+  before do
+    allow_any_instance_of(Traceable::Tracer).to receive(:logger) { fake_logger }
+  end
+
+  let(:subject_class) do
+    Class.new do
+      include Traceable
+
+      attr_reader :non_traced_called
+      def a_non_traced_method
+        @non_traced_called = true
+        :non_traced_return_value
+      end
+
+      attr_reader :traced_called
+      traced_method def a_traced_method
+        @traced_called = true
+        yield if block_given?
+        :traced_return_value
+      end
+
+      traced_method def a_traced_method_that_calls_a_block_with_a_parameter(val)
+        yield val
+      end
+
+      def trace_as_a_block
+        trace 'an example' do
+          trace 'a nested block' do
+            true
+          end
+        end
+      end
+
+      def self.a_class_method
+        trace 'in a class method'
+        trace 'in a class method with a block' do
+          trace.info 'test'
+        end
+      end
+    end
+  end
+
+  let(:contained_class) do
+    Class.new do
+      include Traceable
+
+      def initialize(parent)
+        init_tracer(parent: parent, tags: { inside: true })
+      end
+    end
+  end
+
+  subject do
+    subject_class.new
+  end
+
+  describe '#configure' do
+    it 'receives a Config instance' do
+      @config = nil
+      Traceable.configure { |c| @config = c }
+      expect(@config).to be_a Traceable::Config
+    end
+  end
+
+  describe '#config' do
+  end
+
+  describe '#trace' do
+    it 'responds to #trace' do
+      expect(subject.respond_to?(:trace)).to eq(true)
+    end
+
+    context 'when no block is given' do
+      it 'can be used like an explicit logger' do
+        subject.trace.info 'general info'
+        subject.trace.warn 'a warning'
+        subject.trace.error 'things look bad'
+        subject.trace.fatal 'fell on the floor'
+        subject.trace.debug 'fix me'
+        expect(logs[0][:method]).to eq(:info)
+        expect(logs[1][:method]).to eq(:warn)
+        expect(logs[2][:method]).to eq(:error)
+        expect(logs[3][:method]).to eq(:fatal)
+        expect(logs[4][:method]).to eq(:debug)
+      end
+
+      it 'logs as info as default' do
+        subject.trace 'blah', foo: :bar
+        expect(logs.size).to be(1)
+        expect(logs[0][:method]).to eq(:info)
+        expect(logs[0][:tags][:foo]).to be(:bar)
+      end
+    end
+
+    context 'when a block is given' do
+      it 'logs at start and end of the block' do
+        subject.trace_as_a_block
+        expect(logs.size).to be(4)
+        expect(logs[0][:tags].key?(:enter)).to be(true)
+        expect(logs[0][:tags][:message]).to eq('START: an example')
+        expect(logs[1][:tags].key?(:enter)).to be(true)
+        expect(logs[1][:tags][:message]).to eq('START: a nested block')
+        expect(logs[2][:tags].key?(:exit)).to be(true)
+        expect(logs[2][:tags][:message]).to eq('END: a nested block')
+        expect(logs[3][:tags].key?(:exit)).to be(true)
+        expect(logs[3][:tags][:message]).to eq('END: an example')
+      end
+
+      it 'reports the elapsed time of the block' do
+        subject.trace_as_a_block
+        count = 0
+        logs.select { |log| log[:tags].key?(:exit) }.each do |log|
+          expect(log[:tags][:elapsed]).to be_a(Numeric)
+          count += 1
+        end
+        expect(count).to be(2)
+      end
+    end
+
+    context 'in a class method' do
+      it 'works just like an instance method' do
+        expect { subject.class.a_class_method }.to change { logs.size }.by 4
+      end
+    end
+  end
+
+  describe '#local_tracer' do
+    it 'returns a Tracer object' do
+      expect(subject.local_tracer).to be_a(Traceable::Tracer)
+    end
+
+    it 'inherits a parent tracer' do
+      contained = contained_class.new(subject)
+      expect(contained.local_tracer).not_to eq(subject.local_tracer)
+      expect(contained.local_tracer.parent).to eq(subject.local_tracer)
+    end
+
+    it 'adds tags from the child' do
+      contained = contained_class.new(subject)
+      expect(subject.local_tracer.tags.key?(:inside)).to be(false)
+      expect(contained.local_tracer.tags.key?(:inside)).to be(true)
+    end
+
+    context 'tracer IDs' do
+      class Foo
+        include Traceable
+        def do_it
+          trace 'outside' do
+            trace 'inside' do
+              trace 'a message'
+            end
+          end
+        end
+      end
+
+      it 'creates a unique ID each time' do
+        (1..10).each do |_|
+          Foo.new.do_it
+        end
+
+        ids = Set.new
+        logs.each { |log| ids << log[:tags][:trace] }
+        expect(ids.size).to eq(10)
+      end
+    end
+  end
+
+  describe '.traced_method' do
+    context 'for non-traced methods' do
+      it 'does not interfere' do
+        expect(subject.a_non_traced_method).to eq(:non_traced_return_value)
+        expect(subject.non_traced_called).to eq(true)
+      end
+    end
+
+    context 'for traced methods' do
+      it 'does not interfere' do
+        expect(subject.a_traced_method).to eq(:traced_return_value)
+        expect(subject.traced_called).to eq(true)
+      end
+
+      it 'emits a log entry at start and end' do
+        subject.a_traced_method
+        expect(logs.size).to be(2)
+        expect(logs[0][:tags].key?(:enter)).to be(true)
+        expect(logs[1][:tags].key?(:exit)).to be(true)
+      end
+
+      it 'catches and raises exceptions' do
+        expect { subject.a_traced_method { raise 'oops' } }.to raise_error('oops')
+        expect(logs.size).to be(2)
+        expect(logs[0][:tags].key?(:enter)).to be(true)
+        expect(logs[1][:tags].key?(:exception)).to be(true)
+        expect(logs[1][:tags].key?(:elapsed)).to be(true)
+        expect(logs[1][:tags].key?(:backtrace)).to be(true)
+      end
+
+      it 'catches and raises exceptions through nested blocks' do
+        expect do
+          subject.trace 'level one' do
+            subject.a_traced_method do
+              subject.trace 'level two' do
+                raise 'oops'
+              end
+            end
+          end
+        end.to raise_error('oops')
+
+        origin = logs.find { |log| log[:tags][:exception] && log[:tags][:message].include?('level two') }
+        expect(origin[:tags].key?(:backtrace)).to be(true)
+
+        middle = logs.find { |log| log[:tags][:exception] && log[:tags][:message].include?('a_traced_method') }
+        expect(middle[:tags].key?(:backtrace)).to be(false)
+        expect(middle[:tags][:message].include?('propagated')).to be(true)
+
+        outer = logs.find { |log| log[:tags][:exception] && log[:tags][:message].include?('level one') }
+        expect(outer[:tags].key?(:backtrace)).to be(false)
+        expect(middle[:tags][:message].include?('propagated')).to be(true)
+      end
+
+      it 'properly passes a block through' do
+        yielded = false
+        subject.a_traced_method do
+          yielded = true
+        end
+        expect(yielded).to eq(true)
+      end
+
+      it 'properly passes a block with args through' do
+        yielded = false
+        subject.a_traced_method_that_calls_a_block_with_a_parameter(:blah) do |val|
+          yielded = val
+        end
+        expect(yielded).to eq(:blah)
+      end
+    end
+  end
+
+  describe Traceable::Tracer do
+    describe '#default_parent' do
+      class One
+        include Traceable
+        def initialize
+          init_tracer tags: { one: true }
+        end
+
+        traced_method def first
+          Two.new.second
+          Thread.new { Two.new.second }.join # New thread --> don't inherit tracer context
+        end
+      end
+
+      class Two
+        def second
+          Three.new.third
+        end
+      end
+
+      class Three
+        include Traceable
+        traced_method def third
+          trace 'in the third', three: true
+        end
+      end
+
+      it 'should include tags from the default parent' do
+        One.new.first
+        # expected logs:
+        # 0 START: One#first, :one => true
+        # 1   START: Three#third, :one => true, :three => true
+        # 2     'in the third', :one => true, :three => true
+        # 3   END: Three#third
+        # 4   START: Three#third, :three => true
+        # 5     'in the third', :three => true
+        # 6   END: Three#third
+        # 7 END: One#first, :one => true
+        expect(logs.count).to be(8)
+
+        expect(logs[1][:tags].key?(:one)).to be(true)
+        expect(logs[2][:tags].key?(:one)).to be(true)
+        expect(logs[1][:tags][:trace]).to eq(logs[0][:tags][:trace]) # Same parent, same trace tag
+
+        expect(logs[4][:tags].key?(:one)).to be(false)
+        expect(logs[5][:tags].key?(:one)).to be(false)
+        expect(logs[4][:tags][:trace]).to_not eq(logs[1][:tags][:trace]) # Diff parent, diff trace tag
+      end
+    end
+
+    describe '#initialize' do
+      it 'complains with invalid argument' do
+        expect { Traceable::Tracer.new('foo') }.to raise_error(ArgumentError)
+      end
+    end
+
+    describe '#emit_tags' do
+      context 'when logger chokes on the message' do
+        before do
+          allow(fake_logger).to receive(:info) { raise('blow chunks') }
+        end
+        it 'does not allow the exception to blow up' do
+          t = Traceable::Tracer.new(nil)
+          expect(t).to receive(:emit_tags).twice.and_call_original
+          t.info(message: 'just a test')
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: traceable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeremy Slade
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: wwtd
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+description: 
+email:
+- jeremy@jkslade.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/traceable.rb
+- lib/traceable/class_methods.rb
+- lib/traceable/config.rb
+- lib/traceable/tracer.rb
+- lib/traceable/version.rb
+- spec/spec_helper.rb
+- spec/traceable_spec.rb
+homepage: https://github.com/instructure/inst-jobs-statsd
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Instrument code with logging
+test_files:
+- spec/spec_helper.rb
+- spec/traceable_spec.rb