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



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

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



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

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


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

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



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

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


227
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
 
# File 'lib/pantheios/api.rb', line 227

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



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

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



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

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) 


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

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



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

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



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

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



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

def timestamp t

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

#trace(*args, &block) ⇒ Object

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



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

def trace *args, &block

	return nil unless tracing?

	trace_with_block_ 1, args, &block
end

#trace_b(b, &block) ⇒ Object 



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

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 



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

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



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

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) 


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

def tracing?

	severity_logged? :trace
end