appoptics_apm 4.11.1 → 4.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26c9d31f4b5d680bd14d2cc041c337ea687f87e85c909fb6133d92e3f8292105
-  data.tar.gz: 1694af39aa2e9c8105a7d1b4fa590af16a5a86ae2b41bc9998531f2b16d192af
+  metadata.gz: 6d253a9e5a6be4b11234dc7c761fe700c4ee8ca0d9e254a492de1dd978f80e05
+  data.tar.gz: 45fee16fc9023d5c1e626778cbfd067608b74e0cd70db43376196c6db0d75418
 SHA512:
-  metadata.gz: 3257648c80a8da542d0e3f99a49c53b4ea6f3c2dd3ef37d6e6ebc1384f53054b3883b41f6ae43880f310a5ff4b49c37eaa67450a2d9818946e248180c6834222
-  data.tar.gz: ba4d2a1e71ab6805d73a038bbd1c6593889249e5ebdac1005cbb9df6befad04ef728bcfc67780db2352a10a43c694e991314530452dca57d17297f75c30c3d69
+  metadata.gz: 2d28d01c42520a2245013ac8441880251e5037cf4fbd7523caeba159eee241acd36b32c1a709d95334c98cb44d885f30c3e39c0f3e020ef6b16581aabe461d5d
+  data.tar.gz: 1cc6d1af93479adcb85535e86a791bd7c8eb4806517718612b0c42cf860654a2b07f8d69cc6ac3cc91747ee698dfa85f089d2065f1da7bc5b3cdeb3b68fbbdeb

data/Gemfile

@@ -1,29 +1,38 @@
 source 'https://rubygems.org'
-gem 'rake'
+
+# this Gemfile is very minimal
+# use rake commands or gemfiles in the gemfiles directory for testing
+
+gem 'rake', '>= 0.9.0'
 
 group :development, :test do
-  gem 'minitest'
-  gem 'minitest-reporters', '< 1.0.18'
-  gem 'minitest-debugger', :require => false
-  gem 'rack-test'
-  gem 'puma'
-  gem 'bson'
-  gem 'webmock' if RUBY_VERSION >= '2.0.0'
-  gem 'mocha'
-  gem 'rubocop', require: false
-  gem 'ruby-prof'
-  gem 'benchmark-ips'
-  gem 'ruby-debug',   :platforms =>  :jruby
-  gem 'debugger',     :platform  =>  :mri_19
-  gem 'byebug'
-  gem 'get_process_mem'
-  gem 'memory_profiler'
+  # gem 'benchmark-ips', '>= 2.7.2'
+  # gem 'bson'
+  # gem 'byebug', '>= 8.0.0'
+  # gem 'debugger',     :platform  =>  :mri_19
+  # gem 'get_process_mem'
+  gem 'irb', '>= 1.0.0' # if RUBY_VERSION >= '2.6.0'
+  # gem 'memory_profiler'
+  # gem 'minitest'
+  # gem 'minitest-debugger', :require => false
+  # gem 'minitest-focus', '>=1.1.2'
+  # gem 'minitest-hooks', '>= 1.5.0'
+  # gem 'minitest-reporters', '< 1.0.18'
+  # gem 'mocha'
+  # gem 'puma'
+  # gem 'rack-test'
+  # gem 'rubocop', require: false
+  # gem 'ruby-debug',   :platforms =>  :jruby
+  # gem 'ruby-prof'
+  # gem 'simplecov', '>= 0.16.0'
+  # gem 'simplecov-console'
+  # gem 'webmock' if RUBY_VERSION >= '2.0.0'
 
-  if defined?(JRUBY_VERSION)
-    gem 'sinatra', :require => false
-  else
-    gem 'sinatra'
-  end
+  # if defined?(JRUBY_VERSION)
+  #   gem 'sinatra', :require => false
+  # else
+  #   gem 'sinatra'
+  # end
 end
 
 gemspec

data/appoptics_apm.gemspec

