Module: Sapience

Defined in:
lib/sapience/logger.rb,
lib/sapience/log.rb,
lib/sapience/base.rb,
lib/sapience/grape.rb,
lib/sapience/rails.rb,
lib/sapience/version.rb,
lib/sapience/loggable.rb,
lib/sapience/sapience.rb,
lib/sapience/sneakers.rb,
lib/sapience/subscriber.rb,
lib/sapience/ansi_colors.rb,
lib/sapience/descendants.rb,
lib/sapience/rails/engine.rb,
lib/sapience/config_loader.rb,
lib/sapience/configuration.rb,
lib/sapience/rails/railtie.rb,
lib/sapience/formatters/raw.rb,
lib/sapience/appender/sentry.rb,
lib/sapience/appender/stream.rb,
lib/sapience/formatters/base.rb,
lib/sapience/formatters/json.rb,
lib/sapience/appender/datadog.rb,
lib/sapience/appender/wrapper.rb,
lib/sapience/formatters/color.rb,
lib/sapience/formatters/default.rb,
lib/sapience/concerns/compatibility.rb,
lib/sapience/extensions/grape/timings.rb,
lib/sapience/extensions/grape/middleware/logging.rb,
lib/sapience/extensions/action_view/log_subscriber.rb,
lib/sapience/extensions/active_record/log_subscriber.rb,
lib/sapience/extensions/action_controller/log_subscriber.rb

Overview

:nodoc:

Defined Under Namespace

Modules: AnsiColors, Appender, Concerns, ConfigLoader, Descendants, Extensions, Formatters, Loggable, Rails, Sneakers Classes: Base, Configuration, Grape, Log, Logger, Subscriber

Constant Summary collapse

VERSION = 
"0.2.16"
UnknownClass = 
Class.new(NameError)
LEVELS =

Logging levels in order of most detailed to most severe

[:trace, :debug, :info, :warn, :error, :fatal].freeze
DEFAULT_ENV = 
"default".freeze
UnkownLogLevel = 
Class.new(StandardError)
InvalidLogExecutor = 
Class.new(StandardError)
@@configured = 
false

Class Method Summary collapse

Class Method Details

.[](klass) ⇒ Object

Return a logger for the supplied class or class_name



90
91
92
 
# File 'lib/sapience/sapience.rb', line 90

def self.[](klass)
  Sapience::Logger.new(klass)
end

.add_appender(appender, options = {}, _deprecated_level = nil, &_block) ⇒ Object

Add a new logging appender as a new destination for all log messages emitted from Sapience

Appenders will be written to in the order that they are added

If a block is supplied then it will be used to customize the format of the messages sent to that appender. See Sapience::Logger.new for more information on custom formatters

Parameters

file_name: [String]
  File name to write log messages to.

Or,
io: [IO]
  An IO Stream to log to.
  For example STDOUT, STDERR, etc.

Or,
appender: [Symbol|Sapience::Subscriber]
  A symbol identifying the appender to create.
  For example:
    :bugsnag, :elasticsearch, :graylog, :http, :mongodb, :new_relic, :splunk_http, :syslog, :wrapper
       Or,
  An instance of an appender derived from Sapience::Subscriber
  For example:
    Sapience::Appender::Http.new(url: 'http://localhost:8088/path')

Or,
logger: [Logger|Log4r]
  An instance of a Logger or a Log4r logger.

level: [:trace | :debug | :info | :warn | :error | :fatal]
  Override the log level for this appender.
  Default: Sapience.config.default_level

formatter: [Symbol|Object|Proc]
  Any of the following symbol values: :default, :color, :json
    Or,
  An instance of a class that implements #call
    Or,
  A Proc to be used to format the output from this appender
  Default: :default

filter: [Regexp|Proc]
  RegExp: Only include log messages where the class name matches the supplied.
  regular expression. All other messages will be ignored.
  Proc: Only include log messages where the supplied Proc returns true
        The Proc must return true or false.

Examples:

# Send all logging output to Standard Out (Screen)
Sapience.add_appender(:stream, io: STDOUT)

