documentation for the new configuration option

DataDog · Sep 25, 2024 · d09de1e · d09de1e
1 parent 64f1297
commit d09de1e
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 1 deletion.
diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
@@ -2044,6 +2044,7 @@ For example, if `tracing.sampling.default_rate` is configured by [Remote Configu
 | `service`                                              | `DD_SERVICE`                                            | `String`                              | _Ruby filename_              | Your application's default service name. (e.g. `billing-api`) This value is set as a tag on all traces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `tags`                                                 | `DD_TAGS`                                               | `Hash`                                | `nil`                        | Custom tags in value pairs separated by `,` (e.g. `layer:api,team:intake`) These tags are set on all traces. See [Environment and tags](#environment-and-tags) for more details.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `time_now_provider`                                    |                                                         | `Proc`                                | `->{ Time.now }`             | Changes how time is retrieved. See [Setting the time provider](#setting-the-time-provider) for more details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `get_time_provider`                                    |                                                         | `Proc`                                | `lambda { \|unit\| ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, unit) }` | Changes how monotonic time is retrieved. See [Setting the time provider](#setting-the-time-provider) for more details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `version`                                              | `DD_VERSION`                                            | `String`                              | `nil`                        | Your application version (e.g. `2.5`, `202003181415`, `1.3-alpha`, etc.) This value is set as a tag on all traces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `telemetry.enabled`                                    | `DD_INSTRUMENTATION_TELEMETRY_ENABLED`                  | `Bool`                                | `true`                       | Allows you to enable sending telemetry data to Datadog. Can be disabled, as documented [here](https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection).                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | **Tracing**                                            |                                                         |                                       |                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -2661,7 +2662,15 @@ Datadog.configure do |c|
 end
 ```
 
-Span duration calculation will still use the system monotonic clock when available, thus not being affected by this setting.
+Span duration calculation uses the system monotonic clock when available, to change the function that provides monotonic clock,
+configure the following:
+
+```ruby
+Datadog.configure do |c|
+  # For Timecop, for example, `::Process.clock_gettime_without_mock` allows the tracer to use the real monotonic time.
+  c.get_time_provider = lambda { |unit| ::Process.clock_gettime_without_mock(::Process::CLOCK_MONOTONIC, unit) }
+end
+```
 
 ### Metrics
 

diff --git a/lib/datadog/core/configuration/settings.rb b/lib/datadog/core/configuration/settings.rb
@@ -654,6 +654,17 @@ def initialize(*_)
           end
         end
 
+        # The monotonic time clocl provider used by Datadog.
+        # It must respect the interface of Datadog::Core::Utils::Time#get_time method.
+        #
+        # When testing, it can be helpful to use a different monotonic time clock provider.
+        #
+        # For [Timecop](https://rubygems.org/gems/timecop), for example,
+        # `lambda { |unit| ::Process.clock_gettime_without_mock(::Process::CLOCK_MONOTONIC, unit) }`
+        # allows Datadog features to use the real monotonic time when time is frozen with `Timecop.mock_process_clock = true`.
+        #
+        # @default `lambda { |unit| ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, unit)}`
+        # @return [Proc<Numeric>]
         option :get_time_provider do |o|
           o.default_proc { |unit| ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, unit) }
           o.type :proc