@@ -42,21 +42,21 @@ Automatic tracing and metrics for Ruby applications. Get started at appoptics.co
 
   s.extensions = ['ext/oboe_metal/extconf.rb'] unless defined?(JRUBY_VERSION)
 
-  s.add_runtime_dependency('json', '>= 0')
+  s.add_runtime_dependency('json', '~> 2.3')
   s.add_runtime_dependency('no_proxy_fix', '~> 0.1.2', '>= 0.1.2')
 
   # Development dependencies used in gem development & testing
-  s.add_development_dependency('rake', '>= 0.9.0')
-  s.add_development_dependency('simplecov', '>= 0.16.0') if ENV["SIMPLECOV_COVERAGE"]
-  s.add_development_dependency('simplecov-console', '>= 0.4.0') if ENV["SIMPLECOV_COVERAGE"]
-  s.add_development_dependency('irb', '>= 1.0.0') if RUBY_VERSION >= '2.6.0'
-
-  unless defined?(JRUBY_VERSION)
-    s.add_development_dependency('byebug', '>= 8.0.0')
-    s.add_development_dependency('minitest-hooks', '>= 1.5.0')
-    s.add_development_dependency('minitest-focus', '>=1.1.2')
-    s.add_development_dependency('benchmark-ips', '>= 2.7.2')
-  end
+  # s.add_development_dependency('rake', '>= 0.9.0')
+  # s.add_development_dependency('simplecov', '>= 0.16.0') if ENV["SIMPLECOV_COVERAGE"]
+  # s.add_development_dependency('simplecov-console', '>= 0.4.0') if ENV["SIMPLECOV_COVERAGE"]
+  # s.add_development_dependency('irb', '>= 1.0.0') if RUBY_VERSION >= '2.6.0'
+  #
+  # unless defined?(JRUBY_VERSION)
+  #   s.add_development_dependency('byebug', '>= 8.0.0')
+  #   s.add_development_dependency('minitest-hooks', '>= 1.5.0')
+  #   s.add_development_dependency('minitest-focus', '>=1.1.2')
+  #   s.add_development_dependency('benchmark-ips', '>= 2.7.2')
+  # end
 
   s.required_ruby_version = '>= 2.4.0'
   s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }

data/examples/sdk_examples.rb

