Module: Pantheios::API

Defined in:
lib/pantheios/api.rb

Overview

This inclusion module specifies the main logging API methods, including:

  • log
  • log_v
  • trace
  • trace_v

as well as those that may be overridden:

  • severity_logged?

  • tracing?

  • prefix_elements

  • process_id

  • process_name

  • severity_string severity

  • thread_id

  • timestamp t

  • prefix_parts

  • prefix

Instance Method Summary collapse

Instance Method Details

#log(severity, *args, &block) ⇒ Object

Logs an arbitrary set of parameters at the given severity level



82
83
84
85
86
87
 
# File 'lib/pantheios/api.rb', line 82

def log severity, *args, &block

  return nil unless severity_logged? severity

  log_or_trace_with_block_ 1, severity, args, &block
end

#log_v(severity, argv, &block) ⇒ Object

Logs an array of parameters at the given severity level



90
91
92
93
94
95
 
# File 'lib/pantheios/api.rb', line 90

def log_v severity, argv, &block

  return nil unless severity_logged? severity

  log_or_trace_with_block_ 1, severity, argv, &block
end

#prefix(t, severity) ⇒ Object

Assembles the prefix_parts into a string

  • Parameters:
    • t [ Date, Time, DateTime ] The timestamp of the log entry
    • severity The severity


264
265
266
267
 
# File 'lib/pantheios/api.rb', line 264

def prefix t, severity

  prefix_parts(t, severity).join(', ')
end

#prefix_elements ⇒ Object

Defines the ordered list of log-statement elements

Elements

Elements can be one of:

- +:process_name+
- +:process_id+
- +:severity+
- +:thread_id+
- +:timestamp+

This is called from prefix



172
173
174
175
 
# File 'lib/pantheios/api.rb', line 172

def prefix_elements

  [ :process_name, :thread_id, :timestamp, :severity ]
end

#prefix_parts(t, severity) ⇒ Object

Assembles the prefix according to prefix_elements into an array of parts

  • Parameters:
    • t [ Date, Time, DateTime ] The timestamp of the log entry
    • severity The severity


228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/pantheios/api.rb', line 228

def prefix_parts t, severity

  prefix_elements.map do |el|

    case el
    when :program_name, :process_name

      process_name
    when :process_id

      process_id
    when :severity

      severity_string severity
    when :thread_id

      thread_id
    when :timestamp

      timestamp t
    else

      s = ::Symbol === el ? ":#{el}" : el.to_s

      warn "ignoring unrecognised prefix_element '#{s}'"

      nil
    end
  end
end

#process_id ⇒ Object

Obtains the process id

Unless overridden, returns the value provided by ::Pantheios::Core::process_id



181
182
183
184
 
# File 'lib/pantheios/api.rb', line 181

def process_id

  ::Pantheios::Core.process_id
end

#process_name ⇒ Object

Obtains the program name

Unless overridden, returns the value provided by ::Pantheios::Core::process_name



190
191
192
193
 
# File 'lib/pantheios/api.rb', line 190

def process_name

  ::Pantheios::Core.process_name
end

#severity_logged?(severity) ⇒ Boolean

Determines whether a given severity is logged

Signature

  • Parameters:

    - severity

    The severity level, which should be a known log

    severity symbol or an integral equivalent

  • Returns: a truey value if the severity should be logged; a falsey value otherwise

Returns:

  • (Boolean) 


145
146
147
148
 
# File 'lib/pantheios/api.rb', line 145

def severity_logged? severity

  ::Pantheios::Core.severity_logged? severity
end

#severity_string(severity) ⇒ Object

Obtains the string corresponding to the severity

Unless overridden, returns the value provided by ::Pantheios::Core::severity_string



199
200
201
202
 
# File 'lib/pantheios/api.rb', line 199

def severity_string severity

  ::Pantheios::Core.severity_string severity
end

#thread_id ⇒ Object

Obtains the thread id

Unless overridden, returns the value provided by ::Pantheios::Core::thread_id



208
209
210
211
 
# File 'lib/pantheios/api.rb', line 208

def thread_id

  ::Pantheios::Core.thread_id
end

#timestamp(t) ⇒ Object

Obtains a string-form of the timestamp

Unless overridden, returns the value provided by ::Pantheios::Core::timestamp



217
218
219
220
 
# File 'lib/pantheios/api.rb', line 217

def timestamp t

  ::Pantheios::Core.timestamp t, nil
end

#trace(*args, &block) ⇒ Object

Logs an arbitrary set of parameters at the Trace (:trace) level



98
99
100
101
102
103
 
# File 'lib/pantheios/api.rb', line 98

def trace *args, &block

  return nil unless tracing?

  trace_with_block_ 1, args, &block
end

#trace_b(b, &block) ⇒ Object 



125
126
127
128
129
130
 
# File 'lib/pantheios/api.rb', line 125

def trace_b b, &block

  return nil unless tracing?

  ::Pantheios::Core.trace_v_impl(self, 1, ApplicationLayer::ParamNameList[*b.local_variables], :trace, b.local_variables.map { |lv| b.local_variable_get(lv) }, &block)
end

#trace_blv(b, lvars, &block) ⇒ Object 



115
116
117
118
119
120
 
# File 'lib/pantheios/api.rb', line 115

def trace_blv b, lvars, &block

  return nil unless tracing?

  ::Pantheios::Core.trace_v_impl(self, 1, ApplicationLayer::ParamNameList[*lvars], :trace, lvars.map { |lv| b.local_variable_get(lv) }, &block)
end

#trace_v(argv, &block) ⇒ Object

Logs an array of parameters at the Trace (:trace) level



106
107
108
109
110
111
 
# File 'lib/pantheios/api.rb', line 106

def trace_v argv, &block

  return nil unless tracing?

  trace_with_block_ 1, argv, &block
end

#tracing? ⇒ Boolean

Determines whether tracing (severity == :trace) is enabled. This is used in the trace methods (+trace+, trace_v, trace_blv, trace_b) and therefore it may be overridden independently of severity_logged?

Returns:

  • (Boolean) 


153
154
155
156
 
# File 'lib/pantheios/api.rb', line 153

def tracing?

  severity_logged? :trace
end