# Send all logging output to a file
Sapience.add_appender(:stream, file_name: 'logfile.log')

# Send all logging output to a file and only :info and above to standard output
Sapience.add_appender(:stream, file_name: 'logfile.log')
Sapience.add_appender(:stream, io: STDOUT, level: :info)

Log to log4r, Logger, etc.:

# Send logging output to an existing logger
require 'logger'
require 'sapience'

# Built-in Ruby logger
log = Logger.new(STDOUT)
log.level = Logger::DEBUG

Sapience.config.default_level = :debug
Sapience.add_appender(:wrapper, logger: log)

logger = Sapience['Example']
logger.info "Hello World"
logger.debug("Login time", user: 'Joe', duration: 100, ip_address: '127.0.0.1')



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/sapience/sapience.rb', line 172

def self.add_appender(appender, options = {}, _deprecated_level = nil, &_block)
  fail ArgumentError, "options should be a hash" unless options.is_a?(Hash)
  options.deep_symbolize_keyz!
  appender_class = constantize_symbol(appender)
  validate_appender!(appender_class)

  appender       = appender_class.new(options)
  @@appenders << appender

  # Start appender thread if it is not already running
  Sapience::Logger.start_appender_thread
  Sapience.logger = appender if appender.is_a?(Sapience::Appender::Stream)
  Sapience.metrix = appender if appender.is_a?(Sapience::Appender::Datadog)
  appender
end

.add_appenders(*appenders) ⇒ Object

Examples:

Sapience.add_appenders(
  { file: { io: STDOUT } },
  { sentry: { dsn: "https://app.getsentry.com/" } },
)



204
205
206
207
208
209
210
 
# File 'lib/sapience/sapience.rb', line 204

def self.add_appenders(*appenders)
  appenders.flatten.compact.each do |appender|
    appender.each do |name, options|
      add_appender(name, options)
    end
  end
end

.appenders ⇒ Object

Returns [Sapience::Subscriber] a copy of the list of active appenders for debugging etc. Use Sapience.add_appender and Sapience.remove_appender to manipulate the active appenders list



231
232
233
 
# File 'lib/sapience/sapience.rb', line 231

def self.appenders
  @@appenders.clone
end

.clear_tags! ⇒ Object 



313
314
315
 
# File 'lib/sapience/sapience.rb', line 313

def self.clear_tags!
  Thread.current[:sapience_tags] = []
end

.close ⇒ Object

Close and flush all appenders



262
263
264
 
# File 'lib/sapience/sapience.rb', line 262

def self.close
  Sapience::Logger.close
end

.config ⇒ Object

TODO: Should we really always read from file? What if someone wants to configure sapience with a block without reading the default.yml?



33
34
35
36
37
38
39
40
 
# File 'lib/sapience/sapience.rb', line 33

def self.config
  @@config ||= begin
    config    = ConfigLoader.load_from_file
    options   = config[environment]
    options ||= default_options(config)
    Configuration.new(options)
  end
end

.configure(force: false) {|config| ... } ⇒ Object

TODO: Maybe when configuring with a block we should create a new config? See the TODO note on .config for more information

Yields:



79
80
81
82
83
84
85
86
87
 
# File 'lib/sapience/sapience.rb', line 79

def self.configure(force: false)
  yield config if block_given?
  return config if configured? && force == false
  reset_appenders!
  add_appenders(*config.appenders)
  @@configured = true

  config
end

.configured? ⇒ Boolean

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/sapience/sapience.rb', line 42

def self.configured?
  @@configured
end

.constantize(class_name) ⇒ Object 



378
379
380
381
382
383
384
385
386
387
 
# File 'lib/sapience/sapience.rb', line 378

def self.constantize(class_name)
  return class_name unless class_name.is_a?(String)
  if RUBY_VERSION.to_i >= 2
    Object.const_get(class_name)
  else
    class_name.split("::").inject(Object) { |o, name| o.const_get(name) } # rubocop:disable SingleLineBlockParams
  end
