startback 0.17.4 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d9b3532828f0cd3b82d8a2df96cd5343b98d1c3c55c8c6d3dd1402c24fbbcd8
-  data.tar.gz: e7b19db3af487c0c725e35b923c136dad05daa7b2c0be829dc91ab3be01fe885
+  metadata.gz: b78dea8794d36995b6941280807a9766deae9604d00ef51f96f88a9f06206142
+  data.tar.gz: 95457f1df4d0a3d6341414a17cfb3da56c7c3ad89466322b78e0fd2d9ab049a8
 SHA512:
-  metadata.gz: bb5bfea0e5dec4b691fc908260f9af6bb42bdd829954673dd00adc83433fd3bb2ceee01430045ec4b263230a4f4072f00268d8d189bf2c636de8cf7bd129a1b1
-  data.tar.gz: c28211dca05b881de6d3368152234a7e9b331eda5355d21c57c27a8860a45dc4f45cd730203d02c94d4411da6a784c7fbb356a1129e6530ff6f7b37c93196d90
+  metadata.gz: 3c08dc7d170c6a3baf9889a050ae0f239dee3d9cd0d8d3f8952b778026f8f1fd1a72979143bc553cf2b8bc16df816a14618bab067f924d4eb0f28774484685a5
+  data.tar.gz: 66547cfef8f9d27f0b9e45d4781fc0db225d753d610bbb95c7e1856bf006fedc48bec30753da0ac10607f4af0219f340db01da2b151f79c3257add9723c23a61

data/lib/startback/audit/ext/context.rb

@@ -0,0 +1,35 @@
+module Startback
+  class Context
+    attr_accessor :tracer
+
+    def tracer
+      @tracer ||= Audit::Tracer.empty.on_span(
+        Audit::TraceLogger.new(logger)
+      )
+    end
+
+    def trace_span(attributes = {}, &block)
+      @tracer = tracer.new_trace unless tracer.attached?
+      tracer.fork(attributes, &block)
+    end
+
+    h_dump do |h|
+      next unless tracer.attached?
+
+      last_span = tracer.last_span!
+      h.merge!("tracing" => {
+        "trace_id" => last_span.trace_id,
+        "span_id" => last_span.span_id,
+        "parent_id" => last_span.parent_id,
+      })
+    end
+
+    h_factory do |c, h|
+      next unless h['tracing']
+
+      trace_id = h['tracing']['trace_id']
+      span_id = h['tracing']['span_id']
+      c.tracer = c.tracer.attach_to(trace_id, span_id)
+    end
+  end # class Context
+end # module Startback

data/lib/startback/audit/ext.rb

@@ -0,0 +1 @@
+require_relative 'ext/context'

data/lib/startback/audit/middleware.rb

@@ -0,0 +1,30 @@
+module Startback
+  module Audit
+    class Middleware
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        context = ::Startback::Context::Middleware.context(env)
+
+        # attach to the existing trace if any
+        trace_id = env['HTTP_X_TRACE_ID']
+        span_id = env['HTTP_X_SPAN_ID']
+        context.tracer = context.tracer.attach_to(trace_id, span_id) if trace_id && span_id
+
+        # trace it!
+        context.trace_span({
+          :type => :request_handler,
+          :method => env['REQUEST_METHOD'],
+          :path => env['PATH_INFO'],
+          :qs => env['QUERY_STRING']
+        }) do
+          @app.call(env)
+        end
+      end
+
+    end # class Middleware
+  end # module Audit
+end # module Startback

data/lib/startback/audit/null_tracer.rb

@@ -0,0 +1,31 @@
+module Startback
+  module Audit
+    class NullTracer
+
+      def attached?
+        false
+      end
+
+      def last_span!
+        nil
+      end
+
+      def new_trace(*args)
+        self
+      end
+
+      def attach_to(*args)
+        self
+      end
+
+      def fork(*args)
+        yield
+      end
+
+      def on_span(listener = nil, &block)
+        self
+      end
+
+    end # class NullTracer
+  end # module Audit
+end # module Startback

data/lib/startback/audit/operation_tracer.rb

@@ -0,0 +1,19 @@
+require 'startback/audit'
+
+module Startback
+  module Audit
+    class OperationTracer
+      include Startback::Audit::Shared
+
+      def call(runner, op, &block)
+        op.context.trace_span({
+          type: :operation,
+          op: op_name(op),
+          data: op_data(op),
+          context: op_context(op)
+        }, &block)
+      end
+
+    end # class OperationTracer
+  end # module Audit
+end # module Startback

data/lib/startback/audit/shared.rb

@@ -12,6 +12,24 @@ module Startback
         end
       end
 
