ddtrace 1.0.0.beta1 → 1.1.0

data/docs/UpgradeGuide.md

@@ -2,57 +2,78 @@
 
 # From 0.x to 1.0
 
-- [Namespacing & the public API](#namespacing--the-public-api)
-- [Configuration](#configuration)
-- [Instrumentation](#instrumentation)
-- [Full list of breaking changes](#full-list-of-breaking-changes)
+Upgrading `ddtrace` from 0.x to 1.x introduces some breaking changes which are outlined below.
 
-Upgrading `ddtrace` from 0.x to 1.x introduces some changes to namespacing, the public API, and the underlying trace data structure.
+**How to upgrade basic usage**
 
-Here's a list of the most common changes you may encounter:
+For users with a basic implementation (configuration file + out-of-the-box instrumentation), only minor changes to your configuration file are required: most applications take just minutes to update. Check out the following sections for a step-by-step guide.
 
-## Namespacing & the public API
+- [Configuration](#1.0-configuration)
+  - [`require` paths have changed](#1.0-configuration-requires)
+  - [Settings have been renamed](#1.0-configuration-settings)
+  - [Activating instrumentation](#1.0-configuration-instrumentation)
+- [Instrumentation](#1.0-instrumentation)
+  - [Service naming](#1.0-instrumentation-service-naming)
 
-To avoid naming conflicts with new Datadog features and products, many of the tracing constants and functions defined directly under `Datadog` have moved to `Datadog::Tracing`.
+**Additional upgrades for advanced usage**
 
-You can access most common functions through our [public API](https://www.rubydoc.info/gems/ddtrace/) within `Datadog::Tracing`. Use of some of the functions in the public API will be described in use cases below. Here's a few examples:
+For users with an advanced implementation of `ddtrace` (custom instrumentation, sampling or processing behavior, etc), some additional namespace and behavioral changes may be required. See the following sections for details about what features changed and how to use them.
 
-```ruby
-### Old 0.x ###
-Datadog.tracer.trace
-Datadog.tracer.active_span
-Datadog.tracer.active_correlation.to_s
+- [Namespacing](#1.0-namespacing)
+- [Trace API](#1.0-trace-api)
+  - [Removed `Datadog.tracer`](#1.0-trace-api-removed-tracer)
+  - [Removed access to `Datadog::Context`](#1.0-trace-api-removed-context)
+  - [Manual tracing & trace model](#1.0-trace-api-manual-tracing)
+  - [Accessing trace state](#1.0-trace-api-trace-state)
+  - [Distributed tracing](#1.0-trace-api-distributed)
+    - [Over HTTP](#1.0-trace-api-distributed-http)
+    - [Over gRPC](#1.0-trace-api-distributed-grpc)
+    - [Between threads](#1.0-trace-api-distributed-threads)
+  - [Sampling](#1.0-trace-api-sampling)
+  - [Processing pipeline](#1.0-trace-api-pipeline)
 
+**Appendix**
 
-### New 1.0 ###
-Datadog::Tracing.trace
-Datadog::Tracing.active_span
-Datadog::Tracing.log_correlation
-# ...and more...
-```
+For a comprehensive list of everything that changed, the appendix hosts some helpful and detailed tables with recommendations.
 
-Check out our [complete list of namespacing changes](#appendix-namespacing) for more details.
+  - [Namespace mappings](#1.0-appendix-namespace)
+    - [Constants](#1.0-appendix-namespace-constants)
+  - [Breaking changes](#1.0-appendix-breaking-changes)
 
-### Removed `Datadog.tracer`
+<h1 id="1.0-basic-upgrade">Upgrading basic usage</h1>
 
-Many of the functions accessed directly through `Datadog.tracer` have been moved to `Datadog::Tracing` instead.
+<h2 id="1.0-configuration">Configuration</h2>
 
-### Removed access to `Datadog::Context`
+<h3 id="1.0-configuration-requires">`require` paths have changed</h3>
 
-Direct usage of `Datadog::Context` has been removed. Previously, it was used to modify or access active trace state. Most use cases have been replaced by our public trace API.
+If you `require` any of the following paths, update them accordingly:
 
-## Configuration
+| 0.x `require` path          | 1.0 `require` path          |
+|-----------------------------|-----------------------------|
+| `ddtrace/opentelemetry`     | Removed                     |
+| `ddtrace/opentracer`        | `datadog/opentracer`        |
+| `ddtrace/profiling/preload` | `datadog/profiling/preload` |
 
-### Settings have been namespaced
+Using `require 'ddtrace'` will load all features by default. To load individual features, you may use the following paths instead:
 
-Configuration settings have been sorted into smaller configuration groups, by product.
+| Feature     | 1.0 `require` path   |
+|-------------|----------------------|
+| AppSec      | `datadog/appsec`     |
+| CI          | `datadog/ci`         |
+| OpenTracing | `datadog/opentracer` |
+| Profiling   | `datadog/profiling`  |
+| Tracing     | `datadog/tracing`    |
+
+<h3 id="1.0-configuration-settings">Settings have been renamed</h3>
+
+Configuration settings have been sorted into smaller configuration groups, by feature.
 
  - `Datadog.configure { |c| c.* }`: Datadog configuration settings
  - `Datadog.configure { |c| c.tracing.* }`: Tracing configuration settings
  - `Datadog.configure { |c| c.profiling.* }`: Profiling configuration settings
  - `Datadog.configure { |c| c.ci.* }`: CI configuration settings
 
-Existing applications should update their configuration files and settings accordingly. For example:
+For existing applications, configuration files should be updated accordingly. For example:
 
 ```ruby
 # config/initializers/datadog.rb
@@ -61,17 +82,14 @@ require 'ddtrace'
 ### Old 0.x ###
 Datadog.configure do |c|
   # Global settings
-  c.diagnostics.debug = true
+  c.tracer.hostname = '127.0.0.1'
+  c.tracer.port = 8126
+  c.runtime_metrics.enabled = true
   c.service = 'billing-api'
 
-  # Profiling settings
-  c.profiling.enabled = true
-
-  # Tracer settings
+  # Tracing settings
   c.analytics.enabled = true
-  c.runtime_metrics.enabled = true
-  c.tracer.hostname = '127.0.0.1'
-  c.tracer.port = 8126
+  c.tracer.partial_flush.enabled = true
 
   # CI settings
   c.ci_mode = (ENV['DD_ENV'] == 'ci')
@@ -79,7 +97,6 @@ Datadog.configure do |c|
   # Instrumentation
   c.use :rails
   c.use :redis, service_name: 'billing-redis'
-  c.use :resque
   c.use :rspec
 end
 
@@ -87,17 +104,14 @@ end
 ### New 1.0 ###
 Datadog.configure do |c|
   # Global settings
-  c.agent.hostname = '127.0.0.1'
+  c.agent.host = '127.0.0.1'
   c.agent.port = 8126
-  c.diagnostics.debug = true
+  c.runtime_metrics.enabled = true
   c.service = 'billing-api'
 
-  # Profiling settings
-  c.profiling.enabled = true
-
-  # Tracer settings
+  # Tracing settings
   c.tracing.analytics.enabled = true
-  c.tracing.runtime_metrics.enabled = true
+  c.tracing.partial_flush.enabled = true
 
   # CI settings
   c.ci.enabled = (ENV['DD_ENV'] == 'ci')
@@ -105,77 +119,251 @@ Datadog.configure do |c|
   # Instrumentation
   c.tracing.instrument :rails
   c.tracing.instrument :redis, service_name: 'billing-redis'
-  c.tracing.instrument :resque
   c.ci.instrument :rspec
 end
 ```
 
-Check out our [complete list of configuration changes](#appendix-configuration) for more details.
-
-### Activating instrumentation
-
-The `use` function has been renamed to `instrument`. Also, `instrument` has been namespaced to the specific product:
+Check out the table below for a list of common mappings:
+
+| 0.x setting                            | 1.0 setting                     |
+|----------------------------------------|---------------------------------|
+| `analytics.enabled`                    | `tracing.analytics.enabled`     |
+| `ci_mode.context_flush`                | `ci.context_flush`              |
+| `ci_mode.enabled`                      | `ci.enabled`                    |
+| `ci_mode.writer_options`               | `ci.writer_options`             |
+| `distributed_tracing`                  | `tracing.distributed_tracing`   |
+| `logger=`                              | `logger.instance=`              |
+| `profiling.exporter.transport_options` | Removed                         |
+| `report_hostname`                      | `tracing.report_hostname`       |
+| `runtime_metrics_enabled`              | `runtime_metrics.enabled`       |
+| `runtime_metrics(options)`             | Removed                         |
+| `sampling`                             | `tracing.sampling`              |
+| `test_mode`                            | `tracing.test_mode`             |
+| `tracer=`                              | Removed                         |
+| `tracer.debug`                         | `diagnostics.debug`             |
+| `tracer.enabled`                       | `tracing.enabled`               |
+| `tracer.env`                           | `env`                           |
+| `tracer.hostname`                      | `agent.host`                    |
+| `tracer.instance`                      | `tracing.instance`              |
+| `tracer.log`                           | `logger.instance`               |
+| `tracer.partial_flush`                 | `tracing.partial_flush.enabled` |
+| `tracer.port`                          | `agent.port`                    |
+| `tracer.sampler`                       | `tracing.sampler`               |
+| `tracer.tags`                          | `tags`                          |
+| `tracer.transport_options`             | `tracing.transport_options`     |
+| `tracer.transport_options(options)`    | Removed                         |
+| `tracer.writer`                        | `tracing.writer`                |
+| `tracer.writer_options`                | `tracing.writer_options`        |
+| `use`                                  | `tracing.instrument`            |
+
+<h3 id="1.0-configuration-instrumentation">Activating instrumentation</h3>
+
+ - The `use` function has been renamed to `instrument`.
+ - `instrument` has been namespaced within the feature to which it belongs.
+
+As an example:
 
 ```ruby
 ### Old 0.x ###
 Datadog.configure do |c|
+  # Tracing instrumentation
   c.use :rails
+
+  # CI instrumentation
   c.use :cucumber
 end
 
 
 ### New 1.0 ###
 Datadog.configure do |c|
+  # Tracing instrumentation
   c.tracing.instrument :rails
+
+  # CI instrumentation
   c.ci.instrument :cucumber
 end
 ```
 
-## Instrumentation
+Similarly, if you were accessing configuration for instrumentation, you will need to use the appropriate namespace:
 
-### Service naming
+```ruby
+### Old 0.x ###
+Datadog.configuration[:rails][:service_name]
+Datadog.configuration[:cucumber][:service_name]
 
-In 0.x, The `service` field on spans generated by Datadog integrations would typically default to the package name, e.g. `http` or `sidekiq`. This would often result in many "services" being generated by one application, one for each instrumented package. Users would often rectify this by overriding the `service_name` setting on each integration to get matching `service` names.
+### New 1.0 ###
+Datadog.configuration.tracing[:rails][:service_name]
+Datadog.configuration.ci[:cucumber][:service_name]
+```
 
-To remedy this in later 0.x versions, we introduced the global `service` name setting (also set via `DD_SERVICE`), which is the recommended way to set the name of your application. However, the Datadog integrations (with the exception of Rails) still did not employ this field.
+<h2 id="1.0-instrumentation">Instrumentation</h2>
 
-In 1.0, spans now inherit the global `service` name by default, unless otherwise explicitly set. This means for spans generated by Datadog integrations, they will default to the global `service` name, unless the `service_name` setting is configured for that integration.
+<h3 id="1.0-instrumentation-service-naming">Service naming</h3>
 
-Spans that describe external services (e.g. `mysql`), will default to some other name that describes the external service instead.
+**Define an application service name**
 
-As an example, expect the following code & trace in 0.x:
+We recommend setting the application's service name with `DD_SERVICE`, or by adding the following configuration:
+
+```ruby
+Datadog.configure do |c|
+  c.service = 'billing-api' # Or DD_SERVICE. Defaults to process name.
+end
+```
+
+If this is not set, it will default to the process name.
+
+**Update service names for your integrations**
+
+Spans now inherit the global `service` name by default, unless otherwise explicitly set. This means, generally speaking, spans generated by Datadog integrations will default to the global `service` name, unless the `service_name` setting is configured for that integration.
+
+Spans that describe external services (e.g. `mysql`) will continue to default to some other name that describes the external service instead. (e.g. `mysql`)
 
 ```ruby
 ### Old 0.x ###
+Datadog.configure do |c|
+  # Instrumentation that measures internal behavior
+  c.use :rails, service_name: 'billing-api'
+  c.use :resque, service_name: 'billing-api'
+  c.use :sidekiq, service_name: 'billing-api'
+
+  # Instrumentation that measures external services
+  c.use :active_record, service_name: 'billing-api_mysql' # Defaults to DB type e.g. mysql
+  c.use :http, service_name: 'billing-api_http' # Defaults to net/http
+  c.use :redis, service_name: 'billing-api_redis' # Defaults to redis
+end
+
+### New 1.0 ###
 Datadog.configure do |c|
   c.service = 'billing-api'
-  c.use :rails
-  c.use :redis
-  c.use :resque
+
+  # Instrumentation that measures internal behavior
+  # now inherits the application's service name.
+  c.tracing.instrument :rails
+  c.tracing.instrument :resque
+  c.tracing.instrument :sidekiq
+
+  # Instrumentation that measures external services
+  # defaults to adapter-specific names. You may still override
+  # these names with the `service_name:` option.
+  c.tracing.instrument :active_record, service_name: 'billing-api_mysql' # Defaults to DB type e.g. mysql
+  c.tracing.instrument :http, service_name: 'billing-api_http' # Defaults to net/http
+  c.tracing.instrument :redis, service_name: 'billing-api_redis' # Defaults to redis
 end
 ```
 
-![0.x trace](./0.x-trace.png)
+**Update Rails instrumentation**
+
+If your application activates and configures `rails` instrumentation, you will need to adjust your settings slightly.
 
-To reflect the following trace in 1.0 instead:
+The following options have been removed; instead, configure the underlying instrumentation directly.
+
+| 0.x setting                                 | 1.0 setting                                                    |
+|---------------------------------------------|----------------------------------------------------------------|
+| `use :rails, cache_service: <SERVICE>`      | `tracing.instrument :active_support, cache_service: <SERVICE>` |
+| `use :rails, controller_service: <SERVICE>` | `tracing.instrument :action_pack, service_name: <SERVICE>`     |
+| `use :rails, database_service: <SERVICE>`   | `tracing.instrument :active_record, service_name: <SERVICE>`   |
+| `use :rails, job_service: <SERVICE>`        | `tracing.instrument :active_job, service_name: <SERVICE>`      |
+| `use :rails, log_injection: true`           | `tracing.log_injection = true` (Is `true` by default.)         |
 
 ```ruby
+### Old 0.x ###
+Datadog.configure do |c|
+  c.use :rails, service_name: 'billing-api',
+                cache_service: 'billing-api-cache',
+                controller_service: 'billing-api-controllers',
+                database_service: 'billing-api-db',
+                job_service: 'billing-api-jobs',
+                log_injection: true
+end
+
 ### New 1.0 ###
 Datadog.configure do |c|
   c.service = 'billing-api'
+
   c.tracing.instrument :rails
-  c.tracing.instrument :redis
-  c.tracing.instrument :resque
+  c.tracing.instrument :active_support, cache_service: 'billing-api-cache'
+  c.tracing.instrument :action_pack, service_name: 'billing-api-controllers'
+  c.tracing.instrument :active_record, service_name: 'billing-api-db'
+  c.tracing.instrument :active_job, service_name: 'billing-api-jobs'
 end
 ```
 
-![1.0 trace](./1.0-trace.png)
+<h1 id="1.0-advanced-upgrade">Upgrading advanced usage</h1>
+
+<h2 id="1.0-namespacing">Namespacing</h2>
+
+Many files and constants within `ddtrace` have been recategorized by feature. The new categorization scheme is as follows:
+
+| Feature          | Namespace                | File path               |
+|------------------|--------------------------|-------------------------|
+| Globals          | `Datadog`                | `ddtrace`               |
+|                  |                          |                         |
+| CI               | `Datadog::CI`            | `datadog/ci`            |
+| Core (Internals) | `Datadog::Core`          | `datadog/core`          |
+| OpenTelemetry    | `Datadog::OpenTelemetry` | `datadog/opentelemetry` |
+| OpenTracing      | `Datadog::OpenTracer`    | `datadog/opentracer`    |
+| Profiling        | `Datadog::Profiling`     | `datadog/profiling`     |
+| Security         | `Datadog::AppSec`        | `datadog/appsec`        |
+| Tracing          | `Datadog::Tracing`       | `datadog/trace`         |
+
+As a result, if your application referenced file paths or constants affected by this change, they will need to be updated. Check out the [namespace mappings](#1.0-appendix-namespace) for some common cases and how to update them.
+
+<h2 id="1.0-trace-api">Trace API</h2>
+
+Usage of `Datadog.tracer` has been replaced with the `Datadog::Tracing` trace API. This module contains most of the functions that `Datadog.tracer` had, and most use cases will map one-to-one.
+
+For example:
+
+```ruby
+### Old 0.x ###
+Datadog.tracer.trace
+Datadog.tracer.active_span
+Datadog.tracer.active_correlation.to_s
+
+
+### New 1.0 ###
+Datadog::Tracing.trace
+Datadog::Tracing.active_span
+Datadog::Tracing.log_correlation
+
+# ...and more...
+```
+
+See the table below for most common mappings:
 
-### Manual tracing & trace model
+| 0.x usage                                                                                    | 1.0 usage                                   | Note                                                                |
+|----------------------------------------------------------------------------------------------|---------------------------------------------|---------------------------------------------------------------------|
+| `Datadog.tracer.active_correlation.to_s`                                                     | `Datadog::Tracing.log_correlation`          | Returns `String` with trace identifiers for logging.                |
+| `Datadog.tracer.active_correlation`                                                          | `Datadog::Tracing.correlation`              | Returns `Datadog::Tracing::Correlation::Identifier`                 |
+| `Datadog.tracer.active_root_span`                                                            | Removed                                     | Consider `Datadog::Tracing.active_trace` instead.                   |
+| `Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP`   | `Datadog::Tracing.keep!`                    | See [sampling](#1.0-trace-api-sampling) for details.                |
+| `Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT` | `Datadog::Tracing.reject!`                  | See [sampling](#1.0-trace-api-sampling) for details.                |
+| `Datadog.tracer.active_span.context`                                                         | Removed                                     | Consider `Datadog::Tracing.active_trace` instead.                   |
+| `Datadog.tracer.active_span`                                                                 | `Datadog::Tracing.active_span`              | See [trace state](#1.0-trace-api-trace-state) for details.          |
+| `Datadog.tracer.call_context`                                                                | Removed                                     | See [trace state](#1.0-trace-api-trace-state) for details.          |
+| `Datadog.tracer.configure(options)`                                                          | `Datadog.configure { \|c\| ... }`           | Use configuration API instead.                                      |
+| `Datadog.tracer.provider.context = context`                                                  | `Datadog::Tracing.continue_trace!(digest)`  | See [distributed tracing](#1.0-trace-api-distributed) for details.  |
+| `Datadog.tracer.set_tags(tags)`                                                              | `Datadog.configure { \|c\| c.tags = tags }` |                                                                     |
+| `Datadog.tracer.shutdown!`                                                                   | `Datadog::Tracing.shutdown!`                |                                                                     |
+| `Datadog.tracer.start_span`                                                                  | `Datadog::Tracing.trace`                    | See [manual tracing](#1.0-trace-api-manual-tracing) for details.    |
+| `Datadog.tracer.trace`                                                                       | `Datadog::Tracing.trace`                    | See [manual tracing](#1.0-trace-api-manual-tracing) for details.    |
 
-Manual tracing is now done through the public API.
 
-Whereas in 0.x, the block would yield a `Datadog::Span` as `span`, in 1.0, the block yields a `Datadog::SpanOperation` as `span` and `Datadog::TraceOperation` as `trace`.
+Also check out the functions defined within `Datadog::Tracing` in our [public API](https://www.rubydoc.info/gems/ddtrace/) for more details on their usage.
+
+<h3 id="1.0-trace-api-removed-tracer">Removed `Datadog.tracer`</h3>
+
+Many of the functions accessed directly through `Datadog.tracer` have been moved to `Datadog::Tracing` instead.
+
+<h3 id="1.0-trace-api-removed-context">Removed access to `Datadog::Context`</h3>
+
+Direct usage of `Datadog::Context` has been removed. Previously, it was used to modify or access active trace state. Most use cases have been replaced by our [public trace API](https://www.rubydoc.info/gems/ddtrace/).
+
+<h3 id="1.0-trace-api-manual-tracing">Manual tracing & trace model</h3>
+
+Manual tracing is now done through the [public API](https://www.rubydoc.info/gems/ddtrace/).
+
+Whereas in 0.x, the block would provide a `Datadog::Span` as `span`, in 1.0, the block provides a `Datadog::SpanOperation` as `span` and `Datadog::TraceOperation` as `trace`.
 
 ```ruby
 ### Old 0.x ###
@@ -193,11 +381,11 @@ Datadog::Tracing.trace('my.job') do |span, trace|
 end
 ```
 
-The yielded `span` is nearly identical in behavior, except access to some fields (like `context`) been removed. Instead, the `trace`, which models the trace itself, grants access to new functions.
+The provided `span` is nearly identical in behavior, except access to some fields (like `context`) been removed. Instead, the provided `trace`, which models the trace itself, grants access to new functions, of which some replace old `span` behavior.
 
 For more details about new behaviors and the trace model, see [this pull request](https://github.com/DataDog/dd-trace-rb/pull/1783).
 
-### Accessing trace state
+<h3 id="1.0-trace-api-trace-state">Accessing trace state</h3>
 
 The public API provides new functions to access active trace data:
 
@@ -222,11 +410,11 @@ Datadog::Tracing.correlation
 
 Use of `active_root_span` has been removed.
 
-### Distributed tracing
+<h3 id="1.0-trace-api-distributed">Distributed tracing</h3>
 
 Previously, distributed tracing required building new `Datadog::Context` objects, then replacing the context within the tracer.
 
-Instead, users utilize `TraceDigest` objects derived from a trace. This object represents the state of a trace. It can be used to propagate a trace across execution boundaries (processes, threads), or to continue a trace locally.
+Instead, users must use `TraceDigest` objects derived from a trace. `TraceDigest` represents the state of a trace. It can be used to propagate a trace across execution boundaries (processes, threads) or to continue a trace locally.
 
 ```ruby
 ### Old 0.x ###
@@ -248,12 +436,6 @@ end
 # Get trace continuation from active trace
 trace_digest = Datadog::Tracing.active_trace.to_digest
 
-# Continue a trace: explicit continuation
-# Inherits trace properties from the trace digest
-Datadog::Tracing.trace('my.job', continue_from: trace_digest) do |span, trace|
-  trace.id == trace_digest.trace_id
-end
-
 # Continue a trace: implicit continuation
 # Digest will be "consumed" by the next `trace` operation
 Datadog::Tracing.continue_trace!(trace_digest)
@@ -269,62 +451,91 @@ Datadog::Tracing.trace('my.job') do |span, trace|
 end
 ```
 
-#### Propagation over HTTP/gRPC
+New in 1.0, it's also possible to explicitly assign a trace block to continue from a specific trace, rather than implicitly inherit an active context. This gives users fine-grained control in applications where multiple traces run concurrently in the same execution context:
+
+```ruby
+### New 1.0 ###
+# Get trace continuation from active trace
+trace_digest = Datadog::Tracing.active_trace.to_digest
+
+# Continue a trace: explicit continuation
+# Inherits trace properties from the trace digest
+Datadog::Tracing.trace('my.job', continue_from: trace_digest) do |span, trace|
+  trace.id == trace_digest.trace_id
+end
+
+# Continue a trace: explicit continuation (using #continue_trace!)
+Datadog::Tracing.continue_trace!(trace_digest) do
+  # Traces implicitly continue within the block
+  Datadog::Tracing.trace('my.job') do |span, trace|
+    trace.id == trace_digest.trace_id
+  end
+end
+```
 
-To propagate a local trace to a remote service:
+<h4 id="1.0-trace-api-distributed-http">Over HTTP</h4>
+
+To propagate active trace to a remote service:
 
 ```ruby
 ### Old 0.x ###
-context = Datadog.tracer.call_context
-
-# HTTP
 headers = {}
+context = Datadog.tracer.call_context
 Datadog::HTTPPropagator.inject!(context, headers)
-# Inject `headers` into your HTTP headers
-
-# gRPC
-headers = {}
-Datadog::GRPCPropagator.inject!(context, headers)
-# Inject `headers` into your headers
 
+outgoing = Net::HTTP::Get.new(uri)
+headers.each { |name, value| outgoing[name] = value }
 
 ### New 1.0 ###
-trace_digest = Datadog::Tracing.active_trace.to_digest
-
-# HTTP
 headers = {}
+trace_digest = Datadog::Tracing.active_trace.to_digest
 Datadog::Tracing::Propagation::HTTP.inject!(trace_digest, headers)
-# Inject `headers` into your HTTP headers
 
-# gRPC
-headers = {}
-Datadog::Tracing::Propagation::GRPC.inject!(trace_digest, headers)
-# Inject `headers` into your headers
+outgoing = Net::HTTP::Get.new(uri)
+headers.each { |name, value| outgoing[name] = value }
 ```
 
-To continue a propagated trace locally:
+To continue a trace from a remote service:
 
 ```ruby
 ### Old 0.x ###
-# HTTP
-context = Datadog::HTTPPropagator.extract(request.env)
+incoming = Rack::Request.new(env)
+context = Datadog::HTTPPropagator.extract(incoming.env)
 Datadog.tracer.provider.context = context
 
-# gRPC
+### New 1.0 ###
+incoming = Rack::Request.new(env)
+trace_digest = Datadog::Tracing::Propagation::HTTP.extract(incoming.env)
+Datadog::Tracing.continue_trace!(trace_digest)
+```
+
+<h4 id="1.0-trace-api-distributed-grpc">Over gRPC</h4>
+
+To propagate active trace to a remote service:
+
+```ruby
+### Old 0.x ###
+context = Datadog.tracer.call_context
+Datadog::GRPCPropagator.inject!(context, metadata)
+
+### New 1.0 ###
+trace_digest = Datadog::Tracing.active_trace.to_digest
+Datadog::Tracing::Propagation::GRPC.inject!(trace_digest, metadata)
+```
+
+To continue a trace from a remote service:
+
+```ruby
+### Old 0.x ###
 context = Datadog::GRPCPropagator.extract(metadata)
 Datadog.tracer.provider.context = context
 
 ### New 1.0 ###
-# HTTP
-digest = Datadog::Tracing::Propagation::HTTP.extract(request.env)
-Datadog::Tracing.continue_trace!(digest)
-
-# gRPC
-digest = Datadog::Tracing::Propagation::GRPC.extract(metadata)
-Datadog::Tracing.continue_trace!(digest)
+trace_digest = Datadog::Tracing::Propagation::GRPC.extract(metadata)
+Datadog::Tracing.continue_trace!(trace_digest)
 ```
 
-#### Propagation between threads
+<h4 id="1.0-trace-api-distributed-threads">Between threads</h4>
 
 Traces do not implicitly propagate across threads, as they are considered different execution contexts.
 
@@ -333,6 +544,7 @@ However, if you wish to do this, trace propagation across threads is similar to
 NOTE: The same `TraceOperation` object should never be shared between threads; this would create race conditions.
 
 ```ruby
+### New 1.0 ###
 # Get trace digest
 trace = Datadog::Tracing.active_trace
 
@@ -349,7 +561,7 @@ Thread.new do
 end
 ```
 
-### Sampling
+<h3 id="1.0-trace-api-sampling">Sampling</h3>
 
 Accessing `call_context` to set explicit sampling has been removed.
 
@@ -363,8 +575,10 @@ Datadog.tracer.trace('web.request') do |span|
 end
 
 # From outside the trace:
-Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP # Keeps current trace
-Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT # Drops current trace
+# Keeps current trace
+Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP
+# Drops current trace
+Datadog.tracer.active_span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT
 
 
 ### New 1.0 ###
@@ -378,9 +592,9 @@ Datadog::Tracing.keep! # Keeps current trace
 Datadog::Tracing.reject! # Drops current trace
 ```
 
-### Processing pipeline
+<h3 id="1.0-trace-api-pipeline">Processing pipeline</h3>
 
-When using a trace processor in the processing pipeline, the block yields a `TraceSegment` as `trace` instead of `Array[Datadog::Span]`. This object can be modified by reference.
+When using a trace processor in the processing pipeline, the block provides a `TraceSegment` as `trace` (instead of `Array[Datadog::Span]`.) This object can be directly mutated.
 
 ```ruby
 ### Old 0.x ###
@@ -397,20 +611,11 @@ Datadog::Tracing.before_flush do |trace|
 end
 ```
 
-## Appendix
+<h2 id="1.0-appendix">Appendix</h2>
 
-<h3 id="appendix-namespacing">Namespacing</h3>
+<h3 id="1.0-appendix-namespace">Namespace mappings</h3>
 
-#### `require` paths
-
-| `0.x require path`          | `1.0 require path`          |
-|-----------------------------|-----------------------------|
-| `ddtrace/opentelemetry`     | `datadog/opentelemetry`     |
-| `ddtrace/opentracer`        | `datadog/opentracer`        |
-| `ddtrace/profiling/preload` | `datadog/profiling/preload` |
-
-
-#### Constants
+<h4 id="1.0-appendix-namespace-constants">Constants</h3>
 
 | `0.x Constant`                                                  | `1.0 Constant`                                                                          |
 |-----------------------------------------------------------------|-----------------------------------------------------------------------------------------|
@@ -477,81 +682,55 @@ end
 | `Datadog::Worker`                                               | `Datadog::Core::Worker`                                                                 |
 | `Datadog::Workers`                                              | `Datadog::Core::Workers`                                                                |
 
-
-<h3 id="appendix-configuration">Configuration</h3>
-
-| 0.x setting                            | 1.0 setting                   |
-|----------------------------------------|-------------------------------|
-| `analytics.enabled`                    | `tracing.analytics.enabled`   |
-| `ci_mode.context_flush`                | `ci.context_flush`            |
-| `ci_mode.enabled`                      | `ci.enabled`                  |
-| `ci_mode.writer_options`               | `ci.writer_options`           |
-| `distributed_tracing`                  | `tracing.distributed_tracing` |
-| `logger=`                              | `logger.instance=`            |
-| `profiling.exporter.transport_options` | Removed                       |
-| `report_hostname`                      | `tracing.report_hostname`     |
-| `runtime_metrics_enabled`              | `runtime_metrics.enabled`     |
-| `runtime_metrics(options)`             | Removed                       |
-| `sampling`                             | `tracing.sampling`            |
-| `test_moade`                           | `tracing.test_mode`           |
-| `tracer.enabled`                       | `tracing.enabled`             |
-| `tracer.hostname`                      | `agent.hostname`              |
-| `tracer.instance`                      | `tracing.instance`            |
-| `tracer.partial_flush`                 | `tracing.partial_flush`       |
-| `tracer.port`                          | `agent.port`                  |
-| `tracer.sampler`                       | `tracing.sampler`             |
-| `tracer.transport_options`             | `tracing.transport_options`   |
-| `tracer.transport_options(options)`    | Removed                       |
-| `tracer.writer`                        | `tracing.writer`              |
-| `tracer.writer_options`                | `tracing.writer_options`      |
-
-<h3 id="appendix-breaking-changes">Breaking changes</h3>
-
-| **Category**  | **Type** | **Description**                                                                                                      | **Change / Alternative**                                                                                                                                                  |
-|---------------|----------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| General       | Changed  | Many constants have been moved from `Datadog` to `Datadog::Core`, `Datadog::Tracing`, `Datadog::Profiling`           | Update your references to these [new namespaces](#appendix-namespacing) where appropriate.                                                                                |
-| General       | Removed  | `Datadog.tracer`                                                                                                     | Use methods in `Datadog::Tracing` instead.                                                                                                                                |
-| General       | Removed  | Support for trace agent API v0.2                                                                                     | Use v0.4 instead (default behavior.)                                                                                                                                      |
-| CI API        | Changed  | `DD_TRACE_CI_MODE_ENABLED` environment variable is now `DD_TRACE_CI_ENABLED`                                         | Use `DD_TRACE_CI_ENABLED` instead.                                                                                                                                        |
-| Configuration | Changed  | Many settings have been namespaced under specific categories                                                         | Update your configuration to these [new settings](#appendix-configuration) where appropriate.                                                                             |
-| Configuration | Removed  | `Datadog.configure(client, options)`                                                                                 | Use `Datadog::Tracing.configure_onto(client, options)` instead.                                                                                                           |
-| Configuration | Removed  | `DD_#{integration}_ANALYTICS_ENABLED` and `DD_#{integration}_ANALYTICS_SAMPLE_RATE` environment variables            | Use `DD_TRACE_#{integration}_ANALYTICS_ENABLED` and `DD_TRACE_#{integration}_ANALYTICS_SAMPLE_RATE` instead.                                                              |
-| Configuration | Removed  | `DD_PROPAGATION_INJECT_STYLE` and `DD_PROPAGATION_EXTRACT_STYLE` environment variables                               | Use `DD_PROPAGATION_STYLE_INJECT` and `DD_PROPAGATION_STYLE_EXTRACT` instead.                                                                                             |
-| Integrations  | Changed  | `-` in HTTP header tag names are kept, and no longer replaced with `_`                                               | For example: `http.response.headers.content_type` is changed to `http.response.headers.content-type`.                                                                     |
-| Integrations  | Changed  | `Contrib::Configurable#default_configuration` moved to `Tracing::Contrib::Configurable#new_configuration`            | Use `Tracing::Contrib::Configurable#new_configuration` instead.                                                                                                           |
-| Integrations  | Changed  | `Datadog.configuration.registry` moved to `Datadog.registry`                                                         | Use `Datadog.registry` instead.                                                                                                                                           |
-| Integrations  | Changed  | `service_name` option from each integration uses the default service name, unless it represents an external service  | Set `c.service` or `DD_SERVICE`, and remove `service_name` option from integration to inherit default service name. Set `service_name` option on integration to override. |
-| Integrations  | Changed  | Presto: `out.host` tag now contains only client hostname. Before it contained `"#{hostname}:#{port}"`.               |                                                                                                                                                                           |
-| Integrations  | Changed  | Rails: service_name does not propagate to sub-components (e.g. `c.use :rails, cache_service: 'my-cache'`)            | Use `c.service` instead.                                                                                                                                                  |
-| Integrations  | Changed  | Rails: Sub-components service_name options are now consistently called `:service_name`                               | Update your configuration to use `:service_name`.                                                                                                                         |
-| Integrations  | Changed  | Rails: Trace-logging correlation is enabled by default                                                               | Can be disabled using the environment variable `DD_LOGS_INJECTION=false`.                                                                                                 |
-| Integrations  | Removed  | `tracer` integration option from all integrations                                                                    | Remove this option from your configuration.                                                                                                                               |
-| Integrations  | Removed  | ActiveJob: `log_injection` option                                                                                    | Use `c.tracing.log_injection` instead.                                                                                                                                    |
-| Integrations  | Removed  | ActiveModelSerializers: service_name configuration                                                                   | Remove this option from your configuration.                                                                                                                               |
-| Integrations  | Removed  | ConcurrentRuby: unused option `service_name`                                                                         | Remove this option from your configuration.                                                                                                                               |
-| Integrations  | Removed  | Rails: 3.0 and 3.1 support.                                                                                          | Not supported.                                                                                                                                                            |
-| Integrations  | Removed  | Rails: `log_injection` option.                                                                                       | Use global `c.tracing.log_injection` instead.                                                                                                                             |
-| Integrations  | Removed  | Rails: `orm_service_name` option.                                                                                    | Remove this option from your configuration.                                                                                                                               |
-| Integrations  | Removed  | Resque: `workers` option. (All Resque workers are now automatically instrumented.)                                   | Remove this option from your configuration.                                                                                                                               |
-| Tracing API   | Changed  | `Correlation#to_s` to `Correlation#to_log_format`                                                                    | Use `Datadog::Tracing.log_correlation` instead.                                                                                                                           |
-| Tracing API   | Changed  | `Tracer#trace` implements keyword args                                                                               | Omit invalid options from `trace` calls.                                                                                                                                  |
-| Tracing API   | Changed  | Distributed tracing takes and yields `TraceDigest` instead of `Context`                                              | Update your usage of distributed tracing to use `continue_from` and `to_digest`.                                                                                          |
-| Tracing API   | Changed  | Rules for RuleSampler now yield `TraceOperation` instead of `Span`                                                   | Update Rule sampler usage to use `TraceOperation`.                                                                                                                        |
-| Tracing API   | Changed  | Trace processors yield `TraceSegment` instead of `Array[Span]`                                                       | Update pipeline callbacks to use `TraceSegment instead.                                                                                                                   |
-| Tracing API   | Removed  | `child_of:` option from `Tracer#trace`                                                                               | Not supported.                                                                                                                                                            |
-| Tracing API   | Removed  | `Pin.new(service, config: { option: value }).onto(client)`                                                           | Use `Datadog::Tracing.configure_onto(client, service_name: service, option: value)` instead.                                                                              |
-| Tracing API   | Removed  | `Pin.get_from(client)`                                                                                               | Use `Datadog::Tracing.configure_for(client)` instead.                                                                                                                     |
-| Tracing API   | Removed  | `Pipeline.before_flush`                                                                                              | Use `Datadog::Tracing.before_flush` instead.                                                                                                                              |
-| Tracing API   | Removed  | `SpanOperation#context`                                                                                              | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
-| Tracing API   | Removed  | `SpanOperation#parent`/`SpanOperation#parent=`                                                                       | Not supported.                                                                                                                                                            |
-| Tracing API   | Removed  | `SpanOperation#sampled`                                                                                              | Use `Datadog::TraceOperation#sampled?` instead.                                                                                                                           |
-| Tracing API   | Removed  | `Tracer#active_correlation`                                                                                          | Use `Datadog::Tracing.correlation` instead.                                                                                                                               |
-| Tracing API   | Removed  | `Tracer#active_correlation.to_log_format`                                                                            | Use `Datadog::Tracing.log_correlation` instead.                                                                                                                           |
-| Tracing API   | Removed  | `Tracer#active_root_span`                                                                                            | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
-| Tracing API   | Removed  | `Tracer#build_span`                                                                                                  | Use `Datadog::Tracing.trace` instead.                                                                                                                                     |
-| Tracing API   | Removed  | `Tracer#call_context`                                                                                                | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
-| Tracing API   | Removed  | `Tracer#configure`                                                                                                   | Not supported.                                                                                                                                                            |
-| Tracing API   | Removed  | `Tracer#services`                                                                                                    | Not supported.                                                                                                                                                            |
-| Tracing API   | Removed  | `Tracer#set_service_info`                                                                                            | Not supported.                                                                                                                                                            |
-| Tracing API   | Removed  | `Tracer#start_span`                                                                                                  | Use `Datadog::Tracing.trace` instead.                                                                                                                                     |
-| Tracing API   | Removed  | `Writer#write` and `SyncWriter#write` `services` argument                                                            | Not supported.                                                                                                                                                            |
+<h3 id="1.0-appendix-breaking-changes">Breaking changes</h3>
+
+| **Category**                          | **Type** | **Description**                                                                                                     | **Change / Alternative**                                                                                                                                                  |
+|---------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| General                               | Changed  | Many constants have been moved from `Datadog` to `Datadog::Core`, `Datadog::Tracing`                                | Update your references to these [new namespaces](#1.0-appendix-namespace-constants) where appropriate.                                                                    |
+| General                               | Changed  | Some `require` paths have been moved from `ddtrace` to `datadog`                                                    | Update your references to these [new paths](#1.0-appendix-namespace-requires) where appropriate.                                                                          |
+| General                               | Removed  | Support for trace agent API v0.2                                                                                    | Use v0.4 instead (default behavior.)                                                                                                                                      |
+| General                               | Removed  | `Datadog.configure` can no longer be called without a block                                                         | Remove uses of `Datadog.configure` without a block.                                                                                                                       |
+| CI API                                | Changed  | `DD_TRACE_CI_MODE_ENABLED` environment variable is now `DD_TRACE_CI_ENABLED`                                        | Use `DD_TRACE_CI_ENABLED` instead.                                                                                                                                        |
+| Configuration                         | Changed  | Many settings have been namespaced under specific categories                                                        | Update your configuration to these [new settings](#1.0-configuration-settings) where appropriate.                                                                         |
+| Configuration                         | Removed  | `Datadog.configure(client, options)`                                                                                | Use `Datadog::Tracing.configure_onto(client, options)` instead.                                                                                                           |
+| Configuration                         | Removed  | `DD_#{integration}_ANALYTICS_ENABLED` and `DD_#{integration}_ANALYTICS_SAMPLE_RATE` environment variables           | Use `DD_TRACE_#{integration}_ANALYTICS_ENABLED` and `DD_TRACE_#{integration}_ANALYTICS_SAMPLE_RATE` instead.                                                              |
+| Configuration                         | Removed  | `DD_PROPAGATION_INJECT_STYLE` and `DD_PROPAGATION_EXTRACT_STYLE` environment variables                              | Use `DD_PROPAGATION_STYLE_INJECT` and `DD_PROPAGATION_STYLE_EXTRACT` instead.                                                                                             |
+| Integrations                          | Changed  | `-` in HTTP header tag names are kept, and no longer replaced with `_`                                              | For example: `http.response.headers.content_type` is changed to `http.response.headers.content-type`.                                                                     |
+| Integrations                          | Changed  | `Contrib::Configurable#default_configuration` moved to `Tracing::Contrib::Configurable#new_configuration`           | Use `Tracing::Contrib::Configurable#new_configuration` instead.                                                                                                           |
+| Integrations                          | Changed  | `Datadog.configuration.registry` moved to `Datadog.registry`                                                        | Use `Datadog.registry` instead.                                                                                                                                           |
+| Integrations                          | Changed  | `service_name` option from each integration uses the default service name, unless it represents an external service | Set `c.service` or `DD_SERVICE`, and remove `service_name` option from integration to inherit default service name. Set `service_name` option on integration to override. |
+| Integrations                          | Removed  | `tracer` integration option from all integrations                                                                   | Remove this option from your configuration.                                                                                                                               |
+| Integrations - ActiveJob              | Removed  | `log_injection` option                                                                                              | Use `c.tracing.log_injection` instead.                                                                                                                                    |
+| Integrations - ActiveModelSerializers | Removed  | service_name configuration                                                                                          | Remove this option from your configuration.                                                                                                                               |
+| Integrations - ConcurrentRuby         | Removed  | unused option `service_name`                                                                                        | Remove this option from your configuration.                                                                                                                               |
+| Integrations - Presto                 | Changed  | `out.host` tag now contains only client hostname. Before it contained `"#{hostname}:#{port}"`.                      |                                                                                                                                                                           |
+| Integrations - Rails                  | Changed  | `service_name` does not propagate to sub-components (e.g. `c.use :rails, cache_service: 'my-cache'`)                | Use `c.service` instead.                                                                                                                                                  |
+| Integrations - Rails                  | Changed  | Sub-components service_name options are now consistently called `:service_name`                                     | Update your configuration to use `:service_name`.                                                                                                                         |
+| Integrations - Rails                  | Changed  | Trace-logging correlation is enabled by default                                                                     | Can be disabled using the environment variable `DD_LOGS_INJECTION=false`.                                                                                                 |
+| Integrations - Rails                  | Removed  | `log_injection` option.                                                                                             | Use global `c.tracing.log_injection` instead.                                                                                                                             |
+| Integrations - Rails                  | Removed  | `orm_service_name` option.                                                                                          | Remove this option from your configuration.                                                                                                                               |
+| Integrations - Rails                  | Removed  | 3.0 and 3.1 support.                                                                                                | Not supported.                                                                                                                                                            |
+| Integrations - Resque                 | Removed  | `workers` option. (All Resque workers are now automatically instrumented.)                                          | Remove this option from your configuration.                                                                                                                               |
+| Tracing API                           | Changed  | `Correlation#to_s` to `Correlation#to_log_format`                                                                   | Use `Datadog::Tracing.log_correlation` instead.                                                                                                                           |
+| Tracing API                           | Changed  | `Tracer#trace` implements keyword args                                                                              | Omit invalid options from `trace` calls.                                                                                                                                  |
+| Tracing API                           | Changed  | Distributed tracing takes and returns `TraceDigest` instead of `Context`                                            | Update your usage of distributed tracing to use `continue_from` and `to_digest`.                                                                                          |
+| Tracing API                           | Changed  | Rules for RuleSampler now return `TraceOperation` instead of `Span`                                                 | Update Rule sampler usage to use `TraceOperation`.                                                                                                                        |
+| Tracing API                           | Changed  | Trace processors return `TraceSegment` instead of `Array[Span]`                                                     | Update pipeline callbacks to use `TraceSegment instead.                                                                                                                   |
+| Tracing API                           | Removed  | `child_of:` option from `Tracer#trace`                                                                              | Not supported.                                                                                                                                                            |
+| Tracing API                           | Removed  | `Datadog.tracer`                                                                                                    | Use methods in `Datadog::Tracing` instead.                                                                                                                                |
+| Tracing API                           | Removed  | `Pin.get_from(client)`                                                                                              | Use `Datadog::Tracing.configure_for(client)` instead.                                                                                                                     |
+| Tracing API                           | Removed  | `Pin.new(service, config: { option: value }).onto(client)`                                                          | Use `Datadog::Tracing.configure_onto(client, service_name: service, option: value)` instead.                                                                              |
+| Tracing API                           | Removed  | `Pipeline.before_flush`                                                                                             | Use `Datadog::Tracing.before_flush` instead.                                                                                                                              |
+| Tracing API                           | Removed  | `SpanOperation#context`                                                                                             | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
+| Tracing API                           | Removed  | `SpanOperation#parent`/`SpanOperation#parent=`                                                                      | Not supported.                                                                                                                                                            |
+| Tracing API                           | Removed  | `SpanOperation#sampled`                                                                                             | Use `Datadog::TraceOperation#sampled?` instead.                                                                                                                           |
+| Tracing API                           | Removed  | `Tracer#active_correlation.to_log_format`                                                                           | Use `Datadog::Tracing.log_correlation` instead.                                                                                                                           |
+| Tracing API                           | Removed  | `Tracer#active_correlation`                                                                                         | Use `Datadog::Tracing.correlation` instead.                                                                                                                               |
+| Tracing API                           | Removed  | `Tracer#active_root_span`                                                                                           | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
+| Tracing API                           | Removed  | `Tracer#build_span`                                                                                                 | Use `Datadog::Tracing.trace` instead.                                                                                                                                     |
+| Tracing API                           | Removed  | `Tracer#call_context`                                                                                               | Use `Datadog::Tracing.active_trace` instead.                                                                                                                              |
+| Tracing API                           | Removed  | `Tracer#configure`                                                                                                  | Not supported.                                                                                                                                                            |
+| Tracing API                           | Removed  | `Tracer#services`                                                                                                   | Not supported.                                                                                                                                                            |
+| Tracing API                           | Removed  | `Tracer#set_service_info`                                                                                           | Not supported.                                                                                                                                                            |
+| Tracing API                           | Removed  | `Tracer#start_span`                                                                                                 | Use `Datadog::Tracing.trace` instead.                                                                                                                                     |
+| Tracing API                           | Removed  | `Writer#write` and `SyncWriter#write` `services` argument                                                           | Not supported.                                                                                                                                                            |