rescue NameError
  raise UnknownClass, "Could not find class: #{class_name}."
end

.constantize_symbol(symbol, namespace = "Sapience::Appender") ⇒ Object 



373
374
375
376
 
# File 'lib/sapience/sapience.rb', line 373

def self.constantize_symbol(symbol, namespace = "Sapience::Appender")
  class_name = "#{namespace}::#{symbol.to_sym.camelize}"
  constantize(class_name)
end

.default_options(options = {}) ⇒ Object 



46
47
48
49
 
# File 'lib/sapience/sapience.rb', line 46

def self.default_options(options = {})
  warn "No configuration for environment #{environment}. Using 'default'"
  options[DEFAULT_ENV]
end

.environment ⇒ Object 



64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/sapience/sapience.rb', line 64

def self.environment
  ENV.fetch("RAILS_ENV") do
    ENV.fetch("RACK_ENV") do
      if defined?(::Rails) && ::Rails.respond_to?(:env)
        ::Rails.env
      else
        puts "Sapience is going to use default configuration"
        DEFAULT_ENV
      end
    end
  end
end

.fast_tag(tag) ⇒ Object

If the tag being supplied is definitely a string then this fast tag api can be used for short lived tags



278
279
280
281
282
283
 
# File 'lib/sapience/sapience.rb', line 278

def self.fast_tag(tag)
  (Thread.current[:sapience_tags] ||= []) << tag
  yield
ensure
  Thread.current[:sapience_tags].pop
end

.flush ⇒ Object

Wait until all queued log messages have been written and flush all active appenders



257
258
259
 
# File 'lib/sapience/sapience.rb', line 257

def self.flush
  Sapience::Logger.flush
end

.known_appenders ⇒ Object 



195
196
197
 
# File 'lib/sapience/sapience.rb', line 195

def self.known_appenders
  @_known_appenders ||= Sapience::Subscriber.descendants
end

.log_executor_class ⇒ Object 



369
370
371
 
# File 'lib/sapience/sapience.rb', line 369

def self.log_executor_class
  constantize_symbol(config.log_executor, "Concurrent")
end

.logger ⇒ Object 



247
248
249
 
# File 'lib/sapience/sapience.rb', line 247

def self.logger
  @@logger ||= Sapience::Logger.logger
end

.logger=(logger) ⇒ Object 



243
244
245
 
# File 'lib/sapience/sapience.rb', line 243

def self.logger=(logger)
  @@logger = Sapience::Logger.logger = logger
end

.metrix ⇒ Object 



239
240
241
 
# File 'lib/sapience/sapience.rb', line 239

def self.metrix
  @@metrix ||= Sapience.add_appender(:datadog)
end

.metrix=(metrix) ⇒ Object 



235
236
237
 
# File 'lib/sapience/sapience.rb', line 235

def self.metrix=(metrix)
  @@metrix = metrix
end

.pop_tags(quantity = 1) ⇒ Object

Remove specified number of tags from the current tag list



318
319
320
321
 
# File 'lib/sapience/sapience.rb', line 318

def self.pop_tags(quantity = 1)
  t = Thread.current[:sapience_tags]
  t.pop(quantity) unless t.nil?
end

.push_tags(*tags) ⇒ Object

Add tags to the current scope Returns the list of tags pushed after flattening them out and removing blanks



305
306
307
308
309
310
311
 
# File 'lib/sapience/sapience.rb', line 305

def self.push_tags(*tags)
  # Need to flatten and reject empties to support calls from Rails 4
  new_tags                       = tags.flatten.collect(&:to_s).reject(&:empty?)
  t                              = Thread.current[:sapience_tags]
  Thread.current[:sapience_tags] = t.nil? ? new_tags : t.concat(new_tags)
  new_tags
end

.remove_appender(appender) ⇒ Object

Remove an existing appender Currently only supports appender instances TODO: Make it possible to remove appenders by type Maybe create a concurrent collection that allows this by inheriting from concurrent array.



216
217
218
 
# File 'lib/sapience/sapience.rb', line 216