+      def op_context(op)
+        op.respond_to?(:context, false) ? op.context.to_h : {}
+      end
+
+      def op_data(op)
+        if op.respond_to?(:op_data, false)
+          op.op_data
+        elsif op.respond_to?(:to_trail, false)
+          op.to_trail
+        elsif op.respond_to?(:input, false)
+          op.input
+        elsif op.respond_to?(:request, false)
+          op.request
+        elsif op.is_a?(Operation::MultiOperation)
+          op.ops.map{ |sub_op| op_to_trail(sub_op) }
+        end
+      end
+
     end # module Shared
   end # module Audit
 end # module Startback

data/lib/startback/audit/span.rb

@@ -0,0 +1,66 @@
+module Startback
+  module Audit
+    class Span
+
+      def initialize(trace_id, parent_id, attributes = {}, span_id = SecureRandom.uuid)
+        @trace_id, @parent_id = trace_id, parent_id
+        @span_id = span_id
+        @attributes = attributes
+        @status = 'unknown'
+        @at = (Time.now.to_f*1000).to_i
+        @timing = nil
+        @error = nil
+      end
+      attr_reader :trace_id, :parent_id, :span_id, :status, :attributes, :timing, :error
+
+      def finished?
+        @status != 'unknown'
+      end
+
+      def success?
+        @status == 'success'
+      end
+
+      def error?
+        @status == 'error'
+      end
+
+      def fork(attributes = {})
+        Span.new(@trace_id, @span_id, attributes)
+      end
+
+      def finish(timing, error = nil)
+        @timing = timing
+        @status = error ? 'error' : 'success'
+        @error = error
+        self
+      end
+
+      def to_h
+        {
+          :spanId => span_id,
+          :traceId => trace_id,
+          :parentId => parent_id,
+          :status => status,
+          :timing => timing_to_h,
+          :attributes => attributes,
+          :error => error,
+        }.compact
+      end
+
+      def timing_to_h
+        {
+          at: @at,
+          total: @timing&.total,
+          real: @timing&.real,
+        }.compact
+      end
+      private :timing_to_h
+
+      def to_json(*args, &block)
+        to_h.to_json(*args, &block)
+      end
+
+    end # class Span
+  end # module Audit
+end # module Startback

data/lib/startback/audit/trace_logger.rb

@@ -0,0 +1,30 @@
+module Startback
+  module Audit
+    class TraceLogger
+
+      def initialize(logger = default_logger)
+        @logger = logger || default_logger
+        @logger.formatter ||= Support::LogFormatter.new if @logger.respond_to?(:formatter=)
+      end
+
+      def call(span)
+        if !span.finished?
+          @logger.debug(span.to_h)
+        elsif span.success?
+          @logger.info(span.to_h)
+        elsif span&.error.is_a?(Startback::Errors::BadRequestError)
+          @logger.warn(span.to_h)
+        else
+          @logger.error(span.to_h)
+        end
+      end
+
+    private
+
+      def default_logger
+        ::Logger.new(STDOUT, 'daily')
+      end
+
+    end # class TraceLogger
+  end # module Audit
+end # module Startback

data/lib/startback/audit/tracer.rb

@@ -0,0 +1,85 @@
+require 'securerandom'
+require 'benchmark'
+
+module Startback
+  module Audit
+    class Tracer
+
+      def initialize(stack = [], listeners = [], redactor = default_redactor)
+        @stack = stack
+        @listeners = listeners
+        @redactor = redactor
+      end
+      attr_reader :stack
+
+      def self.empty
+        Tracer.new
+      end
+
+      def attached?
+        !@stack.empty?
+      end
+
+      def last_span!
+        error!("Trace not attached") unless attached?
+
+        @stack.last
+      end
+
+      def new_trace(attributes = {})
+        error!("Trace already attached") if attached?
+
+        attach_to(SecureRandom.uuid, SecureRandom.uuid, attributes)
+      end
+
+      def attach_to(trace_id, span_id, attributes = {}, parent_id = nil)
+        error!("Trace already attached") if attached?
+
+        initial_span = Span.new(trace_id, parent_id, attributes, span_id)
+        initial_stack = [ initial_span ]
+        Tracer.new(initial_stack, @listeners, @redactor)
+      end
+
+      def fork(attributes = {}, &block)
+        span = last_span!.fork(@redactor.redact(attributes))
+        @stack << span
+        propagate_to_listeners(span)
+        result, error = nil, nil
+        timing = Benchmark.measure do
+          result, error = exec_block_with_error_handling(block)
+        end
+        span = @stack.pop.finish(timing, error)
+        propagate_to_listeners(span)
+        error ? raise(error) : result
+      end
+
+      def on_span(listener = nil, &block)
+        @listeners << (listener || block)
+        self
+      end
+
+    private
+
+      def default_redactor
+        Support::Redactor.new
+      end
+
+      def exec_block_with_error_handling(block)
+        [ block.call, nil ]
+      rescue => ex
+        [ nil, ex ]
+      end
+
+      def error!(msg)
+        raise Startback::Errors::InternalServerError, msg
+      end
+
+      def propagate_to_listeners(span)
+        @listeners.each do |listener|
+          listener.call(span)
+        end
+      end
+
+    end # class Tracer
+  end # module Audit
+end # module Startback

