ddtrace 0.54.2 → 1.0.0.beta1

data/docs/GettingStarted.md

@@ -1,3 +1,5 @@
+***Version 1.0.0 is in beta! Check out our [upgrade guide](https://github.com/DataDog/dd-trace-rb/blob/master/docs/UpgradeGuide.md#from-0x-to-10) for more details.***
+
 # Datadog Ruby Trace Client
 
 `ddtrace` is Datadog’s tracing client for Ruby. It is used to trace requests as they flow across web servers,
@@ -9,6 +11,8 @@ For the general APM documentation, see our [setup documentation][setup docs].
 
 For more information about what APM looks like once your application is sending information to Datadog, take a look at [Visualizing your APM data][visualization docs].
 
+For the library API documentation, see our [YARD documentation][yard docs].
+
 To contribute, check out the [contribution guidelines][contribution docs] and [development guide][development docs].
 
 [setup docs]: https://docs.datadoghq.com/tracing/
@@ -16,6 +20,7 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
 [visualization docs]: https://docs.datadoghq.com/tracing/visualization/
 [contribution docs]: https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md
 [development docs]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/DevelopmentGuide.md
+[yard docs]: https://www.rubydoc.info/gems/ddtrace/
 
 ## Table of Contents
 
@@ -27,11 +32,11 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
  - [Manual instrumentation](#manual-instrumentation)
  - [Integration instrumentation](#integration-instrumentation)
      - [Action Cable](#action-cable)
-     - [Action View](#action-view)
      - [Action Mailer](#action-mailer)
-     - [Active Model Serializers](#active-model-serializers)
      - [Action Pack](#action-pack)
+     - [Action View](#action-view)
      - [Active Job](#active-job)
+     - [Active Model Serializers](#active-model-serializers)
      - [Active Record](#active-record)
      - [Active Support](#active-support)
      - [AWS](#aws)
@@ -49,6 +54,7 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
      - [http.rb](#httprb)
      - [httpclient](#httpclient)
      - [httpx](#httpx)
+     - [Kafka](#kafka)
      - [MongoDB](#mongodb)
      - [MySQL2](#mysql2)
      - [Net/HTTP](#nethttp)
@@ -60,11 +66,11 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
      - [Rails](#rails)
      - [Rake](#rake)
      - [Redis](#redis)
-     - [Rest Client](#rest-client)
      - [Resque](#resque)
+     - [Rest Client](#rest-client)
      - [RSpec](#rspec)
-     - [Shoryuken](#shoryuken)
      - [Sequel](#sequel)
+     - [Shoryuken](#shoryuken)
      - [Sidekiq](#sidekiq)
      - [Sinatra](#sinatra)
      - [Sneakers](#sneakers)
@@ -193,7 +199,7 @@ Install and configure the Datadog Agent to receive traces from your now instrume
     ```ruby
     Datadog.configure do |c|
       # This will activate auto-instrumentation for Rails
-      c.use :rails
+      c.tracing.instrument :rails
     end
     ```
 
@@ -243,8 +249,8 @@ Install and configure the Datadog Agent to receive traces from your now instrume
 
     ```ruby
     require 'opentracing'
-    require 'ddtrace'
-    require 'ddtrace/opentracer'
+    require 'datadog/tracing'
+    require 'datadog/opentracer'
 
     # Activate the Datadog tracer for OpenTracing
     OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new
@@ -274,10 +280,10 @@ After setting up, your services will appear on the [APM services page](https://a
 
 If you aren't using a supported framework instrumentation, you may want to manually instrument your code.
 
-To trace any Ruby code, you can use the `Datadog.tracer.trace` method:
+To trace any Ruby code, you can use the `Datadog::Tracing.trace` method:
 
 ```ruby
-Datadog.tracer.trace(name, options) do |span|
+Datadog::Tracing.trace(name, options) do |span, trace|
   # Wrap this block around the code you want to instrument
   # Additionally, you can modify the span here.
   # e.g. Change the resource name, set tags, etc...
@@ -289,14 +295,15 @@ Where `name` should be a `String` that describes the generic kind of operation b
 And `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Type | Description | Default |
-| --- | --- | --- | --- |
-| `service`     | `String` | The service name which this span belongs (e.g. `'my-web-service'`) | Tracer `default-service`, `$PROGRAM_NAME` or `'ruby'` |
-| `resource`    | `String` | Name of the resource or action being operated on. Traces with the same resource value will be grouped together for the purpose of metrics (but still independently viewable.) Usually domain specific, such as a URL, query, request, etc. (e.g. `'Article#submit'`, `http://example.com/articles/list`.) | `name` of Span. |
-| `span_type`   | `String` | The type of the span (such as `'http'`, `'db'`, etc.) | `nil` |
-| `child_of`    | `Datadog::Span` / `Datadog::Context` | Parent for this span. If not provided, will automatically become current active span. | `nil` |
-| `start_time`  | `Time` | When the span actually starts. Useful when tracing events that have already happened. | `Time.now` |
-| `tags`        | `Hash` | Extra tags which should be added to the span. | `{}` |
-| `on_error`    | `Proc` | Handler invoked when a block is provided to trace, and it raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
+| --------------- | ----------------------- | --- | --- |
+| `autostart`     | `Bool`                  | Whether the time measurement should be started automatically. If `false`, user must call `span.start`. | `true` |
+| `continue_from` | `Datadog::TraceDigest`  | Continues a trace that originated from another execution context. TraceDigest describes the continuation point. | `nil` |
+| `on_error`      | `Proc`                  | Overrides error handling behavior, when a span raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
+| `resource`      | `String`                | Name of the resource or action being operated on. Traces with the same resource value will be grouped together for the purpose of metrics (but still independently viewable.) Usually domain specific, such as a URL, query, request, etc. (e.g. `'Article#submit'`, `http://example.com/articles/list`.) | `name` of Span. |
+| `service`       | `String`                | The service name which this span belongs (e.g. `'my-web-service'`) | Tracer `default-service`, `$PROGRAM_NAME` or `'ruby'` |
+| `start_time`    | `Time`                  | When the span actually starts. Useful when tracing events that have already happened. | `Time.now` |
+| `tags`          | `Hash`                  | Extra tags which should be added to the span. | `{}` |
+| `type`          | `String`                | The type of the span (such as `'http'`, `'db'`, etc.) | `nil` |
 
 It's highly recommended you set both `service` and `resource` at a minimum. Spans without a `service` or `resource` as `nil` will be discarded by the Datadog agent.
 
@@ -304,9 +311,9 @@ Example of manual instrumentation in action:
 
 ```ruby
 get '/posts' do
-  Datadog.tracer.trace('web.request', service: 'my-blog', resource: 'GET /posts') do |span|
+  Datadog::Tracing.trace('web.request', service: 'my-blog', resource: 'GET /posts') do |span|
     # Trace the activerecord call
-    Datadog.tracer.trace('posts.fetch') do
+    Datadog::Tracing.trace('posts.fetch') do
       @posts = Posts.order(created_at: :desc).limit(10)
     end
 
@@ -315,7 +322,7 @@ get '/posts' do
     span.set_tag('posts.count', @posts.length)
 
     # Trace the template rendering
-    Datadog.tracer.trace('template.render') do
+    Datadog::Tracing.trace('template.render') do
       erb :index
     end
   end
@@ -324,37 +331,36 @@ end
 
 ### Asynchronous tracing
 
-It might not always be possible to wrap `Datadog.tracer.trace` around a block of code. Some event or notification based instrumentation might only notify you when an event begins or ends.
+It might not always be possible to wrap `Datadog::Tracing.trace` around a block of code. Some event or notification based instrumentation might only notify you when an event begins or ends.
 
-To trace these operations, you can trace code asynchronously by calling `Datadog.tracer.trace` without a block:
+To trace these operations, you can trace code asynchronously by calling `Datadog::Tracing.trace` without a block:
 
 ```ruby
 # Some instrumentation framework calls this after an event finishes...
 def db_query(start, finish, query)
-  span = Datadog.tracer.trace('database.query')
+  span = Datadog::Tracing.trace('database.query', start_time: start)
   span.resource = query
-  span.start_time = start
   span.finish(finish)
 end
 ```
 
-Calling `Datadog.tracer.trace` without a block will cause the function to return a `Datadog::Span` that is started, but not finished. You can then modify this span however you wish, then close it `finish`.
+Calling `Datadog::Tracing.trace` without a block will cause the function to return a `Datadog::SpanOperation` that is started, but not finished. You can then modify this span however you wish, then close it `finish`.
 
 *You must not leave any unfinished spans.* If any spans are left open when the trace completes, the trace will be discarded. You can [activate debug mode](#tracer-settings) to check for warnings if you suspect this might be happening.
 
-To avoid this scenario when handling start/finish events, you can use `Datadog.tracer.active_span` to get the current active span.
+To avoid this scenario when handling start/finish events, you can use `Datadog::Tracing.active_span` to get the current active span.
 
 ```ruby
 # e.g. ActiveSupport::Notifications calls this when an event starts
 def start(name, id, payload)
   # Start a span
-  Datadog.tracer.trace(name)
+  Datadog::Tracing.trace(name)
 end
 
 # e.g. ActiveSupport::Notifications calls this when an event finishes
 def finish(name, id, payload)
   # Retrieve current active span (thread-safe)
-  current_span = Datadog.tracer.active_span
+  current_span = Datadog::Tracing.active_span
   unless current_span.nil?
     current_span.resource = payload[:query]
     current_span.finish
@@ -368,17 +374,16 @@ You can tag additional information to the current active span from any method. N
 ```ruby
 # e.g. adding tag to active span
 
-current_span = Datadog.tracer.active_span
+current_span = Datadog::Tracing.active_span
 current_span.set_tag('my_tag', 'my_value') unless current_span.nil?
 ```
 
-You can also get the root span of the current active trace using the `active_root_span` method. This method will return `nil` if there is no active trace.
+You can also get the current active trace using the `active_trace` method. This method will return `nil` if there is no active trace.
 
 ```ruby
-# e.g. adding tag to active root span
+# e.g. accessing active trace
 
-current_root_span = Datadog.tracer.active_root_span
-current_root_span.set_tag('my_tag', 'my_value') unless current_root_span.nil?
+current_trace = Datadog::Tracing.active_trace
 ```
 
 ## Integration instrumentation
@@ -388,7 +393,7 @@ Many popular libraries and frameworks are supported out-of-the-box, which can be
 ```ruby
 Datadog.configure do |c|
   # Activates and configures an integration
-  c.use :integration_name, options
+  c.tracing.instrument :integration_name, options
 end
 ```
 
@@ -396,94 +401,86 @@ end
 
 For a list of available integrations, and their configuration options, please refer to the following:
 
-| Name                     | Key                        | Versions Supported: MRI  | Versions Supported: JRuby | How to configure                    | Gem source                                                                     |
-| ------------------------ | -------------------------- | ------------------------ | --------------------------| ----------------------------------- | ------------------------------------------------------------------------------ |
-| Action Cable             | `action_cable`             | `>= 5.0`                 | `>= 5.0`                  | *[Link](#action-cable)*             | *[Link](https://github.com/rails/rails/tree/master/actioncable)*               |
-| Action Mailer            | `action_mailer`            | `>= 5.0`                 | `>= 5.0`                  | *[Link](#action-mailer)*            | *[Link](https://github.com/rails/rails/tree/master/actionmailer)*              |
-| Action View              | `action_view`              | `>= 3.0`                 | `>= 3.0`                  | *[Link](#action-view)*              | *[Link](https://github.com/rails/rails/tree/master/actionview)*                |
-| Active Model Serializers | `active_model_serializers` | `>= 0.9`                 | `>= 0.9`                  | *[Link](#active-model-serializers)* | *[Link](https://github.com/rails-api/active_model_serializers)*                |
-| Action Pack              | `action_pack`              | `>= 3.0`                 | `>= 3.0`                  | *[Link](#action-pack)*              | *[Link](https://github.com/rails/rails/tree/master/actionpack)*                |
-| Active Job               | `active_job`               | `>= 4.2`                 | `>= 4.2`                  | *[Link](#active-job)*               | *[Link](https://github.com/rails/rails/tree/master/activejob)*             |
-| Active Record            | `active_record`            | `>= 3.0`                 | `>= 3.0`                  | *[Link](#active-record)*            | *[Link](https://github.com/rails/rails/tree/master/activerecord)*              |
-| Active Support           | `active_support`           | `>= 3.0`                 | `>= 3.0`                  | *[Link](#active-support)*           | *[Link](https://github.com/rails/rails/tree/master/activesupport)*             |
-| AWS                      | `aws`                      | `>= 2.0`                 | `>= 2.0`                  | *[Link](#aws)*                      | *[Link](https://github.com/aws/aws-sdk-ruby)*                                  |
-| Concurrent Ruby          | `concurrent_ruby`          | `>= 0.9`                 | `>= 0.9`                  | *[Link](#concurrent-ruby)*          | *[Link](https://github.com/ruby-concurrency/concurrent-ruby)*                  |
-| Cucumber                 | `cucumber`                 | `>= 3.0`                 | `>= 1.7.16`               | *[Link](#cucumber)*                 | *[Link](https://github.com/cucumber/cucumber-ruby)*                            |
-| Dalli                    | `dalli`                    | `>= 2.0`                 | `>= 2.0`                  | *[Link](#dalli)*                    | *[Link](https://github.com/petergoldstein/dalli)*                              |
-| DelayedJob               | `delayed_job`              | `>= 4.1`                 | `>= 4.1`                  | *[Link](#delayedjob)*               | *[Link](https://github.com/collectiveidea/delayed_job)*                        |
-| Elasticsearch            | `elasticsearch`            | `>= 1.0`                 | `>= 1.0`                  | *[Link](#elasticsearch)*            | *[Link](https://github.com/elastic/elasticsearch-ruby)*                        |
-| Ethon                    | `ethon`                    | `>= 0.11`                | `>= 0.11`                 | *[Link](#ethon)*                    | *[Link](https://github.com/typhoeus/ethon)*                                    |
-| Excon                    | `excon`                    | `>= 0.50`                | `>= 0.50`                 | *[Link](#excon)*                    | *[Link](https://github.com/excon/excon)*                                       |
-| Faraday                  | `faraday`                  | `>= 0.14`                | `>= 0.14`                 | *[Link](#faraday)*                  | *[Link](https://github.com/lostisland/faraday)*                                |
-| Grape                    | `grape`                    | `>= 1.0`                 | `>= 1.0`                  | *[Link](#grape)*                    | *[Link](https://github.com/ruby-grape/grape)*                                  |
-| GraphQL                  | `graphql`                  | `>= 1.7.9`               | `>= 1.7.9`                | *[Link](#graphql)*                  | *[Link](https://github.com/rmosolgo/graphql-ruby)*                             |
-| gRPC                     | `grpc`                     | `>= 1.7`                 | *gem not available*       | *[Link](#grpc)*                     | *[Link](https://github.com/grpc/grpc/tree/master/src/rubyc)*                   |
-| http.rb                  | `httprb`                   | `>= 2.0`                 | `>= 2.0`                  | *[Link](#httprb)*                  | *[Link](https://github.com/httprb/http)*                                       |
-| httpclient                | `httpclient`              | `>= 2.2`                 | `>= 2.2`                  | *[Link](#httpclient)*               | *[Link](https://github.com/nahi/httpclient)*                                     |
-| httpx                     | `httpx`                   | `>= 0.11`                | `>= 0.11`                 | *[Link](#httpx)*                    | *[Link](https://gitlab.com/honeyryderchuck/httpx)*                             |
-| Kafka                    | `ruby-kafka`               | `>= 0.7.10`              | `>= 0.7.10`               | *[Link](#kafka)*                    | *[Link](https://github.com/zendesk/ruby-kafka)*                                |
-| Makara (through Active Record) | `makara`             | `>= 0.3.5`               | `>= 0.3.5`                | *[Link](#active-record)*            | *[Link](https://github.com/instacart/makara)*                                  |
-| MongoDB                  | `mongo`                    | `>= 2.1`                 | `>= 2.1`                  | *[Link](#mongodb)*                  | *[Link](https://github.com/mongodb/mongo-ruby-driver)*                         |
-| MySQL2                   | `mysql2`                   | `>= 0.3.21`              | *gem not available*       | *[Link](#mysql2)*                   | *[Link](https://github.com/brianmario/mysql2)*                                 |
-| Net/HTTP                 | `http`                     | *(Any supported Ruby)*   | *(Any supported Ruby)*    | *[Link](#nethttp)*                  | *[Link](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)* |
-| Presto                   | `presto`                   | `>= 0.5.14`              | `>= 0.5.14`               | *[Link](#presto)*                   | *[Link](https://github.com/treasure-data/presto-client-ruby)*                  |
-| Qless                    | `qless`                    | `>= 0.10.0`              | `>= 0.10.0`               | *[Link](#qless)*                    | *[Link](https://github.com/seomoz/qless)*                                      |
-| Que                      | `que`                      | `>= 1.0.0.beta2`         | `>= 1.0.0.beta2`          | *[Link](#que)*                      | *[Link](https://github.com/que-rb/que)*                                        |
-| Racecar                  | `racecar`                  | `>= 0.3.5`               | `>= 0.3.5`                | *[Link](#racecar)*                  | *[Link](https://github.com/zendesk/racecar)*                                   |
-| Rack                     | `rack`                     | `>= 1.1`                 | `>= 1.1`                  | *[Link](#rack)*                     | *[Link](https://github.com/rack/rack)*                                         |
-| Rails                    | `rails`                    | `>= 3.0`                 | `>= 3.0`                  | *[Link](#rails)*                    | *[Link](https://github.com/rails/rails)*                                       |
-| Rake                     | `rake`                     | `>= 12.0`                | `>= 12.0`                 | *[Link](#rake)*                     | *[Link](https://github.com/ruby/rake)*                                         |
-| Redis                    | `redis`                    | `>= 3.2`                 | `>= 3.2`                  | *[Link](#redis)*                    | *[Link](https://github.com/redis/redis-rb)*                                    |
-| Resque                   | `resque`                   | `>= 1.0`                 | `>= 1.0`                  | *[Link](#resque)*                   | *[Link](https://github.com/resque/resque)*                                     |
-| Rest Client              | `rest-client`              | `>= 1.8`                 | `>= 1.8`                  | *[Link](#rest-client)*              | *[Link](https://github.com/rest-client/rest-client)*                           |
-| RSpec                    | `rspec`.                   | `>= 3.0.0`               | `>= 3.0.0`                | *[Link](#rspec)*.                   | *[Link](https://github.com/rspec/rspec)*                                       |
-| Sequel                   | `sequel`                   | `>= 3.41`                | `>= 3.41`                 | *[Link](#sequel)*                   | *[Link](https://github.com/jeremyevans/sequel)*                                |
-| Shoryuken                | `shoryuken`                | `>= 3.2`                 | `>= 3.2`                  | *[Link](#shoryuken)*                | *[Link](https://github.com/phstc/shoryuken)*                                   |
-| Sidekiq                  | `sidekiq`                  | `>= 3.5.4`               | `>= 3.5.4`                | *[Link](#sidekiq)*                  | *[Link](https://github.com/mperham/sidekiq)*                                   |
-| Sinatra                  | `sinatra`                  | `>= 1.4`                 | `>= 1.4`                  | *[Link](#sinatra)*                  | *[Link](https://github.com/sinatra/sinatra)*                                   |
-| Sneakers                 | `sneakers`                 | `>= 2.12.0`              | `>= 2.12.0`               | *[Link](#sneakers)*                 | *[Link](https://github.com/jondot/sneakers)*                                   |
-| Sucker Punch             | `sucker_punch`             | `>= 2.0`                 | `>= 2.0`                  | *[Link](#sucker-punch)*             | *[Link](https://github.com/brandonhilkert/sucker_punch)*                       |
-
-### Action Cable
-
-The Action Cable integration traces broadcast messages and channel actions.
-
-You can enable it through `Datadog.configure`:
+| Name                       | Key                        | Versions Supported: MRI  | Versions Supported: JRuby | How to configure                    | Gem source                                                                     |
+| -------------------------- | -------------------------- | ------------------------ | --------------------------| ----------------------------------- | ------------------------------------------------------------------------------ |
+| Action Cable               | `action_cable`             | `>= 5.0`                 | `>= 5.0`                  | *[Link](#action-cable)*             | *[Link](https://github.com/rails/rails/tree/master/actioncable)*               |
+| Action Mailer              | `action_mailer`            | `>= 5.0`                 | `>= 5.0`                  | *[Link](#action-mailer)*            | *[Link](https://github.com/rails/rails/tree/master/actionmailer)*              |
+| Action Pack                | `action_pack`              | `>= 3.2`                 | `>= 3.2`                  | *[Link](#action-pack)*              | *[Link](https://github.com/rails/rails/tree/master/actionpack)*                |
+| Action View                | `action_view`              | `>= 3.2`                 | `>= 3.2`                  | *[Link](#action-view)*              | *[Link](https://github.com/rails/rails/tree/master/actionview)*                |
+| Active Job                 | `active_job`               | `>= 4.2`                 | `>= 4.2`                  | *[Link](#active-job)*               | *[Link](https://github.com/rails/rails/tree/master/activejob)*             |
+| Active Model Serializers   | `active_model_serializers` | `>= 0.9`                 | `>= 0.9`                  | *[Link](#active-model-serializers)* | *[Link](https://github.com/rails-api/active_model_serializers)*                |
+| Active Record              | `active_record`            | `>= 3.2`                 | `>= 3.2`                  | *[Link](#active-record)*            | *[Link](https://github.com/rails/rails/tree/master/activerecord)*              |
+| Active Support             | `active_support`           | `>= 3.2`                 | `>= 3.2`                  | *[Link](#active-support)*           | *[Link](https://github.com/rails/rails/tree/master/activesupport)*             |
+| AWS                        | `aws`                      | `>= 2.0`                 | `>= 2.0`                  | *[Link](#aws)*                      | *[Link](https://github.com/aws/aws-sdk-ruby)*                                  |
+| Concurrent Ruby            | `concurrent_ruby`          | `>= 0.9`                 | `>= 0.9`                  | *[Link](#concurrent-ruby)*          | *[Link](https://github.com/ruby-concurrency/concurrent-ruby)*                  |
+| Dalli                      | `dalli`                    | `>= 2.0`                 | `>= 2.0`                  | *[Link](#dalli)*                    | *[Link](https://github.com/petergoldstein/dalli)*                              |
+| DelayedJob                 | `delayed_job`              | `>= 4.1`                 | `>= 4.1`                  | *[Link](#delayedjob)*               | *[Link](https://github.com/collectiveidea/delayed_job)*                        |
+| Elasticsearch              | `elasticsearch`            | `>= 1.0`                 | `>= 1.0`                  | *[Link](#elasticsearch)*            | *[Link](https://github.com/elastic/elasticsearch-ruby)*                        |
+| Ethon                      | `ethon`                    | `>= 0.11`                | `>= 0.11`                 | *[Link](#ethon)*                    | *[Link](https://github.com/typhoeus/ethon)*                                    |
+| Excon                      | `excon`                    | `>= 0.50`                | `>= 0.50`                 | *[Link](#excon)*                    | *[Link](https://github.com/excon/excon)*                                       |
+| Faraday                    | `faraday`                  | `>= 0.14`                | `>= 0.14`                 | *[Link](#faraday)*                  | *[Link](https://github.com/lostisland/faraday)*                                |
+| Grape                      | `grape`                    | `>= 1.0`                 | `>= 1.0`                  | *[Link](#grape)*                    | *[Link](https://github.com/ruby-grape/grape)*                                  |
+| GraphQL                    | `graphql`                  | `>= 1.7.9`               | `>= 1.7.9`                | *[Link](#graphql)*                  | *[Link](https://github.com/rmosolgo/graphql-ruby)*                             |
+| gRPC                       | `grpc`                     | `>= 1.7`                 | *gem not available*       | *[Link](#grpc)*                     | *[Link](https://github.com/grpc/grpc/tree/master/src/rubyc)*                   |
+| http.rb                    | `httprb`                   | `>= 2.0`                 | `>= 2.0`                  | *[Link](#httprb)*                   | *[Link](https://github.com/httprb/http)*                                       |
+| httpclient                 | `httpclient`               | `>= 2.2`                 | `>= 2.2`                  | *[Link](#httpclient)*               | *[Link](https://github.com/nahi/httpclient)*                                     |
+| httpx                      | `httpx`                    | `>= 0.11`                | `>= 0.11`                 | *[Link](#httpx)*                    | *[Link](https://gitlab.com/honeyryderchuck/httpx)*                             |
+| Kafka                      | `ruby-kafka`               | `>= 0.7.10`              | `>= 0.7.10`               | *[Link](#kafka)*                    | *[Link](https://github.com/zendesk/ruby-kafka)*                                |
+| Makara (via Active Record) | `makara`                   | `>= 0.3.5`               | `>= 0.3.5`                | *[Link](#active-record)*            | *[Link](https://github.com/instacart/makara)*                                  |
+| MongoDB                    | `mongo`                    | `>= 2.1`                 | `>= 2.1`                  | *[Link](#mongodb)*                  | *[Link](https://github.com/mongodb/mongo-ruby-driver)*                         |
+| MySQL2                     | `mysql2`                   | `>= 0.3.21`              | *gem not available*       | *[Link](#mysql2)*                   | *[Link](https://github.com/brianmario/mysql2)*                                 |
+| Net/HTTP                   | `http`                     | *(Any supported Ruby)*   | *(Any supported Ruby)*    | *[Link](#nethttp)*                  | *[Link](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)* |
+| Presto                     | `presto`                   | `>= 0.5.14`              | `>= 0.5.14`               | *[Link](#presto)*                   | *[Link](https://github.com/treasure-data/presto-client-ruby)*                  |
+| Qless                      | `qless`                    | `>= 0.10.0`              | `>= 0.10.0`               | *[Link](#qless)*                    | *[Link](https://github.com/seomoz/qless)*                                      |
+| Que                        | `que`                      | `>= 1.0.0.beta2`         | `>= 1.0.0.beta2`          | *[Link](#que)*                      | *[Link](https://github.com/que-rb/que)*                                        |
+| Racecar                    | `racecar`                  | `>= 0.3.5`               | `>= 0.3.5`                | *[Link](#racecar)*                  | *[Link](https://github.com/zendesk/racecar)*                                   |
+| Rack                       | `rack`                     | `>= 1.1`                 | `>= 1.1`                  | *[Link](#rack)*                     | *[Link](https://github.com/rack/rack)*                                         |
+| Rails                      | `rails`                    | `>= 3.2`                 | `>= 3.2`                  | *[Link](#rails)*                    | *[Link](https://github.com/rails/rails)*                                       |
+| Rake                       | `rake`                     | `>= 12.0`                | `>= 12.0`                 | *[Link](#rake)*                     | *[Link](https://github.com/ruby/rake)*                                         |
+| Redis                      | `redis`                    | `>= 3.2`                 | `>= 3.2`                  | *[Link](#redis)*                    | *[Link](https://github.com/redis/redis-rb)*                                    |
+| Resque                     | `resque`                   | `>= 1.0`                 | `>= 1.0`                  | *[Link](#resque)*                   | *[Link](https://github.com/resque/resque)*                                     |
+| Rest Client                | `rest-client`              | `>= 1.8`                 | `>= 1.8`                  | *[Link](#rest-client)*              | *[Link](https://github.com/rest-client/rest-client)*                           |
+| Sequel                     | `sequel`                   | `>= 3.41`                | `>= 3.41`                 | *[Link](#sequel)*                   | *[Link](https://github.com/jeremyevans/sequel)*                                |
+| Shoryuken                  | `shoryuken`                | `>= 3.2`                 | `>= 3.2`                  | *[Link](#shoryuken)*                | *[Link](https://github.com/phstc/shoryuken)*                                   |
+| Sidekiq                    | `sidekiq`                  | `>= 3.5.4`               | `>= 3.5.4`                | *[Link](#sidekiq)*                  | *[Link](https://github.com/mperham/sidekiq)*                                   |
+| Sinatra                    | `sinatra`                  | `>= 1.4`                 | `>= 1.4`                  | *[Link](#sinatra)*                  | *[Link](https://github.com/sinatra/sinatra)*                                   |
+| Sneakers                   | `sneakers`                 | `>= 2.12.0`              | `>= 2.12.0`               | *[Link](#sneakers)*                 | *[Link](https://github.com/jondot/sneakers)*                                   |
+| Sucker Punch               | `sucker_punch`             | `>= 2.0`                 | `>= 2.0`                  | *[Link](#sucker-punch)*             | *[Link](https://github.com/brandonhilkert/sucker_punch)*                       |
+
+#### CI Visibility
+
+For Datadog CI Visibility, library instrumentation can be activated and configured by using the following `Datadog.configure` API:
 
 ```ruby
-require 'ddtrace'
-
 Datadog.configure do |c|
-  c.use :action_cable, options
+  # Activates and configures an integration
+  c.ci.instrument :integration_name, options
 end
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
+`options` is a `Hash` of integration-specific configuration settings.
 
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `action_cable` instrumentation | `'action_cable'` |
+These are the available CI Visibility integrations:
 
-### Action View
+| Name      | Key        | Versions Supported: MRI | Versions Supported: JRuby | How to configure    | Gem source                                          |
+|-----------|------------|-------------------------|---------------------------|---------------------|-----------------------------------------------------|
+| Cucumber  | `cucumber` | `>= 3.0`                | `>= 1.7.16`               | *[Link](#cucumber)* | *[Link](https://github.com/cucumber/cucumber-ruby)* |
+| RSpec     | `rspec`    | `>= 3.0.0`              | `>= 3.0.0`                | *[Link](#rspec)*    | *[Link](https://github.com/rspec/rspec)*            |
 
-Most of the time, Active Support is set up as part of Rails, but it can be activated separately:
+### Action Cable
+
+The Action Cable integration traces broadcast messages and channel actions.
+
+You can enable it through `Datadog.configure`:
 
 ```ruby
-require 'actionview'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :action_view, options
+  c.tracing.instrument :action_cable
 end
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
-
-| Key | Description | Default |
-| ---| --- | --- |
-| `service_name` | Service name used for rendering instrumentation. | `action_view` |
-| `template_base_path` | Used when the template name is parsed. If you don't store your templates in the `views/` folder, you may need to change this value | `'views/'` |
-
 ### Action Mailer
 
 The Action Mailer integration provides tracing for Rails 5 ActionMailer actions.
@@ -492,8 +489,8 @@ You can enable it through `Datadog.configure`:
 
 ```ruby
 require 'ddtrace'
- Datadog.configure do |c|
-  c.use :action_mailer, options
+Datadog.configure do |c|
+  c.tracing.instrument :action_mailer, options
 end
 ```
 
@@ -502,39 +499,31 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
-| `service_name` | Service name used for `action_mailer` instrumentation | `'action_mailer'` |
 | `email_data` | Whether or not to append additional email payload metadata to `action_mailer.deliver` spans. Fields include `['subject', 'to', 'from', 'bcc', 'cc', 'date', 'perform_deliveries']`. | `false` |
 
-### Active Model Serializers
+### Action Pack
 
-The Active Model Serializers integration traces the `serialize` event for version 0.9+ and the `render` event for version 0.10+.
+Most of the time, Action Pack is set up as part of Rails, but it can be activated separately:
 
 ```ruby
-require 'active_model_serializers'
+require 'actionpack'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :active_model_serializers, options
+  c.tracing.instrument :action_pack
 end
-
-my_object = MyModel.new(name: 'my object')
-ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash
 ```
 
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `active_model_serializers` instrumentation. | `'active_model_serializers'` |
-
-### Action Pack
+### Action View
 
-Most of the time, Action Pack is set up as part of Rails, but it can be activated separately:
+Most of the time, Action View is set up as part of Rails, but it can be activated separately:
 
 ```ruby
-require 'actionpack'
+require 'actionview'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :action_pack, options
+  c.tracing.instrument :action_view, options
 end
 ```
 
@@ -542,7 +531,7 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | ---| --- | --- |
-| `service_name` | Service name used for rendering instrumentation. | `action_pack` |
+| `template_base_path` | Used when the template name is parsed. If you don't store your templates in the `views/` folder, you may need to change this value | `'views/'` |
 
 ### Active Job
 
@@ -553,18 +542,27 @@ require 'active_job'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :active_job, options
+  c.tracing.instrument :active_job
 end
 
 ExampleJob.perform_later
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
+### Active Model Serializers
 
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `active_job` instrumentation | `'active_job'` |
-| `log_injection` | Automatically enables injection [Trace Correlation](#trace-correlation) information, such as `dd.trace_id`, into Active Job logs. Supports the default logger (`ActiveSupport::TaggedLogging`) and `Lograge`. Details on the format of Trace Correlation information can be found in the [Trace Correlation](#trace-correlation) section. | `false` |
+The Active Model Serializers integration traces the `serialize` event for version 0.9+ and the `render` event for version 0.10+.
+
+```ruby
+require 'active_model_serializers'
+require 'ddtrace'
+
+Datadog.configure do |c|
+  c.tracing.instrument :active_model_serializers
+end
+
+my_object = MyModel.new(name: 'my object')
+ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash
+```
 
 ### Active Record
 
@@ -577,7 +575,7 @@ require 'active_record'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :active_record, options
+  c.tracing.instrument :active_record, options
 end
 
 Dir::Tmpname.create(['test', '.sqlite']) do |db|
@@ -591,7 +589,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | ---| --- | --- |
-| `orm_service_name` | Service name used for the mapping portion of query results to ActiveRecord objects. Inherits service name from parent by default. | _parent.service_name_ (e.g. `'mysql2'`) |
 | `service_name` | Service name used for database portion of `active_record` instrumentation. | Name of database adapter (e.g. `'mysql2'`) |
 
 **Configuring trace settings per database**
@@ -607,22 +604,22 @@ You can configure trace settings per database connection by using the `describes
 Datadog.configure do |c|
   # Symbol matching your database connection in config/database.yml
   # Only available if you are using Rails with ActiveRecord.
-  c.use :active_record, describes: :secondary_database, service_name: 'secondary-db'
+  c.tracing.instrument :active_record, describes: :secondary_database, service_name: 'secondary-db'
 
   # Block configuration pattern.
-  c.use :active_record, describes: :secondary_database do |second_db|
+  c.tracing.instrument :active_record, describes: :secondary_database do |second_db|
     second_db.service_name = 'secondary-db'
   end
 
   # Connection string with the following connection settings:
   # adapter, username, host, port, database
   # Other fields are ignored.
-  c.use :active_record, describes: 'mysql2://root@127.0.0.1:3306/mysql', service_name: 'secondary-db'
+  c.tracing.instrument :active_record, describes: 'mysql2://root@127.0.0.1:3306/mysql', service_name: 'secondary-db'
 
   # Hash with following connection settings:
   # adapter, username, host, port, database
   # Other fields are ignored.
-  c.use :active_record, describes: {
+  c.tracing.instrument :active_record, describes: {
       adapter:  'mysql2',
       host:     '127.0.0.1',
       port:     '3306',
@@ -632,8 +629,8 @@ Datadog.configure do |c|
     service_name: 'secondary-db'
 
   # If using the `makara` gem, it's possible to match on connection `role`:
-  c.use :active_record, describes: { makara_role: 'primary' }, service_name: 'primary-db'
-  c.use :active_record, describes: { makara_role: 'replica' }, service_name: 'secondary-db'
+  c.tracing.instrument :active_record, describes: { makara_role: 'primary' }, service_name: 'primary-db'
+  c.tracing.instrument :active_record, describes: { makara_role: 'replica' }, service_name: 'secondary-db'
 end
 ```
 
@@ -642,23 +639,23 @@ You can also create configurations based on partial matching of database connect
 ```ruby
 Datadog.configure do |c|
   # Matches any connection on host `127.0.0.1`.
-  c.use :active_record, describes: { host:  '127.0.0.1' }, service_name: 'local-db'
+  c.tracing.instrument :active_record, describes: { host:  '127.0.0.1' }, service_name: 'local-db'
 
   # Matches any `mysql2` connection.
-  c.use :active_record, describes: { adapter: 'mysql2'}, service_name: 'mysql-db'
+  c.tracing.instrument :active_record, describes: { adapter: 'mysql2'}, service_name: 'mysql-db'
 
   # Matches any `mysql2` connection to the `reports` database.
   #
   # In case of multiple matching `describe` configurations, the latest one applies.
   # In this case a connection with both adapter `mysql` and database `reports`
   # will be configured `service_name: 'reports-db'`, not `service_name: 'mysql-db'`.
-  c.use :active_record, describes: { adapter: 'mysql2', database:  'reports'}, service_name: 'reports-db'
+  c.tracing.instrument :active_record, describes: { adapter: 'mysql2', database:  'reports'}, service_name: 'reports-db'
 end
 ```
 
 When multiple `describes` configurations match a connection, the latest configured rule that matches will be applied.
 
-If ActiveRecord traces an event that uses a connection that matches a key defined by `describes`, it will use the trace settings assigned to that connection. If the connection does not match any of the described connections, it will use default settings defined by `c.use :active_record` instead.
+If ActiveRecord traces an event that uses a connection that matches a key defined by `describes`, it will use the trace settings assigned to that connection. If the connection does not match any of the described connections, it will use default settings defined by `c.tracing.instrument :active_record` instead.
 
 ### Active Support
 
@@ -669,7 +666,7 @@ require 'activesupport'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :active_support, options
+  c.tracing.instrument :active_support, options
 end
 
 cache = ActiveSupport::Cache::MemoryStore.new
@@ -691,7 +688,7 @@ require 'aws-sdk'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :aws, options
+  c.tracing.instrument :aws, options
 end
 
 # Perform traced call
@@ -715,21 +712,15 @@ To activate your integration, use the `Datadog.configure` method:
 # Inside Rails initializer or equivalent
 Datadog.configure do |c|
   # Patches ::Concurrent::Future to use ExecutorService that propagates context
-  c.use :concurrent_ruby, options
+  c.tracing.instrument :concurrent_ruby
 end
 
 # Pass context into code executed within Concurrent::Future
-Datadog.tracer.trace('outer') do
-  Concurrent::Future.execute { Datadog.tracer.trace('inner') { } }.wait
+Datadog::Tracing.trace('outer') do
+  Concurrent::Future.execute { Datadog::Tracing.trace('inner') { } }.wait
 end
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
-
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `concurrent-ruby` instrumentation | `'concurrent-ruby'` |
-
 ### Cucumber
 
 Cucumber integration will trace all executions of scenarios and steps when using `cucumber` framework.
@@ -742,7 +733,7 @@ require 'ddtrace'
 
 # Configure default Cucumber integration
 Datadog.configure do |c|
-  c.use :cucumber, options
+  c.ci.instrument :cucumber, options
 end
 
 # Example of how to attach tags from scenario to active span
@@ -775,7 +766,7 @@ require 'ddtrace'
 
 # Configure default Dalli tracing behavior
 Datadog.configure do |c|
-  c.use :dalli, options
+  c.tracing.instrument :dalli, options
 end
 
 # Configure Dalli tracing behavior for single client
@@ -799,7 +790,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :delayed_job, options
+  c.tracing.instrument :delayed_job, options
 end
 ```
 
@@ -807,8 +798,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `service_name` | Service name used for `DelayedJob` instrumentation | `'delayed_job'` |
-| `client_service_name` | Service name used for client-side `DelayedJob` instrumentation | `'delayed_job-client'` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
 
 ### Elasticsearch
@@ -820,7 +809,7 @@ require 'elasticsearch/transport'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :elasticsearch, options
+  c.tracing.instrument :elasticsearch, options
 end
 
 # Perform a query to Elasticsearch
@@ -843,10 +832,10 @@ The `ethon` integration will trace any HTTP request through `Easy` or `Multi` ob
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :ethon, options
+  c.tracing.instrument :ethon, options
 
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :ethon, describes: /user-[^.]+\.example\.com/ do |ethon|
+  c.tracing.instrument :ethon, describes: /user-[^.]+\.example\.com/ do |ethon|
     ethon.service_name = 'user.example.com'
     ethon.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -871,10 +860,10 @@ require 'ddtrace'
 
 # Configure default Excon tracing behavior
 Datadog.configure do |c|
-  c.use :excon, options
+  c.tracing.instrument :excon, options
 
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :excon, describes: /user-[^.]+\.example\.com/ do |excon|
+  c.tracing.instrument :excon, describes: /user-[^.]+\.example\.com/ do |excon|
     excon.service_name = 'user.example.com'
     excon.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -901,7 +890,7 @@ If you use multiple connections with Excon, you can give each of them different
 # Wrap the Datadog tracing middleware around the default middleware stack
 Excon.new(
   'http://example.com',
-  middlewares: Datadog::Contrib::Excon::Middleware.with(options).around_default_stack
+  middlewares: Datadog::Tracing::Contrib::Excon::Middleware.with(options).around_default_stack
 )
 
 # Insert the middleware into a custom middleware stack.
@@ -910,7 +899,7 @@ Excon.new(
   'http://example.com',
   middlewares: [
     Excon::Middleware::ResponseParser,
-    Datadog::Contrib::Excon::Middleware.with(options),
+    Datadog::Tracing::Contrib::Excon::Middleware.with(options),
     Excon::Middleware::Idempotent
   ]
 )
@@ -928,10 +917,10 @@ require 'ddtrace'
 
 # Configure default Faraday tracing behavior
 Datadog.configure do |c|
-  c.use :faraday, options
+  c.tracing.instrument :faraday, options
 
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :faraday, describes: /user-[^.]+\.example\.com/ do |faraday|
+  c.tracing.instrument :faraday, describes: /user-[^.]+\.example\.com/ do |faraday|
     faraday.service_name = 'user.example.com'
     faraday.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -967,7 +956,7 @@ require 'grape'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :grape, options
+  c.tracing.instrument :grape, options
 end
 
 # Then define your application
@@ -984,7 +973,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `enabled` | Defines whether Grape should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
-| `service_name` | Service name used for `grape` instrumentation | `'grape'` |
 | `error_statuses`| Defines a status code or range of status codes which should be marked as errors. `'404,405,500-599'` or `[404,405,'500-599']` | `nil` |
 
 ### GraphQL
@@ -996,7 +984,7 @@ To activate your integration, use the `Datadog.configure` method:
 ```ruby
 # Inside Rails initializer or equivalent
 Datadog.configure do |c|
-  c.use :graphql, schemas: [YourSchema], options
+  c.tracing.instrument :graphql, schemas: [YourSchema], options
 end
 
 # Then run a GraphQL query
@@ -1007,7 +995,6 @@ The `use :graphql` method accepts the following parameters. Additional options c
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `service_name` | Service name used for `graphql` instrumentation | `'ruby-graphql'` |
 | `schemas` | Required. Array of `GraphQL::Schema` objects which to trace. Tracing will be added to all the schemas listed, using the options provided to this configuration. If you do not provide any, then tracing will not be activated. | `[]` |
 
 **Manually configuring GraphQL schemas**
@@ -1067,7 +1054,7 @@ require 'grpc'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :grpc, options
+  c.tracing.instrument :grpc, options
 end
 
 # Server side
@@ -1093,7 +1080,7 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 In situations where you have multiple clients calling multiple distinct services, you may pass the Datadog interceptor directly, like so
 
 ```ruby
-configured_interceptor = Datadog::Contrib::GRPC::DatadogInterceptor::Client.new do |c|
+configured_interceptor = Datadog::Tracing::Contrib::GRPC::DatadogInterceptor::Client.new do |c|
   c.service_name = "Alternate"
 end
 
@@ -1114,9 +1101,9 @@ The http.rb integration will trace any HTTP call using the Http.rb gem.
 require 'http'
 require 'ddtrace'
 Datadog.configure do |c|
-  c.use :httprb, options
+  c.tracing.instrument :httprb, options
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :httprb, describes: /user-[^.]+\.example\.com/ do |httprb|
+  c.tracing.instrument :httprb, describes: /user-[^.]+\.example\.com/ do |httprb|
     httprb.service_name = 'user.example.com'
     httprb.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -1139,9 +1126,9 @@ The httpclient integration will trace any HTTP call using the httpclient gem.
 require 'httpclient'
 require 'ddtrace'
 Datadog.configure do |c|
-  c.use :httpclient, options
+  c.tracing.instrument :httpclient, options
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :httpclient, describes: /user-[^.]+\.example\.com/ do |httpclient|
+  c.tracing.instrument :httpclient, describes: /user-[^.]+\.example\.com/ do |httpclient|
     httpclient.service_name = 'user.example.com'
     httpclient.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -1165,10 +1152,10 @@ require "ddtrace"
 require "httpx/adapters/datadog"
 
 Datadog.configure do |c|
-  c.use :httpx
+  c.tracing.instrument :httpx
 
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :httpx, describes: /user-[^.]+\.example\.com/ do |http|
+  c.tracing.instrument :httpx, describes: /user-[^.]+\.example\.com/ do |http|
     http.service_name = 'user.example.com'
     http.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -1187,17 +1174,10 @@ require 'kafka'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :kafka, options
+  c.tracing.instrument :kafka
 end
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
-
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `kafka` instrumentation | `'kafka'` |
-| `tracer` | `Datadog::Tracer` used to perform instrumentation. Usually you don't need to set this. | `Datadog.tracer` |
-
 ### MongoDB
 
 The integration traces any `Command` that is sent from the [MongoDB Ruby Driver](https://github.com/mongodb/mongo-ruby-driver) to a MongoDB cluster. By extension, Object Document Mappers (ODM) such as Mongoid are automatically instrumented if they use the official Ruby driver. To activate the integration, simply:
@@ -1207,7 +1187,7 @@ require 'mongo'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :mongo, options
+  c.tracing.instrument :mongo, options
 end
 
 # Create a MongoDB client and use it as usual
@@ -1216,7 +1196,7 @@ collection = client[:people]
 collection.insert_one({ name: 'Steve' })
 
 # In case you want to override the global configuration for a certain client instance
-Datadog.configure(client, options)
+Datadog.configure_onto(client, **options)
 ```
 
 Where `options` is an optional `Hash` that accepts the following parameters:
@@ -1238,10 +1218,10 @@ You can configure trace settings per connection by using the `describes` option:
 
 Datadog.configure do |c|
   # Network connection string
-  c.use :mongo, describes: '127.0.0.1:27017', service_name: 'mongo-primary'
+  c.tracing.instrument :mongo, describes: '127.0.0.1:27017', service_name: 'mongo-primary'
 
   # Network connection regular expression
-  c.use :mongo, describes: /localhost.*/, service_name: 'mongo-secondary'
+  c.tracing.instrument :mongo, describes: /localhost.*/, service_name: 'mongo-secondary'
 end
 
 client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
@@ -1266,7 +1246,7 @@ require 'mysql2'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :mysql2, options
+  c.tracing.instrument :mysql2, options
 end
 
 client = Mysql2::Client.new(:host => "localhost", :username => "root")
@@ -1288,10 +1268,10 @@ require 'net/http'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :http, options
+  c.tracing.instrument :http, options
 
   # optionally, specify a different service name for hostnames matching a regex
-  c.use :http, describes: /user-[^.]+\.example\.com/ do |http|
+  c.tracing.instrument :http, describes: /user-[^.]+\.example\.com/ do |http|
     http.service_name = 'user.example.com'
     http.split_by_domain = false # Only necessary if split_by_domain is true by default
   end
@@ -1313,11 +1293,11 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | `service_name` | Service name used for `http` instrumentation | `'net/http'` |
 | `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
 
-If you wish to configure each connection object individually, you may use the `Datadog.configure` as it follows:
+If you wish to configure each connection object individually, you may use the `Datadog.configure_onto` as it follows:
 
 ```ruby
 client = Net::HTTP.new(host, port)
-Datadog.configure(client, options)
+Datadog.configure_onto(client, **options)
 ```
 
 ### Presto
@@ -1329,7 +1309,7 @@ require 'presto-client'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :presto, options
+  c.tracing.instrument :presto, options
 end
 
 client = Presto::Client.new(
@@ -1361,7 +1341,7 @@ To add tracing to a Qless job:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :qless, options
+  c.tracing.instrument :qless, options
 end
 ```
 
@@ -1369,7 +1349,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `service_name` | Service name used for `qless` instrumentation | `'qless'` |
 | `tag_job_data` | Enable tagging with job arguments. true for on, false for off. | `false` |
 | `tag_job_tags` | Enable tagging with job tags. true for on, false for off. | `false` |
 
@@ -1383,7 +1362,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :que, options
+  c.tracing.instrument :que, options
 end
 ```
 
@@ -1392,7 +1371,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `enabled` | Defines whether Que should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
-| `service_name` | Service name used for `que` instrumentation | `'que'` |
 | `tag_args` | Enable tagging of a job's args field. `true` for on, `false` for off. | `false` |
 | `tag_data` | Enable tagging of a job's data field. `true` for on, `false` for off. | `false` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
@@ -1407,7 +1385,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :racecar, options
+  c.tracing.instrument :racecar, options
 end
 ```
 
@@ -1428,10 +1406,10 @@ This integration is automatically activated with web frameworks like Rails. If y
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :rack, options
+  c.tracing.instrument :rack, options
 end
 
-use Datadog::Contrib::Rack::TraceMiddleware
+use Datadog::Tracing::Contrib::Rack::TraceMiddleware
 
 app = proc do |env|
   [ 200, {'Content-Type' => 'text/plain'}, ['OK'] ]
@@ -1454,7 +1432,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | `quantize.query.exclude` | Defines which values should be removed entirely. Excludes nothing by default. May be an Array of strings, or `:all` to remove the query string entirely. Option must be nested inside the `query` option. | `nil` |
 | `quantize.fragment` | Defines behavior for URL fragments. Removes fragments by default. May be `:show` to show URL fragments. Option must be nested inside the `quantize` option. | `nil` |
 | `request_queuing` | Track HTTP request time spent in the queue of the frontend server. See [HTTP request queuing](#http-request-queuing) for setup details. Set to `true` to enable. | `false` |
-| `service_name` | Service name used for `rack` instrumentation | `'rack'` |
 | `web_service_name` | Service name for frontend server request queuing spans. (e.g. `'nginx'`) | `'web-server'` |
 
 **Configuring URL quantization behavior**
@@ -1467,23 +1444,23 @@ Datadog.configure do |c|
 
   # Show values for any query string parameter matching 'category_id' exactly
   # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id=1&sort_by
-  c.use :rack, quantize: { query: { show: ['category_id'] } }
+  c.tracing.instrument :rack, quantize: { query: { show: ['category_id'] } }
 
   # Show all values for all query string parameters
   # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id=1&sort_by=asc
-  c.use :rack, quantize: { query: { show: :all } }
+  c.tracing.instrument :rack, quantize: { query: { show: :all } }
 
   # Totally exclude any query string parameter matching 'sort_by' exactly
   # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id
-  c.use :rack, quantize: { query: { exclude: ['sort_by'] } }
+  c.tracing.instrument :rack, quantize: { query: { exclude: ['sort_by'] } }
 
   # Remove the query string entirely
   # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path
-  c.use :rack, quantize: { query: { exclude: :all } }
+  c.tracing.instrument :rack, quantize: { query: { exclude: :all } }
 
   # Show URL fragments
   # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id&sort_by#featured
-  c.use :rack, quantize: { fragment: :show }
+  c.tracing.instrument :rack, quantize: { fragment: :show }
 end
 ```
 
@@ -1498,7 +1475,7 @@ To enable the Rails instrumentation, create an initializer file in your `config/
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :rails, options
+  c.tracing.instrument :rails, options
 end
 ```
 
@@ -1507,23 +1484,20 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `cache_service` | Cache service name used when tracing cache activity | `'<app_name>-cache'` |
-| `controller_service` | Service name used when tracing a Rails action controller | `'<app_name>'` |
 | `database_service` | Database service name used when tracing database activity | `'<app_name>-<adapter_name>'` |
 | `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `true` |
 | `exception_controller` | Class or Module which identifies a custom exception controller class. Tracer provides improved error behavior when it can identify custom exception controllers. By default, without this option, it 'guesses' what a custom exception controller looks like. Providing this option aids this identification. | `nil` |
-| `job_service` | Service name used when tracing ActiveJob activity. | `<app_name>-active_job` |
 | `middleware` | Add the trace middleware to the Rails application. Set to `false` if you don't want the middleware to load. | `true` |
 | `middleware_names` | Enables any short-circuited middleware requests to display the middleware name as a resource for the trace. | `false` |
 | `service_name` | Service name used when tracing application requests (on the `rack` level) | `'<app_name>'` (inferred from your Rails application namespace) |
 | `template_base_path` | Used when the template name is parsed. If you don't store your templates in the `views/` folder, you may need to change this value | `'views/'` |
-| `log_injection` | Automatically enables injection [Trace Correlation](#trace-correlation) information, such as `dd.trace_id`, into Rails logs. Supports the default logger (`ActiveSupport::TaggedLogging`) and `Lograge`. Details on the format of Trace Correlation information can be found in the [Trace Correlation](#trace-correlation) section.  | `false` |
 
 **Supported versions**
 
 | MRI Versions  | JRuby Versions | Rails Versions |
 | ------------- | -------------- | -------------- |
-|  2.1          |                |  3.0 - 4.2     |
-|  2.2 - 2.3    |                |  3.0 - 5.2     |
+|  2.1          |                |  3.2 - 4.2     |
+|  2.2 - 2.3    |                |  3.2 - 5.2     |
 |  2.4          |                |  4.2.8 - 5.2   |
 |  2.5          |                |  4.2.8 - 6.1   |
 |  2.6 - 2.7    |  9.2           |  5.0 - 6.1     |
@@ -1541,7 +1515,7 @@ require 'rake'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :rake, options
+  c.tracing.instrument :rake, options
 end
 
 task :my_task do
@@ -1557,7 +1531,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | --- | ----------- | ------- |
 | `enabled` | Defines whether Rake tasks should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
 | `quantize` | Hash containing options for quantization of task arguments. See below for more details and examples. | `{}` |
-| `service_name` | Service name used for `rake` instrumentation | `'rake'` |
 
 **Configuring task quantization behavior**
 
@@ -1569,27 +1542,27 @@ Datadog.configure do |c|
   # Default behavior: all arguments are quantized.
   # `rake.invoke.args` tag  --> ['?']
   # `rake.execute.args` tag --> { one: '?', two: '?', three: '?' }
-  c.use :rake
+  c.tracing.instrument :rake
 
   # Show values for any argument matching :two exactly
   # `rake.invoke.args` tag  --> ['?']
   # `rake.execute.args` tag --> { one: '?', two: 'bar', three: '?' }
-  c.use :rake, quantize: { args: { show: [:two] } }
+  c.tracing.instrument :rake, quantize: { args: { show: [:two] } }
 
   # Show all values for all arguments.
   # `rake.invoke.args` tag  --> ['foo', 'bar', 'baz']
   # `rake.execute.args` tag --> { one: 'foo', two: 'bar', three: 'baz' }
-  c.use :rake, quantize: { args: { show: :all } }
+  c.tracing.instrument :rake, quantize: { args: { show: :all } }
 
   # Totally exclude any argument matching :three exactly
   # `rake.invoke.args` tag  --> ['?']
   # `rake.execute.args` tag --> { one: '?', two: '?' }
-  c.use :rake, quantize: { args: { exclude: [:three] } }
+  c.tracing.instrument :rake, quantize: { args: { exclude: [:three] } }
 
   # Remove the arguments entirely
   # `rake.invoke.args` tag  --> ['?']
   # `rake.execute.args` tag --> {}
-  c.use :rake, quantize: { args: { exclude: :all } }
+  c.tracing.instrument :rake, quantize: { args: { exclude: :all } }
 end
 ```
 
@@ -1602,7 +1575,7 @@ require 'redis'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :redis, options
+  c.tracing.instrument :redis, options
 end
 
 # Perform Redis commands
@@ -1624,14 +1597,14 @@ require 'redis'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :redis # Enabling integration instrumentation is still required
+  c.tracing.instrument :redis # Enabling integration instrumentation is still required
 end
 
 customer_cache = Redis.new
 invoice_cache = Redis.new
 
-Datadog.configure(customer_cache, service_name: 'customer-cache')
-Datadog.configure(invoice_cache, service_name: 'invoice-cache')
+Datadog.configure_onto(customer_cache, service_name: 'customer-cache')
+Datadog.configure_onto(invoice_cache, service_name: 'invoice-cache')
 
 # Traced call will belong to `customer-cache` service
 customer_cache.get(...)
@@ -1651,23 +1624,23 @@ You can configure trace settings per connection by using the `describes` option:
 
 Datadog.configure do |c|
   # The default configuration for any redis client
-  c.use :redis, service_name: 'redis-default'
+  c.tracing.instrument :redis, service_name: 'redis-default'
 
   # The configuration matching a given unix socket.
-  c.use :redis, describes: { url: 'unix://path/to/file' }, service_name: 'redis-unix'
+  c.tracing.instrument :redis, describes: { url: 'unix://path/to/file' }, service_name: 'redis-unix'
 
   # For network connections, only these fields are considered during matching:
   # scheme, host, port, db
   # Other fields are ignored.
 
   # Network connection string
-  c.use :redis, describes: 'redis://127.0.0.1:6379/0', service_name: 'redis-connection-string'
-  c.use :redis, describes: { url: 'redis://127.0.0.1:6379/1' }, service_name: 'redis-connection-url'
+  c.tracing.instrument :redis, describes: 'redis://127.0.0.1:6379/0', service_name: 'redis-connection-string'
+  c.tracing.instrument :redis, describes: { url: 'redis://127.0.0.1:6379/1' }, service_name: 'redis-connection-url'
   # Network client hash
-  c.use :redis, describes: { host: 'my-host.com', port: 6379, db: 1, scheme: 'redis' }, service_name: 'redis-connection-hash'
+  c.tracing.instrument :redis, describes: { host: 'my-host.com', port: 6379, db: 1, scheme: 'redis' }, service_name: 'redis-connection-hash'
   # Only a subset of the connection hash
-  c.use :redis, describes: { host: ENV['APP_CACHE_HOST'], port: ENV['APP_CACHE_PORT'] }, service_name: 'redis-cache'
-  c.use :redis, describes: { host: ENV['SIDEKIQ_CACHE_HOST'] }, service_name: 'redis-sidekiq'
+  c.tracing.instrument :redis, describes: { host: ENV['APP_CACHE_HOST'], port: ENV['APP_CACHE_PORT'] }, service_name: 'redis-cache'
+  c.tracing.instrument :redis, describes: { host: ENV['SIDEKIQ_CACHE_HOST'] }, service_name: 'redis-sidekiq'
 end
 ```
 
@@ -1684,7 +1657,7 @@ require 'resque'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :resque, **options
+  c.tracing.instrument :resque, **options
 end
 ```
 
@@ -1692,9 +1665,7 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `service_name` | Service name used for `resque` instrumentation | `'resque'` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
-| `workers` | **[DEPRECATED]** Limits instrumented worker classes to only the ones specified in an array (e.g. `[MyJob]`). If not provided, instruments all workers. | `nil` |
 
 ### Rest Client
 
@@ -1705,7 +1676,7 @@ require 'rest_client'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :rest_client, options
+  c.tracing.instrument :rest_client, options
 end
 ```
 
@@ -1728,7 +1699,7 @@ require 'ddtrace'
 
 # Configure default RSpec integration
 Datadog.configure do |c|
-  c.use :rspec, options
+  c.ci.instrument :rspec, options
 end
 ```
 
@@ -1758,7 +1729,7 @@ database.create_table :articles do
 end
 
 Datadog.configure do |c|
-  c.use :sequel, options
+  c.tracing.instrument :sequel, options
 end
 
 # Perform a query
@@ -1781,8 +1752,8 @@ sqlite_database = Sequel.sqlite
 postgres_database = Sequel.connect('postgres://user:password@host:port/database_name')
 
 # Configure each database with different service names
-Datadog.configure(sqlite_database, service_name: 'my-sqlite-db')
-Datadog.configure(postgres_database, service_name: 'my-postgres-db')
+Datadog.configure_onto(sqlite_database, service_name: 'my-sqlite-db')
+Datadog.configure_onto(postgres_database, service_name: 'my-postgres-db')
 ```
 
 ### Shoryuken
@@ -1795,7 +1766,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :shoryuken, options
+  c.tracing.instrument :shoryuken, options
 end
 ```
 
@@ -1803,7 +1774,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `service_name` | Service name used for `shoryuken` instrumentation | `'shoryuken'` |
 | `tag_body` | Tag spans with the SQS message body `true` or `false` | `false` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
 
@@ -1817,7 +1787,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :sidekiq, options
+  c.tracing.instrument :sidekiq, options
 end
 ```
 
@@ -1825,8 +1795,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 
 | Key | Description | Default |
 | --- | ----------- | ------- |
-| `client_service_name` | Service name used for client-side `sidekiq` instrumentation | `'sidekiq-client'` |
-| `service_name` | Service name used for server-side `sidekiq` instrumentation | `'sidekiq'` |
 | `tag_args` | Enable tagging of job arguments. `true` for on, `false` for off. | `false` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
 
@@ -1843,7 +1811,7 @@ require 'sinatra'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :sinatra, options
+  c.tracing.instrument :sinatra, options
 end
 
 get '/' do
@@ -1858,11 +1826,11 @@ require 'sinatra/base'
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :sinatra, options
+  c.tracing.instrument :sinatra, options
 end
 
 class NestedApp < Sinatra::Base
-  register Datadog::Contrib::Sinatra::Tracer
+  register Datadog::Tracing::Contrib::Sinatra::Tracer
 
   get '/nested' do
     'Hello from nested app!'
@@ -1870,7 +1838,7 @@ class NestedApp < Sinatra::Base
 end
 
 class App < Sinatra::Base
-  register Datadog::Contrib::Sinatra::Tracer
+  register Datadog::Tracing::Contrib::Sinatra::Tracer
 
   use NestedApp
 
@@ -1880,7 +1848,7 @@ class App < Sinatra::Base
 end
 ```
 
-Ensure you register `Datadog::Contrib::Sinatra::Tracer` as a middleware before you mount your nested applications.
+Ensure you register `Datadog::Tracing::Contrib::Sinatra::Tracer` as a middleware before you mount your nested applications.
 
 #### Instrumentation options
 
@@ -1891,7 +1859,6 @@ Ensure you register `Datadog::Contrib::Sinatra::Tracer` as a middleware before y
 | `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `true` |
 | `headers` | Hash of HTTP request or response headers to add as tags to the `sinatra.request`. Accepts `request` and `response` keys with Array values e.g. `['Last-Modified']`. Adds `http.request.headers.*` and `http.response.headers.*` tags respectively. | `{ response: ['Content-Type', 'X-Request-ID'] }` |
 | `resource_script_names` | Prepend resource names with script name | `false` |
-| `service_name` | Service name used for `sinatra` instrumentation | `'sinatra'` |
 
 ### Sneakers
 
@@ -1903,7 +1870,7 @@ You can enable it through `Datadog.configure`:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :sneakers, options
+  c.tracing.instrument :sneakers, options
 end
 ```
 
@@ -1912,7 +1879,6 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `enabled` | Defines whether Sneakers should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
-| `service_name` | Service name used for `sneakers` instrumentation | `'sneakers'` |
 | `tag_body` | Enable tagging of job message. `true` for on, `false` for off. | `false` |
 | `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
 
@@ -1924,63 +1890,48 @@ The `sucker_punch` integration traces all scheduled jobs:
 require 'ddtrace'
 
 Datadog.configure do |c|
-  c.use :sucker_punch, options
+  c.tracing.instrument :sucker_punch
 end
 
 # Execution of this job is traced
 LogJob.perform_async('login')
 ```
 
-Where `options` is an optional `Hash` that accepts the following parameters:
-
-| Key | Description | Default |
-| --- | ----------- | ------- |
-| `service_name` | Service name used for `sucker_punch` instrumentation | `'sucker_punch'` |
-
 ## Advanced configuration
 
-### Tracer settings
+### Environment variables
 
-To change the default behavior of the Datadog tracer, you can provide custom options inside the `Datadog.configure` block as in:
+- `DD_AGENT_HOST`: Hostname of agent to where traces will be sent. See [Tracer settings](#tracer-settings) for more details.
+- `DD_ENV`: Your application environment. See [Environment and tags](#environment-and-tags) for more details.
+- `DD_LOGS_INJECTION`: Injects [Trace Correlation](#trace-correlation) information into Rails logs, if present. Supports the default logger (`ActiveSupport::TaggedLogging`), `lograge`, and `semantic_logger`. Valid values are: `true` (default) or `false`. e.g. `DD_LOGS_INJECTION=false`.
+- `DD_PROPAGATION_STYLE_EXTRACT`: Distributed tracing header formats to extract. See [Distributed Tracing](#distributed-tracing) for more details.
+- `DD_PROPAGATION_STYLE_INJECT`: Distributed tracing header formats to inject. See [Distributed Tracing](#distributed-tracing) for more details.
+- `DD_SERVICE`: Your application's default service name. See [Environment and tags](#environment-and-tags) for more details.
+- `DD_TAGS`: Custom tags for telemetry produced by your application. See [Environment and tags](#environment-and-tags) for more details.
+- `DD_TRACE_<INTEGRATION>_ENABLED`: Enables or disables an **activated** integration. Defaults to `true`.. e.g. `DD_TRACE_RAILS_ENABLED=false`. This option has no effects on integrations that have not been explicitly activated (e.g. `Datadog.configure { |c| c.tracing.instrument :integration }`).on code. This environment variable can only be used to disable an integration.
+- `DD_TRACE_AGENT_PORT`: Port to where traces will be sent. See [Tracer settings](#tracer-settings) for more details.
+- `DD_TRACE_AGENT_URL`: Sets the URL endpoint where traces are sent. Has priority over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. e.g. `DD_TRACE_AGENT_URL=http://localhost:8126`.
+- `DD_TRACE_ANALYTICS_ENABLED`: Enables or disables trace analytics. See [Sampling](#sampling) for more details.
+- `DD_TRACE_RATE_LIMIT`: Sets a rate limit for sampling. See [Sampling](#sampling) for more details.
+- `DD_TRACE_REPORT_HOSTNAME`: Enables ot disables hostname tags on traces.
+- `DD_TRACE_SAMPLE_RATE`: Sets the trace sampling rate between `0.0` (0%) and `1.0` (100%, recommended). `1.0` or Tracing without Limits™, allows you to send all of your traffic and retention can be [configured within the Datadog app](https://docs.datadoghq.com/tracing/trace_retention_and_ingestion/). When this configuration is not set, the Datadog agent will keep an intelligent assortment of diverse traces.
+- `DD_TRACE_TEST_MODE_ENABLED`: Enables or disables test mode, for use of tracing in test suites.
+- `DD_VERSION`: Your application version. See [Environment and tags](#environment-and-tags) for more details.
+
+### Global settings
 
 ```ruby
 # config/initializers/datadog-tracer.rb
-
 Datadog.configure do |c|
-  c.tracer.enabled = true
-  c.tracer.hostname = 'my-agent'
-  c.tracer.port = 8126
-
-  # Ensure all traces are ingested by Datadog
-  c.sampling.default_rate = 1.0 # Recommended
-  c.sampling.rate_limit = 200
-  # or provide a custom implementation (overrides c.sampling settings)
-  c.tracer.sampler = Datadog::AllSampler.new
-
-  # Breaks down very large traces into smaller batches
-  c.tracer.partial_flush.enabled = false
-
-  # You can specify your own tracer
-  c.tracer.instance = Datadog::Tracer.new
-
-  # To enable debug mode
-  c.diagnostics.debug = true
+  c.agent.host = 'custom-agent-host'
+  c.agent.port = 8126
 end
 ```
 
 Available options are:
 
- - `enabled`: defines if the `tracer` is enabled or not. If set to `false` instrumentation will still run, but no spans are sent to the trace agent. Can be configured through the `DD_TRACE_ENABLED` environment variable. Defaults to `true`.
- - `hostname`: set the hostname of the trace agent.
- - `instance`: set to a custom `Datadog::Tracer` instance. If provided, other trace settings are ignored (you must configure it manually.)
- - `partial_flush.enabled`: set to `true` to enable partial trace flushing (for long running traces.) Disabled by default. *Experimental.*
- - `port`: set the port the trace agent is listening on.
- - `sampling.default_rate`: default tracer sampling rate, between `0.0` (0%) and `1.0` (100%, recommended). `1.0` or Tracing without Limits™, allows you to send all of your traffic and retention can be [configured within the Datadog app](https://docs.datadoghq.com/tracing/trace_retention_and_ingestion/). When this configuration is not set, the Datadog agent will keep an intelligent assortment of diverse traces.
- - `sampling.rate_limit`: maximum number of traces per second to sample. Defaults to 100 per second.
- - `sampler`: set to a custom `Datadog::Sampler` instance. If provided, the tracer will use this sampler to determine sampling behavior.
- - `diagnostics.startup_logs.enabled`: Startup configuration and diagnostic log. Defaults to `true`. Can be configured through the `DD_TRACE_STARTUP_LOGS` environment variable.
- - `diagnostics.debug`: set to true to enable debug logging. Can be configured through the `DD_TRACE_DEBUG` environment variable. Defaults to `false`.
- - `time_now_provider`: when testing, it might be helpful to use a different time provider. For Timecop, for example, `->{ Time.now_without_mock_time }` allows the tracer to use the real wall time. Span duration calculation will still use the system monotonic clock when available, thus not being affected by this setting. Defaults to `->{ Time.now }`.
+- `agent.host`: set the hostname of the trace agent. Defaults to `127.0.0.1`.
+- `agent.port`: set the APM TCP port the Datadog Agent listening on. Defaults to `8126`.
 
 #### Custom logging
 
@@ -1993,14 +1944,14 @@ Additionally, it is possible to override the default logger and replace it by a
 ```ruby
 f = File.new("my-custom.log", "w+") # Log messages should go there
 Datadog.configure do |c|
-  c.logger = Logger.new(f) # Overriding the default logger
+  c.logger.instance = Logger.new(f) # Overriding the default logger
   c.logger.level = ::Logger::INFO
 end
 
 Datadog.logger.info { "this is typically called by tracing code" }
 ```
 
-### Environment and tags
+#### Environment and tags
 
 By default, the trace agent (not this library, but the program running in the background collecting data from various clients) uses the tags set in the agent config file, see our [environments tutorial](https://app.datadoghq.com/apm/docs/tutorials/environments) for details.
 
@@ -2028,14 +1979,59 @@ This enables you to set this value on a per application basis, so you can have f
 
 Tags can also be set directly on individual spans, which will supersede any conflicting tags defined at the application level.
 
-### Environment variables
+#### Debugging and diagnostics
 
-Other Environment Variables:
+You can activate debugging features by using `Datadog.configure`:
 
-- `DD_TRACE_AGENT_URL`: Sets the URL endpoint where traces are sent. Has priority over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. e.g. `DD_TRACE_AGENT_URL=http://localhost:8126`.
-- `DD_TRACE_<INTEGRATION>_ENABLED`: Enables or disables an **activated** integration. Defaults to `true`.. e.g. `DD_TRACE_RAILS_ENABLED=false`. This option has no effects on integrations that have not been explicitly activated (e.g. `Datadog.configure{ |c| c.use :integration }`).on code. This environment variable can only be used to disable an integration.
-- `DD_TRACE_SAMPLE_RATE`: Sets the trace sampling rate between `0.0` (0%) and `1.0` (100%, recommended). `1.0` or Tracing without Limits™, allows you to send all of your traffic and retention can be [configured within the Datadog app](https://docs.datadoghq.com/tracing/trace_retention_and_ingestion/). When this configuration is not set, the Datadog agent will keep an intelligent assortment of diverse traces.
-- `DD_LOGS_INJECTION`: Automatically enables injection [Trace Correlation](#trace-correlation) information, such as `dd.trace_id`, into Rails logs. Supports the default logger (`ActiveSupport::TaggedLogging`) and `Lograge`. Details on the format of Trace Correlation information can be found in the [Trace Correlation](#trace-correlation) section. Valid values are: `true` or `false`(default). e.g. `DD_LOGS_INJECTION=true`.
+```ruby
+# config/initializers/datadog-tracer.rb
+
+# Global settings are set here:
+Datadog.configure do |c|
+  # To enable debug mode
+  c.diagnostics.debug = true
+end
+```
+
+Available options are:
+
+ - `diagnostics.debug`: set to true to enable debug logging. Can be configured through the `DD_TRACE_DEBUG` environment variable. Defaults to `false`.
+ - `diagnostics.startup_logs.enabled`: Startup configuration and diagnostic log. Defaults to `true`. Can be configured through the `DD_TRACE_STARTUP_LOGS` environment variable.
+ - `time_now_provider`: when testing, it might be helpful to use a different time provider. For Timecop, for example, `->{ Time.now_without_mock_time }` allows the tracer to use the real wall time. Span duration calculation will still use the system monotonic clock when available, thus not being affected by this setting. Defaults to `->{ Time.now }`.
+
+### Tracer settings
+
+To change the default behavior of the Datadog tracer, you can provide custom options inside the `Datadog.configure` block as in:
+
+```ruby
+# config/initializers/datadog-tracer.rb
+# Tracer settings are set here:
+Datadog.configure do |c|
+  c.tracing.enabled = true
+
+  # Ensure all traces are ingested by Datadog
+  c.tracing.sampling.default_rate = 1.0 # Recommended
+  c.tracing.sampling.rate_limit = 200
+  # or provide a custom implementation (overrides c.tracing.sampling settings)
+  c.tracing.sampler = Datadog::Tracing::Sampling::AllSampler.new
+
+  # Breaks down very large traces into smaller batches
+  c.tracing.partial_flush.enabled = false
+
+  # You can specify your own tracer
+  c.tracing.instance = Datadog::Tracing::Tracer.new
+end
+```
+
+Available options are:
+
+ - `tracing.log_injection`: Injects [Trace Correlation](#trace-correlation) information into Rails logs, if present. Defaults to `true`.
+ - `sampling.default_rate`: default tracer sampling rate, between `0.0` (0%) and `1.0` (100%, recommended). `1.0` or Tracing without Limits™, allows you to send all of your traffic and retention can be [configured within the Datadog app](https://docs.datadoghq.com/tracing/trace_retention_and_ingestion/). When this configuration is not set, the Datadog agent will keep an intelligent assortment of diverse traces.
+ - `sampling.rate_limit`: maximum number of traces per second to sample. Defaults to 100 per second.
+ - `tracing.enabled`: defines if the `tracer` is enabled or not. If set to `false` instrumentation will still run, but no spans are sent to the trace agent. Can be configured through the `DD_TRACE_ENABLED` environment variable. Defaults to `true`.
+ - `tracing.instance`: set to a custom `Datadog::Tracer` instance. If provided, other trace settings are ignored (you must configure it manually.)
+ - `tracing.partial_flush.enabled`: set to `true` to enable partial trace flushing (for long running traces.) Disabled by default. *Experimental.*
+ - `tracing.sampler`: set to a custom `Datadog::Sampler` instance. If provided, the tracer will use this sampler to determine sampling behavior.
 
 ### Sampling
 
@@ -2043,7 +2039,7 @@ Datadog's Tracing without Limits™ allows you to send all of your traffic and [
 
 We recommend setting the environment variable `DD_TRACE_SAMPLE_RATE=1.0` in all new applications using `ddtrace`.
 
-App Analytics, previously configured with the `analytics_enabled` setting, is deprecated in favor of Tracing without Limits™. Documentation for this [deprecated configuration is still available](https://docs.datadoghq.com/tracing/legacy_app_analytics/).
+App Analytics, previously configured with the `tracing.analytics.enabled` setting, is deprecated in favor of Tracing without Limits™. Documentation for this [deprecated configuration is still available](https://docs.datadoghq.com/tracing/legacy_app_analytics/).
 
 #### Application-side sampling
 
@@ -2051,14 +2047,14 @@ While the trace agent can sample traces to reduce bandwidth usage, application-s
 
 This will **reduce visibility and is not recommended**. See [DD_TRACE_SAMPLE_RATE](#environment-variables) for the recommended sampling approach.
 
-`Datadog::RateSampler` samples a ratio of the traces. For example:
+`Datadog::Tracing::Sampling::RateSampler` samples a ratio of the traces. For example:
 
 ```ruby
 # Sample rate is between 0 (nothing sampled) to 1 (everything sampled).
-sampler = Datadog::RateSampler.new(0.5) # sample 50% of the traces
+sampler = Datadog::Tracing::Sampling::RateSampler.new(0.5) # sample 50% of the traces
 
 Datadog.configure do |c|
-  c.tracer.sampler = sampler
+  c.tracing.sampler = sampler
 end
 ```
 
@@ -2068,29 +2064,43 @@ Priority sampling decides whether to keep a trace by using a priority attribute
 
 The sampler can set the priority to the following values:
 
- - `Datadog::Ext::Priority::AUTO_REJECT`: the sampler automatically decided to reject the trace.
- - `Datadog::Ext::Priority::AUTO_KEEP`: the sampler automatically decided to keep the trace.
+ - `Datadog::Tracing::Sampling::Ext::Priority::AUTO_REJECT`: the sampler automatically decided to reject the trace.
+ - `Datadog::Tracing::Sampling::Ext::Priority::AUTO_KEEP`: the sampler automatically decided to keep the trace.
 
 Priority sampling is enabled by default. Enabling it ensures that your sampled distributed traces will be complete. Once enabled, the sampler will automatically assign a priority of 0 or 1 to traces, depending on their service and volume.
 
-You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the `context#sampling_priority` to:
+You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the `TraceOperation#sampling_priority` to:
 
- - `Datadog::Ext::Priority::USER_REJECT`: the user asked to reject the trace.
- - `Datadog::Ext::Priority::USER_KEEP`: the user asked to keep the trace.
+ - `Datadog::Tracing::Sampling::Ext::Priority::USER_REJECT`: the user asked to reject the trace.
+ - `Datadog::Tracing::Sampling::Ext::Priority::USER_KEEP`: the user asked to keep the trace.
 
 When not using [distributed tracing](#distributed-tracing), you may change the priority at any time, as long as the trace incomplete. But it has to be done before any context propagation (fork, RPC calls) to be useful in a distributed context. Changing the priority after the context has been propagated causes different parts of a distributed trace to use different priorities. Some parts might be kept, some parts might be rejected, and this can cause the trace to be partially stored and remain incomplete.
 
-If you change the priority, we recommend you do it as soon as possible - when the root span has just been created.
+For this reason, if you change the priority, we recommend you do it as early as possible.
+
+To change the sampling priority, you can use the following methods:
+
+```ruby
+# Rejects the active trace
+Datadog::Tracing.reject!
+
+# Keeps the active trace
+Datadog::Tracing.keep!
+```
+
+It's safe to use `Datadog::Tracing.reject!` and `Datadog::Tracing.keep!` when no trace is active.
+
+You can also reject a specific trace instance:
 
 ```ruby
 # First, grab the active span
-span = Datadog.tracer.active_span
+trace = Datadog::Tracing.active_trace
 
-# Indicate to reject the trace
-span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT
+# Rejects the trace
+trace.reject!
 
-# Indicate to keep the trace
-span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP
+# Keeps the trace
+trace.keep!
 ```
 
 ### Distributed Tracing
@@ -2195,6 +2205,33 @@ Service C:
   Priority:  1
 ```
 
+**Distributed header formats**
+
+Tracing supports the following distributed trace formats:
+
+ - `Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG` (Default)
+ - `Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3`
+ - `Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER`
+
+You can enable/disable the use of these formats via `Datadog.configure`:
+
+```ruby
+Datadog.configure do |c|
+  # List of header formats that should be extracted
+  c.tracing.distributed_tracing.propagation_extract_style = [
+    Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG,
+    Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3,
+    Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER
+
+  ]
+
+  # List of header formats that should be injected
+  c.tracing.distributed_tracing.propagation_inject_style = [
+    Datadog::Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG
+  ]
+end
+```
+
 **Activating distributed tracing for integrations**
 
 Many integrations included in `ddtrace` support distributed tracing. Distributed tracing is enabled by default in Agent v7 and most versions of Agent v6. If needed, you can activate distributed tracing with configuration settings.
@@ -2218,24 +2255,24 @@ For more details on how to activate distributed tracing for integrations, see th
 
 **Using the HTTP propagator**
 
-To make the process of propagating this metadata easier, you can use the `Datadog::HTTPPropagator` module.
+To make the process of propagating this metadata easier, you can use the `Datadog::Tracing::Propagation::HTTP` module.
 
 On the client:
 
 ```ruby
-Datadog.tracer.trace('web.call') do |span|
-  # Inject span context into headers (`env` must be a Hash)
-  Datadog::HTTPPropagator.inject!(span.context, env)
+Datadog::Tracing.trace('web.call') do |span, trace|
+  # Inject trace headers into request headers (`env` must be a Hash)
+  Datadog::Tracing::Propagation::HTTP.inject!(trace.to_digest, env)
 end
 ```
 
 On the server:
 
 ```ruby
-Datadog.tracer.trace('web.work') do |span|
-  # Build a context from headers (`env` must be a Hash)
-  context = HTTPPropagator.extract(request.env)
-  Datadog.tracer.provider.context = context if context.trace_id
+trace_digest = Datadog::Tracing::Propagation::HTTP.extract(request.env)
+
+Datadog::Tracing.trace('web.work', continue_from: trace_digest) do |span|
+  # Do web work...
 end
 ```
 
@@ -2261,147 +2298,87 @@ Then you must enable the request queuing feature, by setting `request_queuing: t
 
 ### Processing Pipeline
 
-Some applications might require that traces be altered or filtered out before they are sent upstream. The processing pipeline allows users to create *processors* to define such behavior.
-
-Processors can be any object that responds to `#call` accepting `trace` as an argument (which is an `Array` of `Datadog::Span`s.)
-
-For example:
-
-```ruby
-lambda_processor = ->(trace) do
-  # Processing logic...
-  trace
-end
-
-class MyCustomProcessor
-  def call(trace)
-    # Processing logic...
-    trace
-  end
-end
-custom_processor = MyFancyProcessor.new
-```
-
-`#call` blocks of processors *must* return the `trace` object; this return value will be passed to the next processor in the pipeline.
-
-These processors must then be added to the pipeline via `Datadog::Pipeline.before_flush`:
-
-```ruby
-Datadog::Pipeline.before_flush(lambda_processor, custom_processor)
-```
-
-You can also define processors using the short-hand block syntax for `Datadog::Pipeline.before_flush`:
-
-```ruby
-Datadog::Pipeline.before_flush do |trace|
-  trace.delete_if { |span| span.name =~ /forbidden/ }
-end
-```
+Some applications might require that traces be altered or filtered out before they are sent to Datadog. The processing pipeline allows you to create *processors* to define such behavior.
 
 #### Filtering
 
-You can use the `Datadog::Pipeline::SpanFilter` processor to remove spans, when the block evaluates as truthy:
+You can use the `Datadog::Tracing::Pipeline::SpanFilter` processor to remove spans, when the block evaluates as truthy:
 
 ```ruby
-Datadog::Pipeline.before_flush(
+Datadog::Tracing.before_flush(
   # Remove spans that match a particular resource
-  Datadog::Pipeline::SpanFilter.new { |span| span.resource =~ /PingController/ },
+  Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.resource =~ /PingController/ },
   # Remove spans that are trafficked to localhost
-  Datadog::Pipeline::SpanFilter.new { |span| span.get_tag('host') == 'localhost' }
+  Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.get_tag('host') == 'localhost' }
 )
 ```
 
 #### Processing
 
-You can use the `Datadog::Pipeline::SpanProcessor` processor to modify spans:
+You can use the `Datadog::Tracing::Pipeline::SpanProcessor` processor to modify spans:
 
 ```ruby
-Datadog::Pipeline.before_flush(
+Datadog::Tracing.before_flush(
   # Strip matching text from the resource field
-  Datadog::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
+  Datadog::Tracing::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
 )
 ```
 
-### Trace correlation
-
-In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross-referencing.
+#### Custom processor
 
-#### For logging in Rails applications
-
-##### Automatic
+Processors can be any object that responds to `#call` accepting `trace` as an argument (which is an `Array` of `Datadog::Span`s.)
 
-For Rails applications using the default logger (`ActiveSupport::TaggedLogging`), `semantic_logger`, or `lograge`, you can automatically enable trace correlation injection by setting the `rails` instrumentation configuration option `log_injection` to `true` or by setting environment variable `DD_LOGS_INJECTION=true`:
+For example, using the short-hand block syntax:
 
 ```ruby
-# config/initializers/datadog.rb
-require 'ddtrace'
-
-Datadog.configure do |c|
-  c.use :rails, log_injection: true
+Datadog::Tracing.before_flush do |trace|
+   # Processing logic...
+   trace
 end
 ```
 
-##### Manual (Lograge)
-
-After [setting up Lograge in a Rails application](https://docs.datadoghq.com/logs/log_collection/ruby/), manually modify the `custom_options` block in your environment configuration file (e.g. `config/environments/production.rb`) to add the trace IDs.
+For a custom processor class:
 
 ```ruby
-config.lograge.custom_options = lambda do |event|
-  # Retrieves trace information for current thread
-  correlation = Datadog.tracer.active_correlation
-
-  {
-    # Adds IDs as tags to log output
-    :dd => {
-      # To preserve precision during JSON serialization, use strings for large numbers
-      :trace_id => correlation.trace_id.to_s,
-      :span_id => correlation.span_id.to_s,
-      :env => correlation.env.to_s,
-      :service => correlation.service.to_s,
-      :version => correlation.version.to_s
-    },
-    :ddsource => ["ruby"],
-    :params => event.payload[:params].reject { |k| %w(controller action).include? k }
-  }
+class MyCustomProcessor
+  def call(trace)
+    # Processing logic...
+    trace
+  end
 end
+
+Datadog::Tracing.before_flush(MyCustomProcessor.new)
 ```
 
-##### Manual (ActiveSupport::TaggedLogging)
+In both cases, the processor method *must* return the `trace` object; this return value will be passed to the next processor in the pipeline.
 
-Rails applications which are configured with the default `ActiveSupport::TaggedLogging` logger can append correlation IDs as tags to log output. To enable Trace Correlation with `ActiveSupport::TaggedLogging`, in your Rails environment configuration file, add the following:
+### Trace correlation
 
-```ruby
-Rails.application.configure do
-  config.log_tags = [proc { Datadog.tracer.active_correlation.to_s }]
-end
+In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross-referencing.
 
-# Given:
-# DD_ENV = 'production' (The name of the environment your application is running in.)
-# DD_SERVICE = 'billing-api' (Default service name of your application.)
-# DD_VERSION = '2.5.17' (The version of your application.)
+#### For logging in Rails applications
 
-# Web requests will produce:
-# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Started GET "/articles" for 172.22.0.1 at 2019-01-16 18:50:57 +0000
-# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Processing by ArticlesController#index as */*
-# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206]   Article Load (0.5ms)  SELECT "articles".* FROM "articles"
-# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Completed 200 OK in 7ms (Views: 5.5ms | ActiveRecord: 0.5ms)
-```
+##### Automatic
+
+For Rails applications using the default logger (`ActiveSupport::TaggedLogging`), `lograge` or `semantic_logger`, trace correlation injection is enabled by default.
+
+It can be disabled by setting the environment variable `DD_LOGS_INJECTION=false`.
 
 #### For logging in Ruby applications
 
-To add correlation IDs to your logger, add a log formatter which retrieves the correlation IDs with `Datadog.tracer.active_correlation`, then add them to the message.
+To add correlation IDs to your logger, add a log formatter which retrieves the correlation IDs with `Datadog::Tracing.correlation`, then add them to the message.
 
 To properly correlate with Datadog logging, be sure the following is present in the log message, in order as they appear:
 
- - `dd.env=<ENV>`: Where `<ENV>` is equal to `Datadog.tracer.active_correlation.env`. Omit if no environment is configured.
- - `dd.service=<SERVICE>`: Where `<SERVICE>` is equal to `Datadog.tracer.active_correlation.service`. Omit if no default service name is configured.
- - `dd.version=<VERSION>`: Where `<VERSION>` is equal to `Datadog.tracer.active_correlation.version`. Omit if no application version is configured.
- - `dd.trace_id=<TRACE_ID>`: Where `<TRACE_ID>` is equal to `Datadog.tracer.active_correlation.trace_id` or `0` if no trace is active during logging.
- - `dd.span_id=<SPAN_ID>`: Where `<SPAN_ID>` is equal to `Datadog.tracer.active_correlation.span_id` or `0` if no trace is active during logging.
+ - `dd.env=<ENV>`: Where `<ENV>` is equal to `Datadog::Tracing.correlation.env`. Omit if no environment is configured.
+ - `dd.service=<SERVICE>`: Where `<SERVICE>` is equal to `Datadog::Tracing.correlation.service`. Omit if no default service name is configured.
+ - `dd.version=<VERSION>`: Where `<VERSION>` is equal to `Datadog::Tracing.correlation.version`. Omit if no application version is configured.
+ - `dd.trace_id=<TRACE_ID>`: Where `<TRACE_ID>` is equal to `Datadog::Tracing.correlation.trace_id` or `0` if no trace is active during logging.
+ - `dd.span_id=<SPAN_ID>`: Where `<SPAN_ID>` is equal to `Datadog::Tracing.correlation.span_id` or `0` if no trace is active during logging.
 
-By default, `Datadog::Correlation::Identifier#to_s` will return `dd.env=<ENV> dd.service=<SERVICE> dd.version=<VERSION> dd.trace_id=<TRACE_ID> dd.span_id=<SPAN_ID>`.
+`Datadog::Tracing.log_correlation` will return `dd.env=<ENV> dd.service=<SERVICE> dd.version=<VERSION> dd.trace_id=<TRACE_ID> dd.span_id=<SPAN_ID>`.
 
-If a trace is not active and the application environment & version is not configured, it will return `dd.trace_id=0 dd.span_id=0 dd.env= dd.version=`.
+If a trace is not active and the application environment & version is not configured, it will return `dd.env= dd.service= dd.version= dd.trace_id=0 dd.span_id=0`.
 
 An example of this in practice:
 
@@ -2416,7 +2393,7 @@ ENV['DD_VERSION'] = '2.5.17'
 logger = Logger.new(STDOUT)
 logger.progname = 'my_app'
 logger.formatter  = proc do |severity, datetime, progname, msg|
-  "[#{datetime}][#{progname}][#{severity}][#{Datadog.tracer.active_correlation}] #{msg}\n"
+  "[#{datetime}][#{progname}][#{severity}][#{Datadog::Tracing.log_correlation}] #{msg}\n"
 end
 
 # When no trace is active
@@ -2424,7 +2401,7 @@ logger.warn('This is an untraced operation.')
 # [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=0 dd.span_id=0] This is an untraced operation.
 
 # When a trace is active
-Datadog.tracer.trace('my.operation') { logger.warn('This is a traced operation.') }
+Datadog::Tracing.trace('my.operation') { logger.warn('This is a traced operation.') }
 # [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=8545847825299552251 dd.span_id=3711755234730770098] This is a traced operation.
 ```
 
@@ -2442,7 +2419,7 @@ The `Net` adapter submits traces using `Net::HTTP` over TCP. It is the default t
 
 ```ruby
 Datadog.configure do |c|
-  c.tracer.transport_options = proc { |t|
+  c.tracing.transport_options = proc { |t|
     # Hostname, port, and additional options. :timeout is in seconds.
     t.adapter :net_http, '127.0.0.1', 8126, { timeout: 1 }
   }
@@ -2457,7 +2434,7 @@ To use, first configure your trace agent to listen by Unix socket, then configur
 
 ```ruby
 Datadog.configure do |c|
-  c.tracer.transport_options = proc { |t|
+  c.tracing.transport_options = proc { |t|
     # Provide local path to trace agent Unix socket
     t.adapter :unix, '/tmp/ddagent/trace.sock'
   }
@@ -2470,7 +2447,7 @@ The `Test` adapter is a no-op transport that can optionally buffer requests. For
 
 ```ruby
 Datadog.configure do |c|
-  c.tracer.transport_options = proc { |t|
+  c.tracing.transport_options = proc { |t|
     # Set transport to no-op mode. Does not retain traces.
     t.adapter :test
 
@@ -2487,7 +2464,7 @@ Custom adapters can be configured with:
 
 ```ruby
 Datadog.configure do |c|
-  c.tracer.transport_options = proc { |t|
+  c.tracing.transport_options = proc { |t|
     # Initialize and pass an instance of the adapter
     custom_adapter = CustomAdapter.new
     t.adapter custom_adapter
@@ -2556,7 +2533,7 @@ The underlying Datadog tracer can be configured by passing options (which match
 
 ```ruby
 # Where `options` is a Hash of options provided to Datadog::Tracer
-OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(options)
+OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(**options)
 ```
 
 It can also be configured by using `Datadog.configure` described in the [Tracer settings](#tracer-settings) section.