def self.remove_appender(appender)
  @@appenders.delete(appender)
end

.remove_appenders(appenders = @@appenders) ⇒ Object

Remove specific appenders or all existing



221
222
223
224
225
 
# File 'lib/sapience/sapience.rb', line 221

def self.remove_appenders(appenders = @@appenders)
  appenders.each do |appender|
    remove_appender(appender)
  end
end

.reopen ⇒ Object

After forking an active process call Sapience.reopen to re-open any open file handles etc to resources

Note: Only appenders that implement the reopen method will be called



270
271
272
273
274
 
# File 'lib/sapience/sapience.rb', line 270

def self.reopen
  @@appenders.each { |appender| appender.reopen if appender.respond_to?(:reopen) }
  # After a fork the appender thread is not running, start it if it is not running
  Sapience::Logger.start_appender_thread
end

.reset! ⇒ Object 



51
52
53
54
55
56
57
58
 
# File 'lib/sapience/sapience.rb', line 51

def self.reset!
  @@config = nil
  @@logger = nil
  @@metrix = nil
  @@configured = false
  clear_tags!
  reset_appenders!
end

.reset_appenders! ⇒ Object 



60
61
62
 
# File 'lib/sapience/sapience.rb', line 60

def self.reset_appenders!
  @@appenders = Concurrent::Array.new
end

.root ⇒ Object 



389
390
391
 
# File 'lib/sapience/sapience.rb', line 389

def self.root
  @_root ||= Gem::Specification.find_by_name("sapience").gem_dir
end

.silence(new_level = :error) ⇒ Object

Silence noisy log levels by changing the default_level within the block

This setting is thread-safe and only applies to the current thread

Any threads spawned within the block will not be affected by this setting

#silence can be used to both raise and lower the log level within the supplied block.

Example:

# Perform trace level logging within the block when the default is higher
Sapience.config.default_level = :info

logger.debug 'this will _not_ be logged'

Sapience.silence(:trace) do
  logger.debug "this will be logged"
end

Parameters

new_level
  The new log level to apply within the block
  Default: :error

Example:

# Silence all logging for this thread below :error level
Sapience.silence do
  logger.info "this will _not_ be logged"
  logger.warn "this neither"
  logger.error "but errors will be logged"
end

Note:

#silence does not affect any loggers which have had their log level set
explicitly. I.e. That do not rely on the global default level



359
360
361
362
363
364
365
 
# File 'lib/sapience/sapience.rb', line 359

def self.silence(new_level = :error)
  current_index                     = Thread.current[:sapience_silence]
  Thread.current[:sapience_silence] = Sapience.config.level_to_index(new_level)
  yield
ensure
  Thread.current[:sapience_silence] = current_index
end

.tagged(*tags) ⇒ Object

Add the supplied tags to the list of tags to log for this thread whilst the supplied block is active. Returns result of block



288
289
290
291
292
293
 
# File 'lib/sapience/sapience.rb', line 288

def self.tagged(*tags)
  new_tags = push_tags(*tags)
  yield self
ensure
  pop_tags(new_tags.size)
end

.tags ⇒ Object

Returns a copy of the [Array] of [String] tags currently active for this thread Returns nil if no tags are set



297
298
299
300
301
 
# File 'lib/sapience/sapience.rb', line 297

def self.tags
  # Since tags are stored on a per thread basis this list is thread-safe
  t = Thread.current[:sapience_tags]
  t.nil? ? [] : t.clone
end

.test_exception(level = :error) ⇒ Object 



251
252
253
 
# File 'lib/sapience/sapience.rb', line 251

def self.test_exception(level = :error)
  Sapience[self].public_send(level, Exception.new("Sapience Test Exception"))
end

.validate_appender!(appender) ⇒ Object 



188
189
190
191
192
193
 
# File 'lib/sapience/sapience.rb', line 188

def self.validate_appender!(appender)
  return if known_appenders.include?(appender)

  fail NotImplementedError,
    "Unknown appender '#{appender}'. Supported appenders are (#{known_appenders.join(", ")})"
end