data/lib/startback/audit.rb

@@ -1,3 +1,9 @@
+require_relative 'audit/ext'
 require_relative 'audit/shared'
-require_relative 'audit/trailer'
 require_relative 'audit/prometheus'
+require_relative 'audit/span'
+require_relative 'audit/null_tracer'
+require_relative 'audit/tracer'
+require_relative 'audit/operation_tracer'
+require_relative 'audit/trace_logger'
+require_relative 'audit/middleware'

data/lib/startback/context/h_factory.rb

@@ -2,6 +2,11 @@ module Startback
   class Context
     module HFactory
 
+      def inherited(subclass)
+        subclass.h_factories = h_factories.dup if h_factories?
+        subclass.h_dumpers = h_dumpers.dup if h_dumpers?
+      end
+
       def h(hash)
         h_factor!(self.new, hash)
       end
@@ -13,6 +18,14 @@ module Startback
         context
       end
 
+      def h_factories?
+        !!@h_factories && @h_factories.any?
+      end
+
+      def h_factories=(factories)
+        @h_factories = factories
+      end
+
       def h_factories
         @h_factories ||= []
       end
@@ -30,10 +43,18 @@ module Startback
         hash
       end
 
+      def h_dumpers?
+        !!@h_dumpers && @h_dumpers.any?
+      end
+
       def h_dumpers
         @h_dumpers ||= []
       end
 
+      def h_dumpers=(dumpers)
+        @h_dumpers = dumpers
+      end
+
       def h_dump(&dumper)
         h_dumpers << dumper
       end

data/lib/startback/context.rb

@@ -24,7 +24,7 @@ module Startback
   #           h.merge!("foo" => foo)
   #         end
   #
-  #         h_factor do |c,h|
+  #         h_factory do |c,h|
   #           c.foo = h["foo"]
   #         end
   #

data/lib/startback/support/fake_logger.rb

@@ -3,16 +3,27 @@ module Startback
     class FakeLogger < Logger
 
       def initialize(*args)
-        @last_msg = nil
+        @seen = []
+      end
+      attr_accessor :formatter
+      attr_reader :seen
+
+      def last_msg
+        seen.last
       end
-      attr_reader :last_msg
 
       [:debug, :info, :warn, :error, :fatal].each do |meth|
         define_method(meth) do |msg|
-          @last_msg = msg
-        end        
+          @seen << format(meth, msg)
+        end
+      end
+
+      def format(severity, message)
+        return message unless formatter
+
+        formatter.call(severity.to_s.upcase, Time.now, 'prognam', message)
       end
 
-    end # class Logger
+    end # class FakeLogger
   end # module Support
 end # module Startback

data/lib/startback/support/log_formatter.rb

@@ -2,16 +2,33 @@ module Startback
   module Support
     class LogFormatter
 
+      DEFAULT_OPTIONS = {
+        pretty_print: nil
+      }
+
+      def initialize(options = {})
+        @options = DEFAULT_OPTIONS.merge(options)
+        @options[:pretty_print] ||= auto_pretty_print
+      end
+
+      def pretty_print?
+        !!@options[:pretty_print]
+      end
+
       def call(severity, time, progname, msg)
         msg = { message: msg } if msg.is_a?(String)
         msg = { error: msg } if msg.is_a?(Exception)
-        {
+        data = {
           severity: severity,
           time: time
         }.merge(msg)
          .merge(error: error_to_json(msg[:error], severity))
          .compact
-         .to_json << "\n"
+        if pretty_print?
+          JSON.pretty_generate(data) << "\n"
+        else
+          data.to_json << "\n"
+        end
       end
 
       def error_to_json(error, severity = nil)
@@ -29,6 +46,12 @@ module Startback
         }.compact
       end
 
+    private
+
+      def auto_pretty_print
+        ENV['RACK_ENV'] != 'production'
+      end
+
     end # class LogFormatter
   end # module Support
 end # module Startback

data/lib/startback/support/redactor.rb

