README.md in oboe-2.4.0.1 vs README.md in oboe-2.5.0.7

@@ -74,37 +74,52 @@
     require 'bundler'
     
     Bundler.require
     
     require 'oboe'
+
+    # Tracing mode can be 'never', 'through' (to follow upstream) or 'always'
+    Oboe::Config[:tracing_mode] = 'always'
+
+    # Number of requests to trace out of each million
+    Oboe::Config[:sample_rate] = 1000000
+
     Oboe::Ruby.initialize
 
-From here, you can use the Tracing API to instrument areas of code (see below).
+From here, you can use the Tracing API to instrument areas of code using `Oboe::API.start_trace` (see below).  If you prefer to instead dive directly into code, take a look at [this example](https://gist.github.com/pglombardo/8550713) of an instrumented Ruby script.
 
 ## Other
 
 You can send deploy notifications to TraceView and have the events show up on your dashboard.  See: [Capistrano Deploy Notifications with tlog](https://support.tv.appneta.com/support/solutions/articles/86389-capistrano-deploy-notifications-with-tlog).
 
 # Custom Tracing
 
 ## The Tracing API
 
-You can instrument any arbitrary block of code using the following pattern:
+You can instrument any arbitrary block of code using `Oboe::API.trace`:
 
     # layer_name will show up in the TraceView app dashboard
     layer_name = 'subsystemX'
 
-    # report_kvs are a set of information Key/Value pairs that are sent to TraceView along with the performance metrics.
-    # These KV pairs can report on request, environment or client specific information.
+    # report_kvs are a set of information Key/Value pairs that are sent to
+    # TraceView dashboard along with the performance metrics.  These KV 
+    # pairs are used to report request, environment and/or client specific
+    # information.
 
     report_kvs = {}
     report_kvs[:mykey] = @client.id
 
     Oboe::API.trace(layer_name, report_kvs) do
       # the block of code to be traced
     end
 
-Find more details in the TraceView [documentation portal](https://support.tv.appneta.com/support/solutions/articles/86395-ruby-instrumentation-public-api).
+`Oboe::API.trace` is used within the context of a request.  It will follow the upstream state of the request being traced.  i.e. the block of code will only be traced when the parent request is being traced.
+
+This tracing state of a request can also be queried by using `Oboe.tracing?`.
+
+If you need to instrument code outside the context of a request (such as a cron job, background job or an arbitrary ruby script), use `Oboe::API.start_trace` instead which will initiate new traces based on configuration and probability (based on the sample rate).
+
+Find more details in the [RubyDoc page](http://rdoc.info/gems/oboe/Oboe/API/Tracing) or in [this example](https://gist.github.com/pglombardo/8550713) on how to use the Tracing API in an independent Ruby script.
 
 ## Tracing Methods
 
 By using class level declarations, it's possible to automatically have certain methods on that class instrumented and reported to your TraceView dashboard automatically.