Class: Startback::Audit::Trailer

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/startback/audit/trailer.rb

Overview

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.

Constant Summary collapse

DEFAULT_OPTIONS = 
{

  # Words used to stop dumping for, e.g., security reasons
  blacklist: "token password secret credential"

}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(device, options = {}) ⇒ Trailer

Returns a new instance of Trailer.



58
59
60
61
62
 
# File 'lib/startback/audit/trailer.rb', line 58

def initialize(device, options = {})
  @options = DEFAULT_OPTIONS.merge(options)
  @logger = ::Logger.new(device, 'daily')
  @logger.formatter = Support::LogFormatter.new
end

Instance Attribute Details

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



63
64
65
 
# File 'lib/startback/audit/trailer.rb', line 63

def logger
  @logger
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



63
64
65
 
# File 'lib/startback/audit/trailer.rb', line 63

def options
  @options
end

Instance Method Details

#call(runner, op) ⇒ Object 



65
66
67
68
69
70
71
72
73
 
# File 'lib/startback/audit/trailer.rb', line 65

def call(runner, op)
  result = nil
  time = Benchmark.realtime{ result = yield }
  logger.info(op_to_trail(op, time))
  result
rescue => ex
  logger.error(op_to_trail(op, time, ex))
  raise
end