@@ -0,0 +1,40 @@
+module Startback
+  module Support
+    class Redactor
+
+      DEFAULT_OPTIONS = {
+
+        # Words used to stop dumping for, e.g., security reasons
+        blacklist: "token password secret credential email address"
+
+      }
+
+      def initialize(options = {})
+        @options = DEFAULT_OPTIONS.merge(options)
+      end
+
+      def redact(data)
+        case data
+        when Hash, OpenStruct
+          Hash[data.map{|(k,v)|
+            [k, (k.to_s =~ blacklist_rx) ? '---redacted---' : redact(v)]
+          }]
+        when Enumerable
+          data.map{|elm| redact(elm) }.compact
+        else
+          data
+        end
+      end
+
+    private
+
+      def blacklist_rx
+        @blacklist_rx ||= Regexp.new(
+          @options[:blacklist].split(/\s+/).join("|"),
+          Regexp::IGNORECASE
+        )
+      end
+
+    end # class Redactor
+  end # module Support
+end # module Startback

data/lib/startback/support.rb

@@ -15,6 +15,7 @@ module Startback
   end # module Support
 end # module Startback
 require_relative 'support/env'
+require_relative 'support/redactor'
 require_relative 'support/log_formatter'
 require_relative 'support/logger'
 require_relative 'support/robustness'

data/lib/startback/version.rb

@@ -1,8 +1,8 @@
 module Startback
   module Version
     MAJOR = 0
-    MINOR = 17
-    TINY  = 4
+    MINOR = 18
+    TINY  = 1
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"
 end

data/spec/spec_helper.rb

@@ -1,6 +1,7 @@
 require 'startback'
 require 'startback/event'
 require 'startback/support/fake_logger'
+require 'startback/audit'
 require 'rack/test'
 require 'ostruct'
 

data/spec/unit/audit/ext/test_context.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+module Startback
+  module Audit
+    describe "Context extension" do
+      subject do
+        context.to_h
+      end
+
+      context 'no tracing has been added' do
+        let(:context) do
+          Startback::Context.new
+        end
+
+        it 'has no tracing info' do
+          expect(subject).not_to have_key('tracing')
+        end
+
+        it 'does not break reloading a context if no tracing' do
+          subject = Startback::Context.h({})
+          expect(subject.tracer).to be_an_instance_of(Startback::Audit::Tracer)
+          expect(subject.tracer).not_to be_attached
+        end
+      end
+
+      context 'some tracing has been added and attached' do
+        let(:context) do
+          Startback::Context.new.dup do |c|
+            c.tracer = Tracer.empty.attach_to('some_trace_uuid', 'some_trace_parent_uuid')
+          end
+        end
+
+        it 'has tracing info' do
+          expect(subject).to have_key('tracing')
+          expect(subject['tracing']['trace_id']).to eql('some_trace_uuid')
+          expect(subject['tracing']['span_id']).to eql('some_trace_parent_uuid')
+        end
+
+        it 'helps reloading a tracer instance from h info' do
+          subject = Startback::Context.h('tracing' => {
+            'trace_id' => 'some_trace_uuid',
+            'parent_id' => 'some_trace_parent_uuid'
+          })
+          expect(subject.tracer).to be_an_instance_of(Startback::Audit::Tracer)
+          expect(subject.tracer).to be_attached
+        end
+      end
+
+      context 'some tracing has been added and attached on a subclass' do
+        let(:context) do
+          SubContext.new.dup do |c|
+            c.tracer = Tracer.empty.attach_to('some_trace_uuid', 'some_trace_parent_uuid')
+          end
+        end
+
+        it 'has tracing info' do
+          expect(context.tracer).to be_attached
+          expect(SubContext.h_factories.size).to eql(3)
+          expect(subject).to have_key('tracing')
+          expect(subject['tracing']['trace_id']).to eql('some_trace_uuid')
+          expect(subject['tracing']['span_id']).to eql('some_trace_parent_uuid')
+        end
+      end
+    end
+  end # module Audit
+end # module Startback

