ddtrace 0.50.0 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9add4aab5afd288528cb19861c90d1c51f0760cc683716cb5aefdbd03cd6ee0
-  data.tar.gz: 9eba21868f503c91e4af96fa2dd5e625fc60ac19b43ff6b1f538c269e3159599
+  metadata.gz: 8f5ee0735d05ecdadc38bbc0978a2087141d136f31b1848845518d2086f877d2
+  data.tar.gz: dd677af05b413d5593440aedca7b36dc9aba0c9ba08e9213eb8eb9c5443cb2d9
 SHA512:
-  metadata.gz: 36623270e170b810ba47ec10fab7aeb73d366653149266661468727153c71a6b322eb1f87dbda1f2be1587aa49fc8a2c9ffdbf06e753a03d558885123ac0b71b
-  data.tar.gz: 9140282f96d2f3fd5450b51f5f7f1a9370c9772d40eac8f67ed5dbd1a0d421bc1a2689019a9592f47593853dcbaf44a5691870c4224f5c924e7155858167c33e
+  metadata.gz: 9f964c58615348135d915933cea46dac145c1266fa7d573fd8609c7eaf13be8667a8917af8ad5d93340935c00d2dc4bcd89adc7e14db7667eadf005448594f91
+  data.tar.gz: 23ee7b6812d641a0f6bdc65e43baac6f7f17cc68ca2c07a42e87158400a9b97944aa0f6416c2002fdbbfd0e00f92b1e0a6907de7ee3df39e0840f408a6ec1aec

data/.editorconfig

@@ -0,0 +1,22 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.h]
+indent_style = space
+indent_size = 2
+
+[*.c]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2

data/.gitignore

@@ -58,3 +58,10 @@ Gemfile.lock
 
 # bundle config
 gemfiles/.bundle
