Class: Logrb

Inherits:
Object
  • Object
show all
Defined in:
lib/logrb.rb,
lib/logrb/version.rb

Overview

Logrb provides a facility for working with logs in text and json formats. All instances share a single mutex to ensure logging consistency. The following attributes are available:

fields - A hash containing metadata to be included in logs emitted by this

instance.

level - The level filter for the instance. Valid values are :error, :fatal,

:info, :warn, and :debug

format - The format to output logs. Supports :text and :json.

Each instance exposes the following methods, which accepts an arbitrary number of key-value pairs to be included in the logged message:

#error(msg, error=nil, **fields): Outputs an error entry. When ‘error` is

present, attempts to obtain backtrace information and also includes it
to the emitted entry.

#fatal(msg, **fields): Outputs a fatal entry. Calling fatal causes the

current process to exit with a status 1.

#warn(msg, **fields): Outputs a warning entry.

#info(msg, **fields): Outputs a informational entry.

#debug(msg, **fields): Outputs a debug entry.

#dump(msg, data=nil): Outputs a given String or Array of bytes using the

same format as `hexdump -C`.

Constant Summary collapse

COLORS = 
{
  error: 31,
  fatal: 31,
  unknown: 0,
  info: 36,
  warn: 33,
  debug: 30,
  reset: 0,
  dump: 37
}.freeze
BACKGROUNDS = 
{
  debug: 107
}.freeze
LEVELS = 
{
  error: 4,
  fatal: 4,
  unknown: 4,
  warn: 3,
  info: 2,
  debug: 1,
  reset: 1
}.freeze
VERSION = 
"0.1.5"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(output, format: :text, level: :debug, **fields) ⇒ Logrb

Initializes a new Logger instance that outputs logs to a provided output.

output - an IO-like object that implements a #write method. format - Optional. Indicates the format used to output log entries.

Supports :text (default) and :json.

level - Level to filter this logger instance fields - Fields to include in emitted entries



76
77
78
79
80
81
 
# File 'lib/logrb.rb', line 76

def initialize(output, format: :text, level: :debug, **fields)
  @output = output
  @format = format
  @fields = fields
  @level = level
end

Instance Attribute Details

#fields ⇒ Object

Returns the value of attribute fields.



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

def fields
  @fields
end

#format ⇒ Object

Returns the value of attribute format.



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

def format
  @format
end

#level ⇒ Object

Returns the value of attribute level.



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

def level
  @level
end

Class Method Details

.mutex ⇒ Object

Internal: A mutex instance used for synchronizing the usage of the output IO.



65
66
67
 
# File 'lib/logrb.rb', line 65

def self.mutex
  @mutex ||= Mutex.new
end

Instance Method Details

#dump(log, data = nil, **fields) ⇒ Object

Public: Dumps a given String or Array in the same format as ‘hexdump -C`.



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/logrb.rb', line 122

def dump(log, data = nil, **fields)
  return if LEVELS[@level] > LEVELS[:debug]

  if data.nil?
    data = log
    log = nil
  end

  data = data.pack("C*") if data.is_a? Array
  dump = []
  padding = @format == :json ? "" : "        "
  Hexdump.dump(data, output: dump)
  dump.map! { |line| "#{padding}#{line.chomp}" }
  dump = dump.join("\n")

  if @format == :json
    fields[:dump] = dump
    dump = nil
  end
  wrap(:dump, log || "", nil, fields)
  write_output("#{dump}\n\n") unless dump.nil?
end

#error(msg, error = nil, **fields) ⇒ Object

Public: Emits an error to the log output. When error is provided, this method attempts to gather a stacktrace to include in the emitted entry.



105
106
107
108
109
110
 
# File 'lib/logrb.rb', line 105

def error(msg, error = nil, **fields)
  return if LEVELS[@level] > LEVELS[:error]

  wrap(:error, msg, error, fields)
  nil
end

#fatal(msg, error = nil, **fields) ⇒ Object

Public: Emits a fatal message to the log output, and invokes Kernel#exit with a non-zero status code. When error is provided, this method attempts to gather a stacktrace to include in the emitted entry. This log entry cannot be filtered, and is always emitted.



116
117
118
119
 
# File 'lib/logrb.rb', line 116

def fatal(msg, error = nil, **fields)
  wrap(:fatal, msg, error, fields)
  exit 1
end

#with_fields(**fields) ⇒ Object

Returns a new logger instance using the same output of its parent’s, with an optional set of fields to be merged against the parent’s fields.

fields - A Hash containing metadata to be included in all output entries

emitted from the returned instance.



88
89
90
91
92
 
# File 'lib/logrb.rb', line 88

def with_fields(**fields)
  inst = Logrb.new(@output, format: @format, level: @level)
  inst.fields = @fields.merge(fields)
  inst
end