data/spec/unit/audit/test_middleware.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+module Startback
+  module Audit
+    describe Middleware do
+      include Rack::Test::Methods
+
+      def app
+        Rack::Builder.new do
+          use Startback::Context::Middleware
+          use Middleware
+          run ->(env) {
+            ctx = env[Startback::Context::Middleware::RACK_ENV_KEY]
+            attached = ctx.tracer.attached?
+            last_span = ctx.tracer.last_span!
+            [200, {
+              'tracer-attached' => attached,
+              'last-span' => last_span
+            }, 'ok']
+          }
+        end
+      end
+
+      context 'when not provided with tracing headers' do
+        it 'starts a new trace' do
+          get '/'
+          expect(last_response.status).to eql(200)
+          expect(last_response.headers['tracer-attached']).to eq(true)
+          expect(last_response.body).to eql("ok")
+        end
+
+        it 'creates a fresh new span' do
+          get '/'
+          expect(last_response.status).to eql(200)
+          expect(last_response.headers['last-span']).not_to be_nil
+          expect(last_response.body).to eql("ok")
+        end
+      end
+
+      context 'when provided with tracing headers' do
+        it 'does attach the tracer' do
+          header('X-Trace-Id', 'trace-id')
+          header('X-Span-Id', 'span-id')
+          get '/'
+          expect(last_response.status).to eql(200)
+          expect(last_response.headers['tracer-attached']).to eq(true)
+          expect(last_response.body).to eql("ok")
+        end
+
+        it 'does create a new span' do
+          header('X-Trace-Id', 'trace-id')
+          header('X-Span-Id', 'span-id')
+          get '/'
+          expect(last_response.status).to eql(200)
+
+          span = last_response.headers['last-span']
+          expect(span).not_to be_nil
+          expect(span.trace_id).to eq('trace-id')
+          expect(span.parent_id).to eq('span-id')
+          expect(span.span_id).not_to be_nil
+          expect(span.span_id).not_to eq('span-id')
+        end
+      end
+    end # describe Middleware
+  end # module Audit
+end # module Startback

data/spec/unit/audit/test_trace_logger.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+module Startback
+  module Audit
+    describe TraceLogger do
+
+      let(:fake_logger) do
+        Support::FakeLogger.new
+      end
+
+      let(:trace_logger) do
+        TraceLogger.new(fake_logger)
+      end
+
+      let(:tracer) do
+        Tracer.new.on_span(trace_logger)
+      end
+
+      it 'helps logging successes' do
+        attached = tracer.attach_to('trace', 'root-span')
+        attached.fork(foo: 'bar') do
+          "hello world"
+        end
+        expect(fake_logger.seen.size).to eql(2)
+        expect(fake_logger.seen.first).to match(/DEBUG/)
+        expect(fake_logger.seen.last).to match(/INFO/)
+      end
+
+      it 'helps logging user errors' do
+        attached = tracer.attach_to('trace', 'root-span')
+        attached.fork(foo: 'bar') do
+          raise Startback::Errors::ForbiddenError, "no such access granted"
+        end rescue nil
+        expect(fake_logger.seen.size).to eql(2)
+        expect(fake_logger.seen.first).to match(/DEBUG/)
+        expect(fake_logger.seen.last).to match(/WARN/)
+      end
+
+      it 'helps logging fatal errors' do
+        attached = tracer.attach_to('trace', 'root-span')
+        attached.fork(foo: 'bar') do
+          raise ArgumentError, "something bad"
+        end rescue nil
+        expect(fake_logger.seen.size).to eql(2)
+        expect(fake_logger.seen.first).to match(/DEBUG/)
+        expect(fake_logger.seen.last).to match(/ERROR/)
+      end
+
+    end
+  end
+end

data/spec/unit/audit/test_tracer.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+module Startback
+  module Audit
+    describe Tracer do
+
+      let(:spans_seen) do
+        []
+      end
+
+      subject do
+        Tracer.new.on_span do |span|
+          spans_seen << span
+        end
+      end
+
+      it 'clones the object on attach_to' do
+        expect(subject).not_to be_attached
+        attached = subject.attach_to('the-trace', 'root-span')
+        expect(attached).to be_a(Tracer)
+        expect(attached).not_to be(subject)
+        expect(attached).to be_attached
+        expect(subject).not_to be_attached
+      end
+
+      describe 'fork' do
+        it 'fails if not attached' do
+          expect(subject).not_to be_attached
+          expect {
+            subject.fork do
+              12
+            end
+          }.to raise_error(/attached/)
+        end
+
+        it 'returns the block result' do
+          attached = subject.attach_to('the-trace', 'root-span')
+          result = attached.fork do
+            'foo'
+          end
+          expect(result).to eql('foo')
+        end
+
+        it 'propagates spans to listeners' do
+          attached = subject.attach_to('the-trace', 'root-span')
+          result = attached.fork do
+            'foo'
+          end
+          expect(spans_seen.size).to eql(2)
+          expect(spans_seen.last).to be_a(Span)
+          expect(spans_seen.last.timing).not_to be_nil
+          expect(spans_seen.last).to be_finished
+          expect(spans_seen.last).to be_success
+          expect(spans_seen.last).not_to be_error
+        end
+
+        it 'reraises any error that occurs' do
+          attached = subject.attach_to('the-trace', 'root-span')
+          expect {
+            attached.fork do
+              raise ArgumentError, "An error"
+            end
+          }.to raise_error(ArgumentError)
+        end
+
+        it 'traces any error that occurs' do
+          attached = subject.attach_to('the-trace', 'root-span')
+          expect {
+            attached.fork do
+              raise ArgumentError, "An error"
+            end
+          }.to raise_error(ArgumentError)
+          expect(spans_seen.size).to eql(2)
+          expect(spans_seen.last).to be_a(Span)
+          expect(spans_seen.last.timing).not_to be_nil
+          expect(spans_seen.last).to be_finished
+          expect(spans_seen.last).not_to be_success
+          expect(spans_seen.last).to be_error
+          expect(spans_seen.last.error).to be_a(ArgumentError)
+        end
+      end
+
+      describe 'redacting' do
+        it 'applies by default' do
+          attached = subject.attach_to('the-trace', 'root-span')
+          result = attached.fork({
+            foo: 'bar',
+            password: 'baz',
+            repeatPassword: 'baz'
+          }) do
+            'foo'
+          end
+          expect(spans_seen.size).to eql(2)
+          expect(spans_seen.last).to be_a(Span)
+          expect(spans_seen.last.attributes).to eql({
+            foo: 'bar',
+            password: '---redacted---',
+            repeatPassword: '---redacted---'
+          })
+        end
+      end
+
+    end
+  end
+end
+

