tracing 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 20ef811dadb9ee19941f4848e9ba99ae47f705c1
+  data.tar.gz: a6f2ee9abc71081e56b8f1a1c6d85e526952d284
+SHA512:
+  metadata.gz: b7f5e1d033b5d162496945ba150ebb692f89766bd902e5629a2bd8dac33f1aecacbf17d6bc60988d8d3e91771bd21fab82b42a3e58e5610723be1e2b01ad4915
+  data.tar.gz: d68c6e4611334cb883756fefeeeb36cb4768461aaffdc4fdaf34f51ee87cb5f247b2d655b16164c708f5eb674ef0bff6ccf42a4c975255b093f5893a2d40ae15

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  # rcov 1.0.0 is broken for jruby, so 0.9.11 is the only one available.
+  #gem 'rcov', '~> 0.9.11', :platforms => [:jruby, :mri_18], :require => false
+  #gem 'simplecov', '~> 0.6', '>= 0.6.4', :platforms => :mri_19, :require => false
+end

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2015 Clifford Heath.
+
+This software is provided 'as-is', without any express or implied warranty.
+In no event will the authors be held liable for any damages arising from the
+use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.rdoc

@@ -0,0 +1,86 @@
+= tracing
+
+Tracing provides a single method call *trace* which is used in a number of ways
+to generated highly configurable nested tracing output from your program.
+Each trace key is defined by a symbolic keyword, which is enabled by
+including it in a comma-separated list in the TRACE environment variable.
+
+== INSTALL:
+
+* sudo gem install tracing
+
+== USAGE:
+
+require 'tracing'
+
+When *trace* is called with no arguments, it returns the Tracer singleton object.
+The API of this object is defined below. You probably don't need to use this.
+
+If called with one argument, that should be a Symbol, which is the trace key.
+Nothing is printed, and the return value is true if this trace key is enabled.
+
+Normal calls to *trace* take two or more arguments, and an optional block.
+
+The first argument is a Symbol, which is the trace key.
+
+The second and any subsequent arguments are either a String (or anything that can be *join*ed)
+or a Proc (or anything which can be called), which is evaluated and printed
+if the trace key is enabled.
+
+If a block is passed, the nesting level is increased (if this key was enabled),
+the block is called, and *trace* returns its return value (restoring the nesting).
+
+== SPECIAL TRACE KEYS
+
+Specific TRACE keys configure internal behaviour:
+
+* *debug* pre-loads a Ruby debugger at the start of the run, so it has the full context available
+
+* *help* runs the program, and at exit, prints all trace keys that were available during that run.
+
+* *keys* causes each output line to be prefixed by its trace key
+
+* *all* enables all trace keys (this also enables *keys*)
+
+* *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['DEBUG_PREFERENCE'] or the first to load of: byebug, pry. debugger, ruby-trace
+
+== TRACER API
+
+The Tracer supports the following methods:
+
+* *reinitialize*() clear all trace keys and re-initialise from the TRACE enfironment variable
+
+* *available_keys*() returns an array of the keys seen so far this run
+
+* *enabled?*(key) returns true if key is enabled
+
+* *enabled*() returns an array of all enabked keys
+
+* *enable*(key) enables that key
+
+* *disable*(key) disables that key
+
+* *toggle*(key) toggles that key
+
+* *display*(string) prints the string to standard output. You can monkey-patch this to divert the output.
+
+== Contributing to tracing
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile or gem version.rb
+
+== Copyright
+
+Copyright (c) 2016 Clifford Heath. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,89 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Bump gem version patch number"
+task :bump do
+  path = File.expand_path('../lib/activefacts/api/version.rb', __FILE__)
+  lines = File.open(path) do |fp| fp.readlines; end
+  File.open(path, "w") do |fp|
+    fp.write(
+      lines.map do |line|
+	line.gsub(/(VERSION *= *"[0-9.]*\.)([0-9]+)"\n/) do
+	  version = "#{$1}#{$2.to_i+1}"
+	  puts "Version bumped to #{version}\""
+	  version+"\"\n"
+	end
+      end*''
+    )
+  end
+end
+
+desc "Run Rspec tests"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %w{-f d}
+end
+
+namespace :spec do
+  namespace :rubies do
+    SUPPORTED_RUBIES = %w{ 1.9.2 1.9.3 2.0.0 jruby-1.7.0 }
+
+    desc "Run Rspec tests on all supported rubies"
+    task :all_tasks => [:install_gems, :exec]
+
+    desc "Run `bundle install` on all rubies"
+    task :install_gems do
+      sh %{ rvm #{SUPPORTED_RUBIES.join(',')} exec bundle install }
+    end
+
+    desc "Run `bundle exec rake` on all rubies"
+    task :exec do
+      sh %{ rvm #{SUPPORTED_RUBIES.join(',')} exec bundle exec rake spec }
+    end
+
+    SUPPORTED_RUBIES.each do |ruby|
+      desc "Run `bundle install` on #{ruby}"
+      task :"install_gems_#{ruby}" do
+	sh %{ rvm #{ruby} exec bundle install }
+      end
+
+      desc "Run `bundle exec rake` on #{ruby}"
+      task :"exec_#{ruby}" do
+	sh %{ rvm #{ruby} exec bundle exec rake spec }
+      end
+    end
+
+  end
+end
+
+desc "Run RSpec tests and produce coverage files (results viewable in coverage/index.html)"
+RSpec::Core::RakeTask.new(:coverage) do |spec|
+  if RUBY_VERSION < '1.9'
+    spec.rcov_opts = %{ --exclude spec --exclude lib/activefacts/tracer.rb --exclude gem/* }
+    spec.rcov = true
+  else
+    spec.rspec_opts = %w{ --require simplecov_helper }
+  end
+end
+
+task :cov => :coverage
+task :rcov => :coverage
+task :simplecov => :coverage
+
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "activefacts-api #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :wait do
+  print "Waiting for you to hit Enter"
+  $stdin.gets
+end

data/VERSION

@@ -0,0 +1 @@
+1.8.2

data/lib/tracing/version.rb

@@ -0,0 +1,3 @@
+module Tracing
+  VERSION = "2.0.0"
+end

data/lib/tracing.rb

@@ -0,0 +1,281 @@
+#
+# 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['DEBUG_PREFERENCE'] or the first to load of: byebug, pry. debugger, ruby-trace
+#
+# Copyright (c) 2009-2015 Clifford Heath. Read the LICENSE file.
+#
+module Tracing
+  (class << self; self; end).class_eval do
+    attr_accessor :tracer
+  end
+
+  class Tracer
+    def initialize
+      reinitialize
+    end
+
+    def reinitialize
+      @indent = 0	# Current nesting level of enabled trace blocks
+      @nested = false   # Set when a block enables all enclosed tracing
+      @available = {}	# Hash of available trace keys, accumulated during the run
+      @delayed = nil	# A delayed message, emitted only if the enclosed block emits tracing
+
+      @keys = {}
+      if (e = ENV["TRACE"])
+	e.split(/[^_a-zA-Z0-9]/).each{|k| enable(k) }
+      end
+    end
+
+    def trace(*args, &block)
+      begin
+	old_indent, old_nested, old_delayed, enabled = @indent, @nested, @delayed, show(*args)
+	# This monstrosity reduces the steps when single-stepping:
+	block ? yield : (args.size == 0 ? self : enabled)
+      ensure
+	@indent, @nested, @delayed = old_indent, old_nested, old_delayed
+      end
+    end
+
+    def available_keys
+      @available.keys
+    end
+
+    def enabled? key
+      !key.empty? && @keys[key.to_sym]
+    end
+
+    def enabled
+      @keys.keys
+    end
+
+    def enable key
+      if !key.empty? && !@keys[s = key.to_sym]
+	@keys[s] = true
+	setup_help if s == :help
+	setup_flame if s == :flame
+      else
+	true
+      end
+    end
+
+    def disable key
+      !key.empty? and @keys.delete(key.to_sym)
+    end
+
+    def toggle key
+      if !key.empty?
+	if enabled?(key)
+	  disable(key)
+	  false
+	else
+	  enable(key)
+	  true
+	end
+      end
+    end
+
+    def setup_help
+      at_exit {
+	$stderr.puts "---\nTracing keys available: #{@available.keys.map{|s| s.to_s}.sort*", "}"
+      }
+    end
+
+    def setup_flame
+      require 'ruby-prof'
+      require 'ruby-prof-flamegraph'
+      profile_result = RubyProf.start
+      at_exit {
+	profile_result2 = RubyProf.stop
+	printer = RubyProf::FlameGraphPrinter.new(profile_result2)
+	data_file = "/tmp/flamedata_#{Process.pid}.txt"
+	svg_file = "/tmp/flamedata_#{Process.pid}.svg"
+	flamegraph = File.dirname(__FILE__)+"/flamegraph.pl"
+	File.popen("tee #{data_file} | perl #{flamegraph} --countname=ms --width=4800 > #{svg_file}", "w") { |f|
+	  printer.print(f, {})
+	}
+	STDERR.puts("Flame graph dumped to file:///#{svg_file}")
+      }
+    end
+
+    def setup_debugger
+      begin
+	require 'ruby-trace '
+	Debugger.start # (:post_mortem => true)  # Some Ruby versions crash on post-mortem debugging
+      rescue LoadError
+	# Ok, no debugger, tough luck.
+      end
+
+      if trace :trap
+	trap('SIGINT') do
+	  puts "Stopped at:\n\t"+caller*"\n\t"
+	  debugger
+	  true	# Stopped on SIGINT
+	end
+      end
+
+      errors = []
+      (
+	[ENV["DEBUG_PREFERENCE"]].compact +
+	[
+	  'byebug',
+	  'pry',
+	  'debugger',
+	  'ruby-trace '
+	]
+      ).each do |debugger|
+	begin
+	  require debugger
+	  if debugger == 'byebug'
+	    Kernel.class_eval do
+	      alias_method :debugger, :byebug
+	    end
+	  end
+	  ::Debugger.start if (const_get(::Debugger) rescue nil)
+	  return
+	rescue LoadError => e
+	  errors << e
+	end
+      end
+
+      # Report when we couldn't load any debugger
+      $stderr.p errors
+    end
+
+    def setup_firstaid
+      if trace :firstaid
+	puts "Preparing first aid kit"
+	::Exception.class_eval do
+	  alias_method :firstaid_initialize, :initialize
+
+	  def initialize *args, &b
+	    send(:firstaid_initialize, *args, &b)
+	    return if NoMethodError === self && message =~ /^undefined method `to_ary' for \#<Gem::Specification/
+	    return if LoadError == self
+	    puts "Stopped due to #{self.class}: #{message} at "+caller*"\n\t"
+	    debugger
+	    true # Stopped in Exception constructor
+	  end
+	end
+      end
+    end
+
+    def display key, msg
+      puts msg
+    end
+
+  private
+    def show(*args)
+      key, enabled_prefix = *selected?(args)
+
+      # Emit the message if enabled or a parent is:
+      if enabled_prefix && args.size > 0
+	message =
+	  "\##{enabled_prefix} " +
+	  '  '*@indent +
+	  args.
+	    map{|a| a.respond_to?(:call) ? a.call : a}.
+	    join(' ')
+
+	if @delayed == true
+	  @delayed = message	# Arrange to display this message later, if necessary
+	elsif @delayed
+	  display key, @delayed		# Display a delayed message, then the current one
+	  @delayed = nil
+	  display key, message
+	else
+	  display key, message
+	end
+      end
+      @indent += (enabled_prefix ? 1 : 0)
+      !!enabled_prefix
+    end
+
+    def selected?(args)
+      # Figure out whether this trace is enabled (itself or by :all), if it nests, and if we should print the key:
+      key =
+	if Symbol === args[0]
+	  control = args.shift
+	  case s = control.to_s
+	  when /!\Z/		# Enable all nested trace calls
+	    nested = true
+	    s.sub(/!\Z/, '').to_sym
+	  when /\?\Z/		# Delay this message until a nested active trace
+	    @delayed = true
+	    s.sub(/\?\Z/, '').to_sym
+	  else
+	    control
+	  end
+	else
+	  :all
+	end
+
+      @available[key] ||= key		# Remember that this trace was requested, for help
+      if @nested ||			# This trace is enabled because it's in a nested block
+	  @keys[key] ||			# This trace is enabled in its own right
+	  @keys[:all]			# This trace is enabled because all are
+	if @keys[:keys] || @keys[:all]	# Use a formatting prefix?
+	  enabled_prefix = " %-15s"%key
+	  @keys[key] = enabled_prefix if @keys[key] == true # Save the formatting prefix
+	else
+	  enabled_prefix = ''
+	end
+	@nested ||= nested		# Activate nesting, if requested
+      end
+
+      [key, enabled_prefix]
+    end
+
+  end
+end
+
+# Make the trace method globally available:
+class Object
+  def trace *args, &block
+    (Tracing.tracer ||= Tracing::Tracer.new).trace(*args, &block)
+  end
+end
+
+# Load the ruby debugger before everything else, if requested
+if trace(:debug) or trace(:firstaid) or trace(:trap)
+  trace.setup_debugger
+  trace.setup_firstaid
+end

data/tracing.gemspec

@@ -0,0 +1,44 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'tracing/version'
+
+Gem::Specification.new do |spec|
+  spec.name	     = "tracing"
+  spec.version       = Tracing::VERSION
+  spec.authors       = ["Clifford Heath"]
+  spec.email         = ["clifford.heath@gmail.com"]
+  spec.date = "2015-10-02"
+
+  spec.summary = "A nested tracing API for user defined trace classes"
+  spec.description   = %q{
+Enable tracing by setting the TRACE environment variable to a list of the
+names of trace classes you want to investigate. The enabled tracing is
+generated in a nested format, with significant support for exceptions and
+debugging.
+}
+  spec.homepage      = "https://github.com/cjheath/tracing"
+  spec.license       = "MIT"
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+
+  spec.add_runtime_dependency(%q<rbtree-pure>, [">= 0.1.1", "~> 0"])
+
+  spec.add_development_dependency "bundler", ">= 1.10", "~> 1.10.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3"
+
+  spec.add_runtime_dependency(%q<ruby-debug>, ["~> 0"]) if RUBY_VERSION < "1.9"
+  spec.add_runtime_dependency(%q<debugger>, ["~> 1"]) if RUBY_VERSION =~ /^1\.9/ or RUBY_VERSION =~ /^2\.0/
+  spec.add_runtime_dependency(%q<byebug>, ["~> 1"]) if RUBY_VERSION =~ /^2\.1/
+  # spec.add_development_dependency(%q<pry>, ["~> 0"]) # rbx, jruby
+end
+

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: tracing
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Clifford Heath
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbtree-pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.6
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: |2
+
+  Enable tracing by setting the TRACE environment variable to a list of the
+  names of trace classes you want to investigate. The enabled tracing is
+  generated in a nested format, with significant support for exceptions and
+  debugging.
+email:
+- clifford.heath@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.rdoc
+files:
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/tracing.rb
+- lib/tracing/version.rb
+- tracing.gemspec
+homepage: https://github.com/cjheath/tracing
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A nested tracing API for user defined trace classes
+test_files: []