@@ -0,0 +1,142 @@
+# Copyright (c) 2020 SolarWinds, LLC.
+# All rights reserved.
+
+###############################################################
+# SDK EXAMPLES
+###############################################################
+# The uses cases of the SDK include:
+# - tracing a piece of your own code
+# - tracing a method call of a gem that is not auto-instrumented
+#   by appoptics_apm
+#
+# SDK documentation:
+# https://rubydoc.info/gems/appoptics_apm/AppOpticsAPM/SDK
+
+###############################################################
+# Prerequisits
+# export APPOPTICS_SERVICE_KEY=<API token>:<service_name>
+# `bundle exec ruby sdk_examples.rb`
+# 5 traced requests will show up at https://my.appoptics.com/
+###############################################################
+
+require 'appoptics_apm'
+
+unless AppOpticsAPM::SDK.appoptics_ready?(10_000)
+  puts "aborting!!! Agent not ready after 10 seconds"
+  exit false
+end
+
+###############################################################
+### ADD A SPAN
+###############################################################
+#
+# AppOpticsAPM::SDK.trace()
+# This method adds a span to a trace that has been started either
+# by the auto-instrumentation of the gem handling incoming requests
+# or the SDK method `start_trace`.
+# If this method is called outside of the context of a started
+# trace no spans will be created.
+#
+# The argument is the name for the span
+
+AppOpticsAPM::SDK.trace('span_name') do
+  [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+end
+
+###############################################################
+# START A TRACE, ADD A SPAN, AND LOG AN INFO EVENT
+###############################################################
+#
+# AppOpticsAPM::SDK.start_trace()
+# This method starts a trace.  It is handy for background jobs,
+# workers, or scripts, that are not part of a rack application
+
+AppOpticsAPM::SDK.start_trace('outer_span') do
+  AppOpticsAPM::SDK.trace('first_child_span') do
+    [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+    AppOpticsAPM::SDK.log_info({ some: :fancy, hash: :to, send: 1 })
+  end
+end
+
+###############################################################
+# LOG AN ERROR EVENT
+###############################################################
+#
+# AppOpticsAPM::SDK.log_exception()
+# This method adds an error event to the trace, which will be
+# displayed and counted as exception on the appoptics dashboard.
+
+def do_raise
+  raise StandardError.new("oops")
+end
+
+AppOpticsAPM::SDK.start_trace('with_error') do
+  begin
+    do_raise
+  rescue => e
+    AppOpticsAPM::SDK.log_exception(e)
+  end
+end
+
+###############################################################
+# TRACE A METHOD
+###############################################################
+#
+# AppOpticsAPM::SDK.trace_method()
+# This creates a span every time the defined method is run.
+# The method can be of any (accessible) type (instance,
+# singleton, private, protected etc.).
+
+module ExampleModule
+  def self.do_sum(a, b)
+    a + b
+  end
+end
+
+AppOpticsAPM::SDK.trace_method(ExampleModule,
+                               :do_sum,
+                               { name: 'computation', backtrace: true },
+                               { CustomKey: "some_info"})
+
+AppOpticsAPM::SDK.start_trace('trace_a_method') do
+  ExampleModule.do_sum(1, 2)
+  ExampleModule.do_sum(3, 4)
+end
+
+###############################################################
+# SET A CUSTOM TRANSACTION NAME
+###############################################################
+#
+# AppOpticsAPM::SDK.set_transaction_name()
+#
+# this method can be called anytime after a trace has been started to add a
+# custom name for the whole transaction.
+# In case of a controller the trace is usually started in rack.
+
+class FakeController
+  def create(params)
+    # @fake = fake.new(params.permit(:type, :title))
+    # @fake.save
+    AppOpticsAPM::SDK.set_transaction_name("fake.#{params[:type]}")
+    # redirect_to @fake
+  end
+end
+
+AppOpticsAPM::SDK.start_trace('set_transaction_name') do
+  FakeController.new.create(type: 'news')
+end
+
+###############################################################
+# LOG INJECTION OF TRACE_ID
+###############################################################
+#
+# AppOpticsAPM::SDK.current_trace
+# This method creates an object with the current trace ID and
+# helper methods to add the ID to logs for cross-referencing.
+
+AppOpticsAPM::Config[:log_traceId] = :always
+
+AppOpticsAPM::SDK.start_trace('log_trace_id') do
+  trace = AppOpticsAPM::SDK.current_trace
+  AppOpticsAPM.logger.warn "Some log message #{trace.for_log}"
+end

data/ext/oboe_metal/extconf.rb

@@ -49,7 +49,7 @@ while retries > 0
   begin
     # download
     # TODO warning: calling URI.open via Kernel#open is deprecated, call URI.open directly or use URI#open
-    # ____ figure out if URI.open is supported in older rubies
+    # ____ URI.open is not supported in 2.4.5, let's use open until we can deprecate 2.4.5
     download = open(ao_item, 'rb')
     IO.copy_stream(download, clib)
 

data/ext/oboe_metal/src/VERSION

@@ -1 +1 @@
-7.1.1
+10.0.0

data/lib/appoptics_apm/api/metrics.rb

@@ -45,6 +45,8 @@ module  AppOpticsAPM
           AppOpticsAPM.transaction_name
         elsif kvs['Controller'] && kvs['Action']
           [kvs['Controller'], kvs['Action']].join('.')
+        elsif kvs[:Controller] && kvs[:Action]
+          [kvs[:Controller], kvs[:Action]].join('.')
         else
           "custom-#{span}"
         end
@@ -52,4 +54,4 @@ module  AppOpticsAPM
 
     end
   end
-end
+end

data/lib/appoptics_apm/sdk/custom_metrics.rb

@@ -29,7 +29,7 @@ module AppOpticsAPM
       #   end
       #
       # === Returns:
-      # * true on success, false on failure
+      # * 0 on success, error code on failure
       #
       def increment_metric(name, count = 1, with_hostname = false, tags_kvs = {})
         return true unless AppOpticsAPM.loaded
@@ -62,7 +62,7 @@ module AppOpticsAPM
       #   end
       #
       # === Returns:
-      # * true on success, false on failure
+      # * 0 on success, error code on failure
       #
       def summary_metric(name, value, count = 1, with_hostname = false, tags_kvs = {})
         return true unless AppOpticsAPM.loaded

data/lib/appoptics_apm/test.rb

@@ -54,7 +54,7 @@ module AppOpticsAPM
         if ENV.key?('TRAVIS_PSQL_PASS')
           ENV['DATABASE_URL'] = "postgresql://postgres:#{ENV['TRAVIS_PSQL_PASS']}@127.0.0.1:5432/travis_ci_test"
         elsif ENV.key?('DOCKER_PSQL_PASS')
-          ENV['DATABASE_URL'] = "postgresql://docker:#{ENV['DOCKER_PSQL_PASS']}@127.0.0.1:5432/travis_ci_test"
+          ENV['DATABASE_URL'] = "postgresql://docker:#{ENV['DOCKER_PSQL_PASS']}@#{ENV['PSQL_HOST']}:5432/travis_ci_test"
         else
           ENV['DATABASE_URL'] = 'postgresql://postgres@127.0.0.1:5432/travis_ci_test'
         end

data/lib/appoptics_apm/version.rb

@@ -8,7 +8,7 @@ module AppOpticsAPM
   module Version
     MAJOR = 4 # breaking,
     MINOR = 11 # feature,
-    PATCH = 1 # fix => BFF
+    PATCH = 2 # fix => BFF
 
     STRING = [MAJOR, MINOR, PATCH].compact.join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appoptics_apm
 version: !ruby/object:Gem::Version
-  version: 4.11.1
+  version: 4.11.2
 platform: ruby
 authors:
 - Maia Engeli
@@ -10,22 +10,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2020-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: no_proxy_fix
   requirement: !ruby/object:Gem::Requirement
@@ -46,94 +46,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.2
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.0
-- !ruby/object:Gem::Dependency
-  name: irb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-- !ruby/object:Gem::Dependency
-  name: byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.0.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.0.0
-- !ruby/object:Gem::Dependency
-  name: minitest-hooks
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.5.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.5.0
-- !ruby/object:Gem::Dependency
-  name: minitest-focus
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.2
-- !ruby/object:Gem::Dependency
-  name: benchmark-ips
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.7.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.7.2
 description: 'Automatic tracing and metrics for Ruby applications. Get started at
   appoptics.com. @AppOptics
 
-'
+  '
 email: support@appoptics.com
 executables:
 - appoptics_apm_config
@@ -156,8 +72,7 @@ files:
 - README.md
 - appoptics_apm.gemspec
 - bin/appoptics_apm_config
-- examples/SDK/01_basic_tracing.rb
-- examples/carrying_context.rb
+- examples/sdk_examples.rb
 - ext/oboe_metal/README.md
 - ext/oboe_metal/extconf.rb
 - ext/oboe_metal/lib/.keep

data/examples/SDK/01_basic_tracing.rb

@@ -1,68 +0,0 @@
-
-###############################################################
-# BASIC TRACING EXAMPLES
-###############################################################
-
-# set APPOPTICS_SERVICE_KEY and run with
-# `bundle exec ruby 01_basic_tracing.rb`
-
-require 'appoptics_apm'
-unless AppOpticsAPM::SDK.appoptics_ready?(10_000)
-  puts "aborting!!! Agent not ready after 10 seconds"
-  exit false
-end
-
-
-###############################################################
-# Starting a trace and adding a span
-###############################################################
-
-# USE CASE:
-# You may want to either trace a piece of your own code or a
-# call to a method from a gem that isn't auto-instrumented by
-# appoptics_apm
-
-# The first example will not create a span, because no trace has
-# been started, but the second and third ones will.
-
-# The string argument is the name for the span
-
-##
-# AppOpticsAPM::SDK.trace()
-# most of the time this is the method you need.  It adds a span
-# to a trace that has probably been started by rack.
-
-# Example 1
-def do_work
-  42
-end
-
-AppOpticsAPM::SDK.trace('simple_span') do
-  do_work
-end
-
-##
-# AppOpticsAPM::SDK.start_trace()
-# This method starts a trace.  It is handy for background jobs,
-# workers, or scripts, that are not part of a rack application
-
-# Example 2
-AppOpticsAPM::SDK.start_trace('outer_span') do
-
-  AppOpticsAPM::SDK.trace('simple_span') do
-    do_work
-    AppOpticsAPM::API.log_info(AppOpticsAPM.layer, { some: :fancy, hash: :to, send: 1 })
-  end
-
-end
-
-# Example 3
-def do_traced_work
-  AppOpticsAPM::SDK.trace('simple_span_2') do
-    do_work
-  end
-end
-
-AppOpticsAPM::SDK.start_trace('outer_span_2') do
-  do_traced_work
-end

data/examples/carrying_context.rb

@@ -1,220 +0,0 @@
-###############################################################
-# A brief overview of AppOpticsAPM tracing context
-###############################################################
-#
-# Tracing context is the state held when AppOpticsAPM is instrumenting a
-# transaction, block, request etc..  This context is advanced as
-# new blocks are instrumented and this chain of context is used
-# by AppOpticsAPM to later reassemble performance data to be displayed
-# in the AppOptics dashboard.
-#
-# Tracing context is non-existent until established by calling
-# `AppOpticsAPM::API.start_trace` or `AppOpticsAPM::API.log_start`.  Those methods
-# are part of the high-level and low-level API respectively.
-#
-# After a tracing context is established, that context can be
-# continued by calling `AppOpticsAPM::API.trace` or `AppOpticsAPM::API.log_entry`.
-# These methods will advance an existing context but not start
-# new one.
-#
-# For example, when a web request comes into a stack, a tracing
-# context is established using `AppOpticsAPM::API.log_start` as the request
-# enters through the rack middleware via `AppOpticsAPM::Rack`.
-#
-# That tracing context is then continued using `AppOpticsAPM::API.trace` or
-# `AppOpticsAPM::API.log_entry` for each subsequent layer such as Rails,
-# ActiveRecord, Redis, Memcache, ActionView, Mongo (etc...) until
-# finally request processing is complete and the tracing context
-# is cleared (AppOpticsAPM::Context.clear)
-#
-
-###############################################################
-# Carrying Context
-###############################################################
-#
-# The tracing context exists in the form of an X-Trace string and
-# can be retrieved using 'AppOpticsAPM::Context.toString'
-#
-# xtrace = AppOpticsAPM::Context.toString
-#
-# => "1B4EDAB9E028CA3C81BCD57CC4644B4C4AE239C7B713F0BCB9FAD6D562"
-#
-# Tracing context can also be picked up from a pre-existing
-# X-Trace string:
-#
-# xtrace = "1B4EDAB9E028CA3C81BCD57CC4644B4C4AE239C7B713F0BCB9FAD6D562"
-#
-# AppOpticsAPM::Context.fromString(xtrace)
-#
-# With these two methods, context can be passed across threads,
-# processes (via fork) and in requests (such as external HTTP
-# requests where the X-Trace is inserted in request headers).
-#
-#
-
-###############################################################
-# Two Options for Spawned Tracing
-###############################################################
-#
-# When your application needs to instrument code that forks,
-# spawns a thread or does something in-parallel, you have the
-# option to either link those child traces to the parent or
-# trace them as individuals (but with identifying information).
-#
-# Linking parent and child has it's benefits as in the
-# AppOptics dashboard, you will see how a process may spawn
-# a task in parallel and in a single view see the performance
-# of both.
-#
-# The limitation of this is that this is only useful if your
-# parent process spawns only a limited number of child traces.
-#
-# If your parent process is spawning many child tasks (e.g.
-# twenty, hundreds, thousands or more) it's best to trace those
-# child tasks as individuals and pass in identifier Key-Values
-# (such as task ID, job ID etc..)
-#
-# In the examples below, I show implementations of both linked
-# asynchronous traces and separated independent traces.
-
-###############################################################
-# Thread - with separated traces
-###############################################################
-
-AppOpticsAPM::API.log_start('parent')
-
-# Get the work to be done
-job = get_work
-
-Thread.new do
-  # This is a new thread so there is no pre-existing context so
-  # we'll call `AppOpticsAPM::API.log_start` to start a new trace context.
-  AppOpticsAPM::API.log_start('worker_thread', :job_id => job.id)
-
-  # Do the work
-  do_the_work(job)
-
-  AppOpticsAPM::API.log_end('worker_thread')
-end
-
-AppOpticsAPM::API.log_end('parent')
-
-###############################################################
-#
-# This will generate two independent traces with the following
-# topology.
-#
-# 'parent'
-# ------------------------------------------------------------
-#
-# 'worker_thread'
-# ------------------------------------------------------------
-#
-
-###############################################################
-# Thread - with linked asynchronous traces
-###############################################################
-
-# Since the following example spawns a thread without waiting
-# for it to return, we carry over the context and we mark the
-# trace generated in that thread to be asynchronous using
-# the `Async` flag.
-
-AppOpticsAPM::API.log_start('parent')
-
-# Save the context to be imported in spawned thread
-tracing_context = AppOpticsAPM::Context.toString
-
-# Get the work to be done
-job = get_work
-
-Thread.new do
-  # Restore context
-  AppOpticsAPM::Context.fromString(tracing_context)
-
-  AppOpticsAPM::API.log_entry('worker_thread')
-
-  # Do the work
-  do_the_work(job)
-
-  AppOpticsAPM::API.log_exit('worker_thread', :Async => 1)
-end
-
-AppOpticsAPM::API.log_end('parent')
-
-###############################################################
-#
-# This will generate a single trace with an asynchronous
-# branch like the following
-#
-# 'parent'
-# ------------------------------------------------------------
-#     \
-#      \
-#       ------------------------------------------------------
-#        'worker_thread'
-#
-
-###############################################################
-# Process via fork - with separated traces
-###############################################################
-
-AppOpticsAPM::API.start_trace('parent_process') do
-  # Get some work to process
-  job = get_job
-
-  # fork process to handle work
-  fork do
-    # Since fork does a complete process copy, the tracing_context still exists
-    # so we have to clear it and start again.
-    AppOpticsAPM::Context.clear
-
-    AppOpticsAPM::API.start_trace('worker_process', nil, :job_id => job.id) do
-      do_work(job)
-    end
-  end
-
-end
-
-###############################################################
-#
-# This will generate two independent traces:
-#
-# 'parent_process'
-# ------------------------------------------------------------
-#
-# 'worker_process'
-# ------------------------------------------------------------
-#
-###############################################################
-# Process via fork - with linked asynchronous traces
-###############################################################
-
-AppOpticsAPM::API.start_trace('parent_process') do
-  # Get some work to process
-  job = get_job
-
-  # fork process to handle work
-  fork do
-    # Since fork does a complete process copy, the tracing_context still exists
-    # although we'll have to mark these traces as asynchronous to denote
-    # that it has split off from the main program flow
-
-    AppOpticsAPM::API.trace('worker_process', :Async => 1) do
-      do_work(job)
-    end
-  end
-end
-
-###############################################################
-#
-# This will generate a single trace with an asynchronous
-# branch like the following
-#
-# 'parent_process'
-# ------------------------------------------------------------
-#     \
-#      \
-#       ------------------------------------------------------
-#        'worker_process'
-#