data/spec/unit/context/test_h_factory.rb

@@ -7,9 +7,11 @@ module Startback
       expect(Context.new.to_json).to eql("{}")
     end
 
-    it 'allows installing factories' do
-      expect(Context.h_factories).to be_empty
-      expect(SubContext.h_factories.size).to eql(2)
+    it 'allows installing factories and dumpers' do
+      expect(Context.h_factories.size).to eql(1)
+      expect(SubContext.h_factories.size).to eql(3)
+      expect(Context.h_dumpers.size).to eql(1)
+      expect(SubContext.h_dumpers.size).to eql(3)
     end
 
     it 'has a `to_h` information contract that works as expected' do

data/spec/unit/support/test_redactor.rb

@@ -0,0 +1,84 @@
+require 'spec_helper'
+
+module Startback
+  module Support
+    describe Redactor do
+
+      let(:redactor) do
+        Redactor.new
+      end
+
+      it 'applies default blacklists for security reasons' do
+        data = {
+          token: "will not be dumped",
+          a_token: "will not be dumped",
+          AToken: "will not be dumped",
+          password: "will not be dumped",
+          secret: "will not be dumped",
+          credentials: "will not be dumped",
+          foo: "bar"
+        }
+        expect(redactor.redact(data)).to eql({
+          token: "---redacted---",
+          a_token: "---redacted---",
+          AToken: "---redacted---",
+          password: "---redacted---",
+          secret: "---redacted---",
+          credentials: "---redacted---",
+          foo: "bar",
+        })
+      end
+
+      it 'applies default blacklists to data arrays too' do
+        data = [{
+          token: "will not be dumped",
+          a_token: "will not be dumped",
+          AToken: "will not be dumped",
+          password: "will not be dumped",
+          secret: "will not be dumped",
+          credentials: "will not be dumped",
+          foo: "bar"
+        }]
+        expect(redactor.redact(data)).to eql([{
+          token: "---redacted---",
+          a_token: "---redacted---",
+          AToken: "---redacted---",
+          password: "---redacted---",
+          secret: "---redacted---",
+          credentials: "---redacted---",
+          foo: "bar"
+        }])
+      end
+
+      it 'redacts recursively' do
+        data = [{
+          foo: "bar",
+          baz: {
+            password: 'will not be dumped'
+          }
+        }]
+        expect(redactor.redact(data)).to eql([{
+          foo: "bar",
+          baz: {
+            password: '---redacted---'
+          }
+        }])
+      end
+
+      it 'uses the stop words provided at construction' do
+        r = Redactor.new(blacklist: "hello and     world")
+        data = {
+          Hello: "bar",
+          World: "foo",
+          foo: "bar"
+        }
+        expect(r.redact(data)).to eql({
+          Hello: "---redacted---",
+          World: "---redacted---",
+          foo: "bar"
+        })
+      end
+
+    end # class Redactor
+  end # module Support
+end # module Startback

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: startback
 version: !ruby/object:Gem::Version
-  version: 0.17.4
+  version: 0.18.1
 platform: ruby
 authors:
 - Bernard Lambeau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-20 00:00:00.000000000 Z
+date: 2023-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -270,20 +270,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.21.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.22.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.21.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -382,9 +382,16 @@ files:
 - Rakefile
 - lib/startback.rb
 - lib/startback/audit.rb
+- lib/startback/audit/ext.rb
+- lib/startback/audit/ext/context.rb
+- lib/startback/audit/middleware.rb
+- lib/startback/audit/null_tracer.rb
+- lib/startback/audit/operation_tracer.rb
 - lib/startback/audit/prometheus.rb
 - lib/startback/audit/shared.rb
