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/config_loader.rb,
lib/sapience/configuration.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/configuration/grape.rb,
lib/sapience/concerns/compatibility.rb,
lib/sapience/extensions/grape/timings.rb,
lib/sapience/extensions/grape/middleware/logging.rb

Overview

:nodoc:

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
"0.1.13"
LEVELS =

Logging levels in order of most detailed to most severe

[:trace, :debug, :info, :warn, :error, :fatal].freeze
DEFAULT_ENV = 
"default".freeze
@@configured = 
nil

Class Method Summary collapse

Class Method Details

.[](klass) ⇒ Object

Return a logger for the supplied class or class_name



80
81
82
 
# File 'lib/sapience/sapience.rb', line 80

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')



162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/sapience/sapience.rb', line 162

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_keys!
  appender_class = constantize_symbol(appender)
  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/" } },
)



181
182
183
184
185
186
187
 
# File 'lib/sapience/sapience.rb', line 181

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



208
209
210
 
# File 'lib/sapience/sapience.rb', line 208

def self.appenders
  @@appenders.clone
end

.camelize(term) ⇒ Object

Borrow from Rails, when not running Rails



368
369
370
371
372
373
374
375
376
 
# File 'lib/sapience/sapience.rb', line 368

def self.camelize(term) # rubocop:disable AbcSize
  string = term.to_s
  string = string.sub(/^[a-z\d]*/) { |match| match.capitalize }
  string.gsub!(/(?:_|(\/))([a-z\d]*)/i) do
    "#{Regexp.last_match[1]}#{inflections.acronyms[Regexp.last_match[2]] || Regexp.last_match[2].capitalize}"
  end
  string.gsub!("/".freeze, "::".freeze)
  string
end

.close ⇒ Object

Close and flush all appenders



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

def self.close
  Sapience::Logger.close
end

.config ⇒ Object 



27
28
29
30
31
32
33
34
 
# File 'lib/sapience/sapience.rb', line 27

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

Yields:



70
71
72
73
74
75
76
77
 
# File 'lib/sapience/sapience.rb', line 70

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

  config
end

.configured? ⇒ Boolean

Returns:

  • (Boolean) 


36
37
38
 
# File 'lib/sapience/sapience.rb', line 36

def self.configured?
  @@configured
end

.constantize(class_name) ⇒ Object 



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

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
end

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



351
352
353
354
355
356
 
# File 'lib/sapience/sapience.rb', line 351

def self.constantize_symbol(symbol, namespace = "Sapience::Appender")
  klass = "#{namespace}::#{camelize(symbol.to_s)}"
  constantize(klass)
rescue NameError
  raise(ArgumentError, "Could not convert symbol: #{symbol} to a class in: #{namespace}. Looking for: #{klass}")
end

.default_options(options = {}) ⇒ Object 



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

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

.environment ⇒ Object 



57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/sapience/sapience.rb', line 57

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



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

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



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

def self.flush
  Sapience::Logger.flush
end

.logger ⇒ Object 



224
225
226
 
# File 'lib/sapience/sapience.rb', line 224

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

.logger=(logger) ⇒ Object 



220
221
222
 
# File 'lib/sapience/sapience.rb', line 220

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

.metrix ⇒ Object 



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

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

.metrix=(metrix) ⇒ Object 



212
213
214
 
# File 'lib/sapience/sapience.rb', line 212

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

.named_tags(tag) ⇒ Object

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

Returns result of block

Example:



264
265
266
267
268
269
 
# File 'lib/sapience/sapience.rb', line 264

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

.pop_tags(quantity = 1) ⇒ Object

Remove specified number of tags from the current tag list



300
301
302
303
 
# File 'lib/sapience/sapience.rb', line 300

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



291
292
293
294
295
296
297
 
# File 'lib/sapience/sapience.rb', line 291

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.



193
194
195
 
# File 'lib/sapience/sapience.rb', line 193

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

.remove_appenders(appenders = @@appenders) ⇒ Object

Remove specific appenders or all existing



198
199
200
201
202
 
# File 'lib/sapience/sapience.rb', line 198

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



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

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 



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

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

.reset_appenders! ⇒ Object 



53
54
55
 
# File 'lib/sapience/sapience.rb', line 53

def self.reset_appenders!
  @@appenders = Concurrent::Array.new
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



341
342
343
344
345
346
347
 
# File 'lib/sapience/sapience.rb', line 341

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



274
275
276
277
278
279
 
# File 'lib/sapience/sapience.rb', line 274

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



283
284
285
286
287
 
# File 'lib/sapience/sapience.rb', line 283

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