Module: TraceView::API::Tracing

Defined in:
lib/traceview/api/tracing.rb

Overview

Provides the higher-level tracing interface for the API.

Instance Method Summary collapse

Instance Method Details

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

Public: Trace a given block of code which can start a trace depending on configuration and probability. Detect any exceptions thrown by the block and report errors.

When start_trace returns control to the calling context, the oboe context will be cleared.

layer - The layer the block of code belongs to. opts - A hash containing key/value pairs that will be reported along with the first event of this layer (optional).

Example

def handle_request(request, response)
  # ... code that modifies request and response ...
end

def handle_request_with_oboe(request, response)
  result, xtrace = start_trace('rails', request['X-Trace']) do
    handle_request(request, response)
  end
  result
rescue Exception => e
  xtrace = e.xtrace
ensure
  response['X-trace'] = xtrace
end

Returns a list of length two, the first element of which is the result of the block, and the second element of which is the oboe context that was set when the block completed execution.



77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/traceview/api/tracing.rb', line 77

def start_trace(layer, xtrace = nil, opts = {})
  log_start(layer, xtrace, opts)
  begin
    result = yield
  rescue Exception => e
    log_exception(layer, e)
    e.instance_variable_set(:@xtrace, log_end(layer))
    raise
  end
  xtrace = log_end(layer)

  [result, xtrace]
end

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

Public: Trace a given block of code which can start a trace depending on configuration and probability. Detect any exceptions thrown by the block and report errors. Insert the oboe metadata into the provided for later user.

The motivating use case for this is HTTP streaming in rails3. We need access to the exit event’s trace id so we can set the header before any work is done, and before any headers are sent back to the client.

layer - The layer the block of code belongs to. target - The target object in which to place the oboe metadata. opts - A hash containing key/value pairs that will be reported along with the first event of this layer (optional).

Example:

def handle_request(request, response)
  # ... code that does something with request and response ...
end

def handle_request_with_oboe(request, response)
  start_trace_with_target('rails', request['X-Trace'], response) do
    handle_request(request, response)
  end
end

Returns the result of the block.



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/traceview/api/tracing.rb', line 118

def start_trace_with_target(layer, xtrace, target, opts = {})
  log_start(layer, xtrace, opts)
  exit_evt = TraceView::Context.createEvent
  begin
    target['X-Trace'] = TraceView::Event.metadataString(exit_evt) if TraceView.tracing?
    yield
  rescue Exception => e
    log_exception(layer, e)
    raise
  ensure
    exit_evt.addEdge(TraceView::Context.get)
    log_event(layer, 'exit', exit_evt)
    TraceView::Context.clear
  end
end

#trace(layer, opts = {}, protect_op = nil) ⇒ Object

Public: Trace a given block of code. Detect any exceptions thrown by the block and report errors.

layer - The layer the block of code belongs to. opts - A hash containing key/value pairs that will be reported along with the first event of this layer (optional). protect_op - specify the operation being traced. Used to avoid double tracing between operations that call each other

Example

def computation(n)
  fib(n)
  raise Exception.new
end

def computation_with_oboe(n)
  trace('fib', { :number => n }) do
    computation(n)
  end
end

result = computation_with_oboe(1000)

Returns the result of the block.



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/traceview/api/tracing.rb', line 34

def trace(layer, opts = {}, protect_op = nil)
  log_entry(layer, opts, protect_op)
  begin
    yield
  rescue Exception => e
    log_exception(layer, e)
    raise
  ensure
    log_exit(layer, {}, protect_op)
  end
end