-- lib/startback/audit/trailer.rb
+- lib/startback/audit/span.rb
+- lib/startback/audit/trace_logger.rb
+- lib/startback/audit/tracer.rb
 - lib/startback/caching/entity_cache.rb
 - lib/startback/caching/no_store.rb
 - lib/startback/caching/store.rb
@@ -419,6 +426,7 @@ files:
 - lib/startback/support/log_formatter.rb
 - lib/startback/support/logger.rb
 - lib/startback/support/operation_runner.rb
+- lib/startback/support/redactor.rb
 - lib/startback/support/robustness.rb
 - lib/startback/support/transaction_manager.rb
 - lib/startback/support/transaction_policy.rb
@@ -436,8 +444,11 @@ files:
 - lib/startback/web/prometheus.rb
 - lib/startback/web/shield.rb
 - spec/spec_helper.rb
+- spec/unit/audit/ext/test_context.rb
+- spec/unit/audit/test_middleware.rb
 - spec/unit/audit/test_prometheus.rb
-- spec/unit/audit/test_trailer.rb
+- spec/unit/audit/test_trace_logger.rb
+- spec/unit/audit/test_tracer.rb
 - spec/unit/caching/test_entity_cache.rb
 - spec/unit/context/test_abstraction_factory.rb
 - spec/unit/context/test_dup.rb
@@ -454,6 +465,7 @@ files:
 - spec/unit/support/operation_runner/test_before_after_call.rb
 - spec/unit/support/test_data_object.rb
 - spec/unit/support/test_env.rb
+- spec/unit/support/test_redactor.rb
 - spec/unit/support/test_robusteness.rb
 - spec/unit/support/test_transaction_manager.rb
 - spec/unit/support/test_world.rb

data/lib/startback/audit/trailer.rb

@@ -1,132 +0,0 @@
-require_relative 'shared'
-require 'forwardable'
-module Startback
-  module Audit
-    #
-    # Log & Audit trail abstraction, that can be registered as an around
-    # hook on OperationRunner and as an actual logger on Context instances.
-    #
-    # The trail is outputted as JSON lines, using a Logger on the "device"
-    # passed at construction. The following JSON entries are dumped:
-    #
-    # - severity  : INFO or ERROR
-    # - time      : ISO8601 Datetime of operation execution
-    # - op        : class name of the operation executed
-    # - op_took   : Execution duration of the operation
-    # - op_data   : Dump of operation input data
-    # - context   : Execution context, through its `h` information contract (IC)
-    #
-    # Dumping of operation data follows the following duck typing conventions:
-    #
-    # - If the operation instance responds to `to_trail`, this data is taken
-    # - If the operation instance responds to `input`, this data is taken
-    # - If the operation instance responds to `request`, this data is taken
-    # - Otherwise op_data is a JSON null
-    #
-    # By contributing to the Context's `h` IC, users can easily dump information that
-    # makes sense (such as the operation execution requester).
-    #
-    # The class implements a sanitization process when dumping the context and
-    # operation data. Blacklisted words taken in construction options are used to
-    # prevent dumping hash keys that match them (insentively). Default stop words
-    # are equivalent to:
-    #
-    #     Trailer.new("/var/log/trail.log", {
-    #       blacklist: "token password secret credential"
-    #     })
-    #
-    # Please note that the sanitization process does not apply recursively if
-    # the operation data is hierarchic. It only applies to the top object of
-    # Hash and [Hash]. Use `Operation#to_trail` to fine-tune your audit trail.
-    #
-    # Given that this Trailer is intended to be used as around hook on an
-    # `OperationRunner`, operations that fail at construction time will not be
-    # trailed at all, since they can't be ran in the first place. This may lead
-    # to trails not containing important errors cases if operations check their
-    # input at construction time.
-    #
-    class Trailer
-      include Shared
-      extend Forwardable
-      def_delegators :@logger, :debug, :info, :warn, :error, :fatal
-
-      DEFAULT_OPTIONS = {
-
-        # Words used to stop dumping for, e.g., security reasons
-        blacklist: "token password secret credential"
-
-      }
-
-      def initialize(device, options = {})
-        @options = DEFAULT_OPTIONS.merge(options)
-        @logger = ::Logger.new(device, 'daily')
-        @logger.formatter = Support::LogFormatter.new
-      end
-      attr_reader :logger, :options
-
-      def call(runner, op)
-        result = nil
-        time = Benchmark.realtime{ result = yield }
-        logger.info(op_to_trail(op, time))
-        result
-      rescue Startback::Errors::BadRequestError => ex
-        logger.warn(op_to_trail(op, time, ex))
-        raise
-      rescue => ex
-        logger.error(op_to_trail(op, time, ex))
-        raise
-      end
-
-    protected
-
-      def op_to_trail(op, time = nil, ex = nil)
-        log_msg = {
-          op_took: time ? time.round(8) : nil,
-          op: op_name(op),
-          context: op_context(op),
-          op_data: op_data(op)
-        }.compact
-        log_msg[:error] = ex if ex
-        log_msg
-      end
-
-      def op_context(op)
-        sanitize(op.respond_to?(:context, false) ? op.context.to_h : {})
-      end
-
-      def op_data(op)
-        data = if op.respond_to?(:op_data, false)
-          op.op_data
-        elsif op.respond_to?(:to_trail, false)
-          op.to_trail
-        elsif op.respond_to?(:input, false)
-          op.input
-        elsif op.respond_to?(:request, false)
-          op.request
-        elsif op.is_a?(Operation::MultiOperation)
-          op.ops.map{ |sub_op| op_to_trail(sub_op) }
-        end
-        sanitize(data)
-      end
-
-      def sanitize(data)
-        case data
-        when Hash, OpenStruct
-          data.dup.delete_if{|k| k.to_s =~ blacklist_rx }
-        when Enumerable
-          data.map{|elm| sanitize(elm) }.compact
-        else
-          data
-        end
-      end
-
-      def blacklist_rx
-        @blacklist_rx ||= Regexp.new(
-          options[:blacklist].split(/\s+/).join("|"),
-          Regexp::IGNORECASE
-        )
-      end
-
-    end # class Trailer
-  end # module Audit
-end # module Startback

