Module: Oboe::API::Logging

Defined in:
lib/oboe/api/logging.rb

Overview

This modules provides the X-Trace logging facilities.

Instance Method Summary collapse

Instance Method Details

#log(layer, label, opts = {}) ⇒ Object

Public: Report an event in an active trace.

layer - The layer the reported event belongs to label - The label for the reported event. See API documentation for

reserved labels and usage.

opts - A hash containing key/value pairs that will be reported along

with this event (optional).

Example

log('logical_layer', 'entry')
log('logical_layer', 'info', { :list_length => 20 })
log('logical_layer', 'exit')

Returns nothing.



24
25
26
27
28
 
# File 'lib/oboe/api/logging.rb', line 24

def log(layer, label, opts = {})
  if Oboe.loaded
    log_event(layer, label, Oboe::Context.createEvent, opts)
  end
end

#log_end(layer, opts = {}) ⇒ Object

Public: Report an exit event.

layer - The layer the reported event belongs to

Returns an xtrace metadata string



108
109
110
111
112
113
114
115
 
# File 'lib/oboe/api/logging.rb', line 108

def log_end(layer, opts = {})
  if Oboe.loaded
    log_event(layer, 'exit', Oboe::Context.createEvent, opts)
    xtrace = Oboe::Context.toString
    Oboe::Context.clear unless Oboe.has_incoming_context?
    xtrace
  end
end

#log_entry(layer, kvs = {}, op = nil) ⇒ Object

Public: Log an entry event

A helper method to create and log an entry event

Returns an xtrace metadata string



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

def log_entry(layer, kvs = {}, op = nil)
  if Oboe.loaded
    Oboe.layer_op = op if op
    log_event(layer, 'entry', Oboe::Context.createEvent, kvs)
  end
end

#log_event(layer, label, event, opts = {}) ⇒ Object

Internal: Report an event.

layer - The layer the reported event belongs to label - The label for the reported event. See API documentation for

reserved labels and usage.

opts - A hash containing key/value pairs that will be reported along

with this event (optional).

Examples

entry = Oboe::Context.createEvent
log_event('rails', 'entry', exit, { :controller => 'user', :action => 'index' })
exit = Oboe::Context.createEvent
exit.addEdge(entry.getMetadata)
log_event('rails', 'exit', exit)

Returns nothing.



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/oboe/api/logging.rb', line 175

def log_event(layer, label, event, opts = {})
  if Oboe.loaded
    event.addInfo('Layer', layer.to_s) if layer
    event.addInfo('Label', label.to_s)

    Oboe.layer = layer if label == 'entry'
    Oboe.layer = nil   if label == 'exit'

    opts.each do |k, v|
      value = nil

      if valid_key? k
        if [Integer, Float, Fixnum, NilClass, String].include?(v.class)
          value = v
        elsif v.class == Set
          value = v.to_a.to_s
        else
          value = v.to_s if v.respond_to?(:to_s)
        end

        begin
          event.addInfo(k.to_s, value)
        rescue ArgumentError => e
          Oboe.logger.debug "[oboe/debug] Couldn't add event KV: #{k.to_s} => #{v.class}"
        end
      end
    end if !opts.nil? && opts.any?

    Oboe::Reporter.sendReport(event)
  end
end

#log_exception(layer, exn) ⇒ Object

Public: Report an exception.

layer - The layer the reported event belongs to exn - The exception to report

Example

begin
  function_without_oboe()
rescue Exception => e
  log_exception('rails', e)
  raise
end

Returns nothing.



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/oboe/api/logging.rb', line 45

def log_exception(layer, exn)
  return if !Oboe.loaded || exn.instance_variable_get(:@oboe_logged)

  kvs = { :ErrorClass => exn.class.name,
          :ErrorMsg => exn.message,
          :Backtrace => exn.backtrace.join("\r\n") }

  exn.instance_variable_set(:@oboe_logged, true)
  log(layer, 'error', kvs)
end

#log_exit(layer, kvs = {}, op = nil) ⇒ Object

Public: Log an exit event

A helper method to create and log an exit event

Returns an xtrace metadata string



151
152
153
154
155
156
 
# File 'lib/oboe/api/logging.rb', line 151

def log_exit(layer, kvs = {}, op = nil)
  if Oboe.loaded
    Oboe.layer_op = nil if op
    log_event(layer, 'exit', Oboe::Context.createEvent, kvs)
  end
end

#log_info(layer, kvs = {}) ⇒ Object

Public: Log an info event

A helper method to create and log an info event

Returns an xtrace metadata string



138
139
140
141
142
 
# File 'lib/oboe/api/logging.rb', line 138

def log_info(layer, kvs = {})
  if Oboe.loaded
    log_event(layer, 'info', Oboe::Context.createEvent, kvs)
  end
end

#log_start(layer, xtrace, opts = {}) ⇒ Object

Public: Decide whether or not to start a trace, and report an event appropriately.

layer - The layer the reported event belongs to xtrace - An xtrace metadata string, or nil. opts - A hash containing key/value pairs that will be reported along

with this event (optional).

Returns nothing.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/oboe/api/logging.rb', line 65

def log_start(layer, xtrace, opts = {})
  return if !Oboe.loaded || Oboe.never? ||
            (opts.key?(:URL) && ::Oboe::Util.static_asset?(opts[:URL]))

  Oboe::Context.fromString(xtrace) if Oboe.pickup_context?(xtrace)

  if Oboe.tracing?
    # Pre-existing context.  Either we inherited context from an
    # incoming X-Trace request header or under JRuby, Joboe started
    # tracing before the JRuby code was called (e.g. Tomcat)
    Oboe.is_continued_trace = true

    if Oboe.has_xtrace_header
      opts[:TraceOrigin] = :continued_header
    elsif Oboe.has_incoming_context
      opts[:TraceOrigin] = :continued_context
    else
      opts[:TraceOrigin] = :continued
    end

    log_entry(layer, opts)

  elsif opts.key?('Force')
    # Forced tracing: used by __Init reporting
    opts[:TraceOrigin] = :forced
    log_event(layer, 'entry', Oboe::Context.startTrace, opts)

  elsif Oboe.sample?(opts.merge(:layer => layer, :xtrace => xtrace))
    # Probablistic tracing of a subset of requests based off of
    # sample rate and sample source
    opts[:SampleRate]        = Oboe.sample_rate
    opts[:SampleSource]      = Oboe.sample_source
    opts[:TraceOrigin] = :always_sampled

    log_event(layer, 'entry', Oboe::Context.startTrace, opts)
  end
end