+
+# Native extension binaries
+lib/*.bundle
+lib/*.so
+
+# Extra file kept by sorbet for debugging usage, as documented in https://sorbet.org/docs/adopting#step-6-source-control
+sorbet/rbi/hidden-definitions/errors.txt

data/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 ## [Unreleased]
 
+## [0.52.0] - 2021-08-09
+
+Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.52.0
+
+Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.51.1...v0.52.0
+
+### Added
+
+- Add Sorbet typechecker to dd-trace-rb ([#1607][])
+
+  Note that no inline type signatures were added, to avoid a hard dependency on sorbet.
+
+- Profiler: Add support for annotating profiler stacks with the resource of the active web trace, if any ([#1623][])
+
+  Note that this data is not yet visible on the profiling interface.
+
+- Add error_handler option to GRPC tracer configuration ([#1583][]) ([@fteem][])
+- User-friendly handling of slow submissions on shutdown ([#1601][])
+- Profiler: Add experimental toggle to disable the profiling native extension ([#1594][])
+- Profiler: Bootstrap profiling native extension ([#1584][])
+
+### Changed
+
+- Profiler: Profiling data is no longer reported when there's less than 1 second of data to report ([#1630][])
+- Move Grape span resource setting to beginning of request ([#1629][])
+- Set resource in Sinatra spans at the beginning of requests, and delay setting fallback resource to end of requests ([#1628][])
+- Move Rails span resource setting to beginning of request ([#1626][])
+- Make registry a global constant repository ([#1572][])
+- Profiler: Remove automatic agentless support ([#1590][])
+
+### Fixed
+
+- Profiler: Fix CPU-time accounting in Profiling when fibers are used ([#1636][])
+- Don't set peer.service tag on grpc.server spans ([#1632][])
+- CI-App: Fix GitHub actions environment variable extraction ([#1622][])
+- Additional Faraday 1.4+ cgroup parsing formats ([#1595][])
+- Avoid shipping development cruft files in gem releases ([#1585][])
+
+## [0.51.1] - 2021-07-13
+
+Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.51.1
+
+Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.51.0...v0.51.1
+
+### Fixed
+
+- AWS-SDK instrumentation without `aws-sdk-s3` ([#1592][])
+
+## [0.51.0] - 2021-07-12
+
+Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.51.0
+
+Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.50.0...v0.51.0
+
+### Added
+
+- Semantic Logger trace correlation injection ([#1566][])
+- New and improved Lograge trace correlation injection ([#1555][])
+- Profiler: Start profiler on `ddtrace/auto_instrument`
+- CI-App: Add runtime and OS information ([#1587][])
+- CI-App: Read metadata from local git repository ([#1561][])
+
+### Changed
+
+- Rename `Datadog::Runtime` to `Datadog::Core::Environment` ([#1570][])
+
+  As we prepare the `Datadog` Ruby namespace to better accommodate new products, we are moving a few internal modules to a different location to avoid conflicts.
+
+  None of the affected files are exposed publicly in our documentation, and they are only expected to be used internally and may change at any time, even between patch releases.
+
+  * The following modules have been moved:
+  ```ruby
+  Datadog::Runtime::Cgroup -> Datadog::Core::Environment::Cgroup
+  Datadog::Runtime::ClassCount -> Datadog::Core::Environment::ClassCount
+  Datadog::Runtime::Container -> Datadog::Core::Environment::Container
+  Datadog::Runtime::GC -> Datadog::Core::Environment::GC
+  Datadog::Runtime::Identity -> Datadog::Core::Environment::Identity
+  Datadog::Runtime::ObjectSpace -> Datadog::Core::Environment::ObjectSpace
+  Datadog::Runtime::Socket -> Datadog::Core::Environment::Socket
+  Datadog::Runtime::ThreadCount -> Datadog::Core::Environment::ThreadCount
+  ```
+  * Most constants from `Datadog::Ext::Runtime` have been moved to a new module: `Datadog::Core::Environment::Ext`.
+- Skip CPU time instrumentation if logging gem is detected ([#1557][])
+
+### Fixed
+
+- Initialize `dogstatsd-ruby` in single threaded mode ([#1576][])
+
+  This should alleviate any existing issues with `dogstatsd-ruby` resource leaks.
+
+- Do not use configured `dogstatsd-ruby` instance when it's an incompatible version ([#1560][])
+- Ensure tags with special Datadog processing are consistently serialized ([#1556][])
+- Profiler: NameError during initialization ([#1552][])
+
+### Refactored
+- Improvements to test suite & CI ([#1586][])
+- Improvements to documentation ([#1397][])
+
 ## [0.50.0] - 2021-06-07
 
 Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.50.0
@@ -1713,6 +1811,8 @@ Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.3.1
 Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 
 [Unreleased]: https://github.com/DataDog/dd-trace-rb/compare/v0.48.0...master
+[0.51.1]: https://github.com/DataDog/dd-trace-rb/compare/v0.51.0...v0.51.1
+[0.51.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.50.0...v0.51.0
 [0.48.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.47.0...v0.48.0
 [0.47.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.46.0...v0.47.0
 [0.46.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.45.0...v0.46.0
@@ -2359,6 +2459,7 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [#1393]: https://github.com/DataDog/dd-trace-rb/issues/1393
 [#1394]: https://github.com/DataDog/dd-trace-rb/issues/1394
 [#1396]: https://github.com/DataDog/dd-trace-rb/issues/1396
+[#1397]: https://github.com/DataDog/dd-trace-rb/issues/1397
 [#1398]: https://github.com/DataDog/dd-trace-rb/issues/1398
 [#1399]: https://github.com/DataDog/dd-trace-rb/issues/1399
 [#1400]: https://github.com/DataDog/dd-trace-rb/issues/1400
@@ -2419,6 +2520,35 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [#1537]: https://github.com/DataDog/dd-trace-rb/issues/1537
 [#1543]: https://github.com/DataDog/dd-trace-rb/issues/1543
 [#1544]: https://github.com/DataDog/dd-trace-rb/issues/1544
+[#1552]: https://github.com/DataDog/dd-trace-rb/issues/1552
+[#1555]: https://github.com/DataDog/dd-trace-rb/issues/1555
+[#1556]: https://github.com/DataDog/dd-trace-rb/issues/1556
+[#1557]: https://github.com/DataDog/dd-trace-rb/issues/1557
+[#1560]: https://github.com/DataDog/dd-trace-rb/issues/1560
+[#1561]: https://github.com/DataDog/dd-trace-rb/issues/1561
+[#1566]: https://github.com/DataDog/dd-trace-rb/issues/1566
+[#1570]: https://github.com/DataDog/dd-trace-rb/issues/1570
+[#1572]: https://github.com/DataDog/dd-trace-rb/issues/1572
+[#1576]: https://github.com/DataDog/dd-trace-rb/issues/1576
+[#1583]: https://github.com/DataDog/dd-trace-rb/issues/1583
+[#1584]: https://github.com/DataDog/dd-trace-rb/issues/1584
+[#1585]: https://github.com/DataDog/dd-trace-rb/issues/1585
+[#1586]: https://github.com/DataDog/dd-trace-rb/issues/1586
+[#1587]: https://github.com/DataDog/dd-trace-rb/issues/1587
+[#1590]: https://github.com/DataDog/dd-trace-rb/issues/1590
+[#1592]: https://github.com/DataDog/dd-trace-rb/issues/1592
+[#1594]: https://github.com/DataDog/dd-trace-rb/issues/1594
+[#1595]: https://github.com/DataDog/dd-trace-rb/issues/1595
+[#1601]: https://github.com/DataDog/dd-trace-rb/issues/1601
+[#1607]: https://github.com/DataDog/dd-trace-rb/issues/1607
+[#1622]: https://github.com/DataDog/dd-trace-rb/issues/1622
+[#1623]: https://github.com/DataDog/dd-trace-rb/issues/1623
+[#1626]: https://github.com/DataDog/dd-trace-rb/issues/1626
+[#1628]: https://github.com/DataDog/dd-trace-rb/issues/1628
+[#1629]: https://github.com/DataDog/dd-trace-rb/issues/1629
+[#1630]: https://github.com/DataDog/dd-trace-rb/issues/1630
+[#1632]: https://github.com/DataDog/dd-trace-rb/issues/1632
+[#1636]: https://github.com/DataDog/dd-trace-rb/issues/1636
 [@AdrianLC]: https://github.com/AdrianLC
 [@Azure7111]: https://github.com/Azure7111
 [@BabyGroot]: https://github.com/BabyGroot
@@ -2470,6 +2600,7 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [@evan-waters]: https://github.com/evan-waters
 [@fledman]: https://github.com/fledman
 [@frsantos]: https://github.com/frsantos
+[@fteem]: https://github.com/fteem
 [@gaborszakacs]: https://github.com/gaborszakacs
 [@giancarlocosta]: https://github.com/giancarlocosta
 [@gingerlime]: https://github.com/gingerlime

data/CONTRIBUTING.md

@@ -20,8 +20,6 @@ Additionally, if you can, include:
  - Links to similar features that would serve as a good comparison
  - (Any other details that would be useful for implementing this feature!)
 
-Feature requests will be reviewed, discussed, and then added to [our Community project](https://github.com/DataDog/dd-trace-rb/projects/2).
-
 ## Found a bug?
 
 For any urgent matters (such as outages) or issues concerning the Datadog service or UI, contact our support team via https://docs.datadoghq.com/help/ for direct, faster assistance.
@@ -46,7 +44,7 @@ If at all possible, also provide:
  - Code sample or test that reproduces the problem
  - An explanation of what causes the bug and/or how it can be fixed
 
-Reports that include rich detail are better, and ones with code that reproduce the bug are best. Bug requests are triaged, reviewed, and added to [our Community project](https://github.com/DataDog/dd-trace-rb/projects/2).
+Reports that include rich detail are better, and ones with code that reproduce the bug are best.
 
 ## Have a patch?
 
@@ -74,8 +72,6 @@ We also recommend that you share in your description:
  - Benchmarks if the feature is anticipated to have performance implications
  - Any limitations, constraints or risks that are important to consider
 
-Pull requests will be reviewed and added to [our Community project](https://github.com/DataDog/dd-trace-rb/projects/2).
-
 For more information on common topics such as debugging locally, or how to write new integrations, check out [our development guide](https://github.com/DataDog/dd-trace-rb/blob/master/docs/DevelopmentGuide.md). If at any point you have a question or need assistance with your pull request, feel free to mention a project member! We're always happy to help contributors with their pull requests.
 
 ## Final word

data/ddtrace.gemspec

@@ -28,7 +28,14 @@ Gem::Specification.new do |spec|
     raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
   end
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files =
+    `git ls-files -z`
+    .split("\x0")
+    .reject { |f| f.match(%r{^(test|spec|features|[.]circleci|[.]github|[.]dd-ci|benchmarks|gemfiles|integration|tasks|sorbet)/}) }
+    .reject do |f|
+      ['.dockerignore', '.env', '.gitattributes', '.gitlab-ci.yml', '.rspec', '.rubocop.yml',
+       '.rubocop_todo.yml', '.simplecov', 'Appraisals', 'Gemfile', 'Rakefile', 'docker-compose.yml'].include?(f)
+    end
   spec.executables   = ['ddtracerb']
   spec.require_paths = ['lib']
 
@@ -41,4 +48,6 @@ Gem::Specification.new do |spec|
 
   # Used by the profiler
   spec.add_dependency 'ffi', '~> 1.0'
+
+  spec.extensions = ['ext/ddtrace_profiling_native_extension/extconf.rb']
 end

data/docs/DevelopmentGuide.md

@@ -9,6 +9,8 @@ This guide covers some of the common how-tos and technical reference material fo
      - [Writing tests](#writing-tests)
      - [Running tests](#running-tests)
      - [Checking code quality](#checking-code-quality)
+     - [Running benchmarks](#running-benchmarks)
+     - [Type checking](#type-checking)
  - [Appendix](#appendix)
      - [Writing new integrations](#writing-new-integrations)
      - [Custom transport adapters](#custom-transport-adapters)
@@ -162,6 +164,19 @@ $ bundle exec rake spec:benchmark
 
 Results are printed to STDOUT as well as written to the `./tmp/benchmark/` directory.
 
+## Type checking
+
+This library uses the [Sorbet](https://sorbet.org/) type checker. Sorbet can be run with `bundle exec srb tc` (or `bundle exec rake
+typecheck`). There's also Language Server Protocol support, if your editor supports it.
+
+Type checking can be controlled on a file-by-file manner, using a `# typed: ...` comment. The default (when none is provided) is assuming `# typed: false`.
+
+Things to note:
+
+* For compatibility with older Rubies, we use Sorbet but do not yet allow type annotations in the codebase. If Sorbet is blocking you, feel free to use `# typed: false` or `# typed: ignore` with a quick note on why this was needed. In many cases, Sorbet can typecheck a file correctly with no extra type annotations.
+
+* Most integration-specific code will reference optional external dependencies which Sorbet cannot see into. You'll probably need to use `# typed: false` or `# typed: ignore`  for those files as well.
+
 ## Appendix
 
 ### Writing new integrations

data/docs/GettingStarted.md

@@ -86,6 +86,11 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
          - [For application runtime](#for-application-runtime)
      - [OpenTracing](#opentracing)
      - [Profiling](#profiling)
+         - [Troubleshooting](#troubleshooting)
+         - [Profiling Resque jobs](#profiling-resque-jobs)
+ - [Known issues and suggested configurations](#known-issues-and-suggested-configurations)
+    - [Payload too large](#payload-too-large)
+    - [Stack level too deep](#stack-level-too-deep)
 
 ## Compatibility
 
@@ -1025,6 +1030,7 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | Key | Description | Default |
 | --- | ----------- | ------- |
 | `service_name` | Service name used for `grpc` instrumentation | `'grpc'` |
+| `error_handler` | Custom error handler invoked when a request is an error. A `Proc` that accepts `span` and `error` parameters. Sets error on the span by default. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
 
 **Configuring clients to use different settings**
 
@@ -2237,7 +2243,7 @@ In many cases, such as logging, it may be useful to correlate trace IDs to other
 
 ##### Automatic
 
-For Rails applications using the default logger (`ActiveSupport::TaggedLogging`) 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 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`:
 
 ```ruby
 # config/initializers/datadog.rb
@@ -2248,8 +2254,6 @@ Datadog.configure do |c|
 end
 ```
 
-_Note:_ For `lograge` users who have also defined `lograge.custom_options` in an `initializers/lograge.rb` configuration file, due to the order that Rails loads initializers (alphabetical), automatic trace correlation may not take effect, since `initializers/datadog.rb` would be overwritten by the `initializers/lograge.rb` initializer. To support automatic trace correlation with _existing_ `lograge.custom_options`, use the [Manual (Lograge)](#manual-lograge) configuration below.
-
 ##### 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.
@@ -2409,7 +2413,7 @@ The tracer and its integrations can produce some additional metrics that can pro
 To configure your application for metrics collection:
 
 1. [Configure your Datadog agent for StatsD](https://docs.datadoghq.com/developers/dogstatsd/#setup)
-2. Add `gem 'dogstatsd-ruby', '~> 4.0'` to your Gemfile (note that it is advised to pin v4.x [until this issue is solved](https://github.com/DataDog/dogstatsd-ruby/issues/182))
+2. Add `gem 'dogstatsd-ruby', '~> 5.2'` to your Gemfile
 
 #### For application runtime
 
@@ -2490,8 +2494,42 @@ However, additional instrumentation provided by Datadog can be activated alongsi
 
 To get started with profiling, follow the [Profiler Getting Started Guide](https://docs.datadoghq.com/tracing/profiler/getting_started/?code-lang=ruby).
 
+#### Troubleshooting
+
+If you run into issues with profiling, please check the [Profiler Troubleshooting Guide](https://docs.datadoghq.com/tracing/profiler/profiler_troubleshooting/?code-lang=ruby).
+
 #### Profiling Resque jobs
 
 When profiling [Resque](https://github.com/resque/resque) jobs, you should set the `RUN_AT_EXIT_HOOKS=1` option described in the [Resque](https://github.com/resque/resque/blob/v2.0.0/docs/HOOKS.md#worker-hooks) documentation.
 
 Without this flag, profiles for short-lived Resque jobs will not be available as Resque kills worker processes before they have a chance to submit this information.
+
+## Known issues and suggested configurations
+
+### Payload too large
+
+By default, Datadog limits the size of trace payloads to prevent memory overhead within instrumented applications. As a result, traces containing thousands of operations may not be sent to Datadog.
+
+If traces are missing, enable [debug mode](#tracer-settings) to check if messages containing `"Dropping trace. Payload too large"` are logged.
+
+Since debug mode is verbose, Datadog does not recommend leaving this enabled or enabling this in production. Disable it after confirming. You can inspect the [Datadog Agent logs](https://docs.datadoghq.com/agent/guide/agent-log-files/) for similar messages.
+
+If you have confirmed that traces are dropped due to large payloads, then enable the [partial_flush](#tracer-settings) setting to break down large traces into smaller chunks.
+
+### Stack level too deep
+
+Datadog tracing collects trace data by adding instrumentation into other common libraries (e.g. Rails, Rack, etc.) Some libraries provide APIs to add this instrumentation, but some do not. In order to add instrumentation into libraries lacking an instrumentation API, Datadog uses a technique called "monkey-patching" to modify the code of that library.
+
+In Ruby version 1.9.3 and earlier, "monkey-patching" often involved the use of [`alias_method`](https://ruby-doc.org/core-3.0.0/Module.html#method-i-alias_method), also known as *method rewriting*, to destructively replace existing Ruby methods. However, this practice would often create conflicts & errors if two libraries attempted to "rewrite" the same method. (e.g. two different APM packages trying to instrument the same method.)
+
+In Ruby 2.0, the [`Module#prepend`](https://ruby-doc.org/core-3.0.0/Module.html#method-i-prepend) feature was introduced. This feature avoids destructive method rewriting and allows multiple "monkey patches" on the same method. Consequently, it has become the safest, preferred means to "monkey patch" code.
+
+Datadog instrumentation almost exclusively uses the `Module#prepend` feature to add instrumentation non-destructively. However, some libraries (typically those supporting Ruby < 2.0) still use `alias_method` which can create conflicts with Datadog instrumentation, often resulting in `SystemStackError` or `stack level too deep` errors.
+
+As the implementation of `alias_method` exists within those libraries, Datadog generally cannot fix them. However, some libraries have known workarounds:
+
+* `rack-mini-profiler`: [Net::HTTP stack level too deep errors](https://github.com/MiniProfiler/rack-mini-profiler#nethttp-stack-level-too-deep-errors).
+
+For libraries without a known workaround, consider removing the library using `alias` or `Module#alias_method` or separating libraries into different environments for testing.
+
+For any further questions or to report an occurence of this issue, please [reach out to Datadog support](https://docs.datadoghq.com/help)

data/docs/ProfilingDevelopment.md

@@ -11,7 +11,7 @@ Components below live inside <../lib/ddtrace/profiling>:
 * `Collectors::Stack`: Collects stack trace samples from Ruby threads for both CPU-time (if available) and wall-clock.
   Runs on its own background thread.
 * `Encoding::Profile`: Encodes gathered data into the pprof format.
-* `Events::Stack`, `Events::StackSample`, `Events::StackExceptionSample`: Entity classes used to represent stacks.
+* `Events::Stack`, `Events::StackSample`: Entity classes used to represent stacks.
 * `Ext::CPU`: Monkey patches Ruby's `Thread` with our `Ext::CThread` to enable CPU-time profiling.
 * `Ext::CThread`: Extension used to enable CPU-time profiling via use of Pthread's `getcpuclockid`.
 * `Ext::Forking`: Monkey patches `Kernel#fork`, adding a `Kernel#at_fork` callback mechanism which is used to restore
@@ -20,6 +20,7 @@ Components below live inside <../lib/ddtrace/profiling>:
 * `Tasks::Setup`: Takes care of loading our extensions/monkey patches to handle fork() and CPU profiling.
 * `Transport::*` (in <../lib/ddtrace/profiling/transport>): Implements transmission of profiling payloads to the Datadog agent
   or backend.
+* `TraceIdentifiers::*`: Used to retrieve trace id and span id from tracers, to be used to connect traces to profiles.
 * `BacktraceLocation`: Entity class used to represent an entry in a stack trace.
 * `Buffer`: Bounded buffer used to store profiling events.
 * `Exporter`: Writes profiling data to a given transport.
@@ -41,22 +42,14 @@ flow:
 4. The `Setup` task activates our extensions
     * `Datadog::Profiling::Ext::Forking`
     * `Datadog::Profiling::Ext::CPU`
-5. Still inside `Datadog::Components`, the `build_profiler` method then creates and wires up the Profiler:
-    ```ruby
-          recorder = build_profiler_recorder(settings)
-          collectors = build_profiler_collectors(settings, recorder)
-          exporters = build_profiler_exporters(settings)
-          scheduler = build_profiler_scheduler(settings, recorder, exporters)
-
-          Datadog::Profiler.new(collectors, scheduler)
-    ```
+5. Still inside `Datadog::Components`, the `build_profiler` method then creates and wires up the Profiler as such:
     ```asciiflow
             +------------+
             |  Profiler  |
-            +-+--------+-+
-              |        |
-              v        v
-    +---------+--+  +--+--------+
+            +-+-------+--+
+              |       |
+              v       v
+    +---------+--+  +-+---------+
     | Collectors |  | Scheduler |
     +---------+--+  +-+-------+-+
               |       |       |
@@ -86,3 +79,29 @@ takes care of encoding the data and reporting it to the datadog agent (or to the
 ## How CPU-time profiling works
 
 **TODO**: Document our pthread-based approach to getting CPU-time for threads.
+
+## How linking of traces to profiles works
+
+The [code hotspots feature](https://docs.datadoghq.com/tracing/profiler/connect_traces_and_profiles) allows users to start
+from a trace and then to investigate the profile that corresponds to that trace.
+
+This works in two steps:
+1. Linking a trace to the profile that was gathered while it executed
+2. Enabling the filtering of a profile to contain only the samples relating to a given trace/span
+
+To link a trace to a profile, we must ensure that both have the same `runtime-id` tag.
+This tag is in `Datadog::Runtime::Identity.id` and is automatically added by both the tracer and the profiler to reported
+traces/profiles.
+
+The profiler backend links a trace covering a given time interval to the profiles covering the same time interval,
+whenever they share the same `runtime-id`.
+
+To further enable filtering of a profile to show only samples related to a given trace/span, each sample taken by the
+profiler is tagged with the trace_id and span_id for the given trace/span.
+
+This is done using the `Datadog::Profiling::TraceIdentifiers::Helper` that retrieves a trace_id and span_id, if
+available, from the supported tracers. This helper is called by the `Collectors::Stack` during sampling.
+
+Note that if a given trace executes too fast, it's possible that the profiler will not contain any samples for that
+specific trace. Nevertheless, the linking still works and is useful, as it allows users to explore what was going on their
+profile at that time, even if they can't filter down to the specific request.