data/spec/unit/audit/test_trailer.rb

@@ -1,105 +0,0 @@
-require 'spec_helper'
-require 'startback/audit'
-module Startback
-  module Audit
-    describe Trailer do
-
-      let(:trailer) {
-        Trailer.new("/tmp/trail.log")
-      }
-
-      describe "op_name" do
-
-        def op_name(op, trailer = self.trailer)
-          trailer.send(:op_name, op)
-        end
-
-        it 'uses op_name in priority if provided' do
-          op = OpenStruct.new(op_name: "foo")
-          expect(op_name(op)).to eql("foo")
-        end
-      end
-
-      describe "op_data" do
-
-        def op_data(op, trailer = self.trailer)
-          trailer.send(:op_data, op)
-        end
-
-        it 'uses op_data in priority if provided' do
-          op = OpenStruct.new(op_data: { foo: "bar" }, input: 12, request: 13)
-          expect(op_data(op)).to eql({ foo: "bar" })
-        end
-
-        it 'uses to_trail then' do
-          op = OpenStruct.new(to_trail: { foo: "bar" }, input: 12, request: 13)
-          expect(op_data(op)).to eql({ foo: "bar" })
-        end
-
-        it 'uses input then' do
-          op = OpenStruct.new(input: { foo: "bar" }, request: 13)
-          expect(op_data(op)).to eql({ foo: "bar" })
-        end
-
-        it 'uses request then' do
-          op = OpenStruct.new(request: { foo: "bar" })
-          expect(op_data(op)).to eql({ foo: "bar" })
-        end
-
-        it 'applies default blacklists for security reasons' do
-          op = OpenStruct.new(input: {
-            token: "will not be dumped",
-            a_token: "will not be dumped",
-            AToken: "will not be dumped",
-            password: "will not be dumped",
-            secret: "will not be dumped",
-            credentials: "will not be dumped",
-            foo: "bar"
-          })
-          expect(op_data(op)).to eql({
-            foo: "bar"
-          })
-        end
-
-        it 'applies default blacklists to data arrays too' do
-          op = OpenStruct.new(input: [{
-            token: "will not be dumped",
-            a_token: "will not be dumped",
-            AToken: "will not be dumped",
-            password: "will not be dumped",
-            secret: "will not be dumped",
-            credentials: "will not be dumped",
-            foo: "bar"
-          }])
-          expect(op_data(op)).to eql([{
-            foo: "bar"
-          }])
-        end
-
-        it 'uses the stop words provided at construction' do
-          t = Trailer.new("/tmp/trail.log", blacklist: "hello and     world")
-          op = OpenStruct.new(request: { Hello: "bar", World: "foo", foo: "bar" })
-          expect(op_data(op, t)).to eql({ foo: "bar" })
-        end
-
-      end
-
-      describe "op_context" do
-
-        def op_context(op, trailer = self.trailer)
-          trailer.send(:op_context, op)
-        end
-
-        it 'applies default blacklists for security reasons' do
-          op = OpenStruct.new(context: {
-            token: "will not be dumped",
-            foo: "bar"
-          })
-          expect(op_context(op)).to eql({ foo: "bar" })
-        end
-
-      end
-
-    end
-  end
-end