Module: Tracing

Defined in:
lib/tracing.rb,
lib/tracing/version.rb

Overview

Tracer.

The trace() method supports indented tracing.

Trace keys: The first argument is normally a symbol which is the key for related trace calls. Set the TRACE environment variable to enable it, or add trace.enable(:key) to a CLI. A call to trace without a first symbol argument is always enabled (as if by :all)

Message arguments: Each subsequent argument is either

- a String (or anything that can be join()ed), or
- a Proc (or anything that can be called) that returns such a string.

Proc arguments will be called only if the trace key is enabled. If the key is enabled (or not present) the Trace strings will be joined and emitted.

Trace blocks: A block passed to the trace method will always be called, and trace will always return its value. Any trace emitted from within such a block will be indented if the current trace key is enabled.

Special trace key options for nesting blocks:

  • A trace key ending in ! is enabled if the base key is enabled, but enables all nested trace calls whether or not their key is enabled.

  • A trace key ending in ? is enabled if the base key is enabled, but is emitted only if (and just before) the nested block emits a trace message

Testing whether a trace key is enabled: A call to trace with a key but without a block will return true if the key is enabled

A call to trace with no arguments returns the Tracer object itself.

Built-in trace keys and behaviour:

help - list (at exit) all trace keys that became available during the run
all - enable all trace keys
keys - display the trace key for every trace message (automatically enabled by :all)
debug - prepare a Ruby debugger at the start of the run, so it has the full context available
firstaid - enter the debugger inside the Exception constructor so you can inspect the local context
trap - trap SIGINT (^C) in a block that allows inspecting or continuing execution (not all debuggers support this)
flame - use ruby-prof-flamegraph to display the performance profile as a flame graph using SVG

The debugger is chosen from ENV or the first to load of: byebug, pry. debugger, ruby-trace

Copyright © 2009-2015 Clifford Heath. Read the LICENSE file.

Defined Under Namespace

Classes: Tracer

Constant Summary collapse

VERSION = 
"2.0.9"