ddtrace 1.19.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37ea5c2fe193569e17d13e026b4477dd8806c00df50250fb5f69854c23e6e6a5
-  data.tar.gz: 858b756d1ef6baddb66f85fb44f3301b317e151d58e4e299390f819621d4ecb8
+  metadata.gz: 1baa733b2ad3335ab214de620e849f1eab598effb15d24f336aa20147e6e34be
+  data.tar.gz: 684bbf501475346f6e2a32b5a9284d59e193344e23d63b912624de77ac8bbbad
 SHA512:
-  metadata.gz: 3d86acc37f0bcb7d3b680c4ee8698b45eeb10c026d7dbcdf65ca5c7991eeb561ab35b40b02e98aa24dd984fd7871da8c4906ccc1aa64f9b8c2d8ad86aded199b
-  data.tar.gz: 4463963285c39c09e2d1d090fe0f80518107b7b60fdb58a0bd993d11dfbaf64e0131cd774b16483d6bd84b5a7faf4256eb8304c3bf4b08b4b90dadfaa513adb9
+  metadata.gz: a10dcafb4ff9e9655e06e149ae83a872a0b614f44d69db15ed120f6aa6990f858bb94897d7b8fe30c1b41fe74dc71f054bdf7f0387ded0c0b66058d0d9a15492
+  data.tar.gz: 87be0dc85c2fc044a0f95096d147dbc79dda101babad85bfdfd29a37c42cd9cb70180fdedae00ff95321fe6eec0e4d61a6aaab852c9c6d3f10fc39ff7f06d87c

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [1.20.0] - 2024-02-05
+
+### Added
+
+* Tracing: Add `Trilogy` instrumentation ([#3274][])
+* Rack: Add remote configuration boot tags ([#3315][])
+* Faraday: Add `on_error` option ([#3431][])
+* Profiling: Add dynamic allocation sampling ([#3395][])
+
+### Changed
+
+* Bump `datadog-ci` dependency to 0.7.0 ([#3408][])
+* Improve performance of gathering ClassCount metric ([#3386][])
+
+### Fixed
+
+* OpenTelemetry: Fix internal loading ([#3400][])
+* Core: Fix logger deadlock ([#3426][])
+* Rack: Fix missing active trace ([#3420][])
+* Redis: Fix instance configuration ([#3278][])
+
 ## [1.19.0] - 2024-01-10
 
 ### Highlights
@@ -2707,7 +2728,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/v1.19.0...master
+[Unreleased]: https://github.com/DataDog/dd-trace-rb/compare/v1.20.0...master
+[1.20.0]: https://github.com/DataDog/dd-trace-rb/compare/v1.19.0...v1.20.0
 [1.19.0]: https://github.com/DataDog/dd-trace-rb/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/DataDog/dd-trace-rb/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/DataDog/dd-trace-rb/compare/v1.16.2...v1.17.0
@@ -3936,6 +3958,8 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [#3270]: https://github.com/DataDog/dd-trace-rb/issues/3270
 [#3271]: https://github.com/DataDog/dd-trace-rb/issues/3271
 [#3273]: https://github.com/DataDog/dd-trace-rb/issues/3273
+[#3274]: https://github.com/DataDog/dd-trace-rb/issues/3274
+[#3278]: https://github.com/DataDog/dd-trace-rb/issues/3278
 [#3279]: https://github.com/DataDog/dd-trace-rb/issues/3279
 [#3280]: https://github.com/DataDog/dd-trace-rb/issues/3280
 [#3281]: https://github.com/DataDog/dd-trace-rb/issues/3281
@@ -3948,6 +3972,7 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [#3308]: https://github.com/DataDog/dd-trace-rb/issues/3308
 [#3310]: https://github.com/DataDog/dd-trace-rb/issues/3310
 [#3313]: https://github.com/DataDog/dd-trace-rb/issues/3313
+[#3315]: https://github.com/DataDog/dd-trace-rb/issues/3315
 [#3316]: https://github.com/DataDog/dd-trace-rb/issues/3316
 [#3317]: https://github.com/DataDog/dd-trace-rb/issues/3317
 [#3320]: https://github.com/DataDog/dd-trace-rb/issues/3320
@@ -3965,6 +3990,13 @@ Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 [#3366]: https://github.com/DataDog/dd-trace-rb/issues/3366
 [#3373]: https://github.com/DataDog/dd-trace-rb/issues/3373
 [#3374]: https://github.com/DataDog/dd-trace-rb/issues/3374
+[#3386]: https://github.com/DataDog/dd-trace-rb/issues/3386
+[#3395]: https://github.com/DataDog/dd-trace-rb/issues/3395
+[#3400]: https://github.com/DataDog/dd-trace-rb/issues/3400
+[#3408]: https://github.com/DataDog/dd-trace-rb/issues/3408
+[#3420]: https://github.com/DataDog/dd-trace-rb/issues/3420
+[#3426]: https://github.com/DataDog/dd-trace-rb/issues/3426
+[#3431]: https://github.com/DataDog/dd-trace-rb/issues/3431
 [@AdrianLC]: https://github.com/AdrianLC
 [@Azure7111]: https://github.com/Azure7111
 [@BabyGroot]: https://github.com/BabyGroot

data/ext/ddtrace_profiling_native_extension/collectors_cpu_and_wall_time_worker.c

@@ -12,10 +12,14 @@
 #include "collectors_thread_context.h"
 #include "collectors_dynamic_sampling_rate.h"
 #include "collectors_idle_sampling_helper.h"
+#include "collectors_discrete_dynamic_sampler.h"
 #include "private_vm_api_access.h"
 #include "setup_signal_handler.h"
 #include "time_helpers.h"
 
+// Maximum allowed value for an allocation weight. Attempts to use higher values will result in clamping.
+unsigned int MAX_ALLOC_WEIGHT = 65535;
+
 // Used to trigger the execution of Collectors::ThreadState, which implements all of the sampling logic
 // itself; this class only implements the "when to do it" part.
 //
@@ -89,13 +93,13 @@ struct cpu_and_wall_time_worker_state {
   bool gc_profiling_enabled;
   bool no_signals_workaround_enabled;
   bool dynamic_sampling_rate_enabled;
-  int allocation_sample_every;
   bool allocation_profiling_enabled;
   VALUE self_instance;
   VALUE thread_context_collector_instance;
   VALUE idle_sampling_helper_instance;
   VALUE owner_thread;
-  dynamic_sampling_rate_state dynamic_sampling_rate;
+  dynamic_sampling_rate_state cpu_dynamic_sampling_rate;
+  discrete_dynamic_sampler allocation_sampler;
   VALUE gc_tracepoint; // Used to get gc start/finish information
   VALUE object_allocation_tracepoint; // Used to get allocation counts and allocation profiling
 
@@ -159,7 +163,6 @@ static VALUE _native_initialize(
   VALUE no_signals_workaround_enabled,
   VALUE dynamic_sampling_rate_enabled,
   VALUE dynamic_sampling_rate_overhead_target_percentage,
-  VALUE allocation_sample_every,
   VALUE allocation_profiling_enabled
 );
 static void cpu_and_wall_time_worker_typed_data_mark(void *state_ptr);
@@ -244,7 +247,7 @@ void collectors_cpu_and_wall_time_worker_init(VALUE profiling_module) {
   // https://bugs.ruby-lang.org/issues/18007 for a discussion around this.
   rb_define_alloc_func(collectors_cpu_and_wall_time_worker_class, _native_new);
 
-  rb_define_singleton_method(collectors_cpu_and_wall_time_worker_class, "_native_initialize", _native_initialize, 9);
+  rb_define_singleton_method(collectors_cpu_and_wall_time_worker_class, "_native_initialize", _native_initialize, 8);
   rb_define_singleton_method(collectors_cpu_and_wall_time_worker_class, "_native_sampling_loop", _native_sampling_loop, 1);
   rb_define_singleton_method(collectors_cpu_and_wall_time_worker_class, "_native_stop", _native_stop, 2);
   rb_define_singleton_method(collectors_cpu_and_wall_time_worker_class, "_native_reset_after_fork", _native_reset_after_fork, 1);
@@ -284,12 +287,12 @@ static VALUE _native_new(VALUE klass) {
   state->gc_profiling_enabled = false;
   state->no_signals_workaround_enabled = false;
   state->dynamic_sampling_rate_enabled = true;
-  state->allocation_sample_every = 0;
   state->allocation_profiling_enabled = false;
   state->thread_context_collector_instance = Qnil;
   state->idle_sampling_helper_instance = Qnil;
   state->owner_thread = Qnil;
-  dynamic_sampling_rate_init(&state->dynamic_sampling_rate);
+  dynamic_sampling_rate_init(&state->cpu_dynamic_sampling_rate);
+  discrete_dynamic_sampler_init(&state->allocation_sampler, "allocation");
   state->gc_tracepoint = Qnil;
   state->object_allocation_tracepoint = Qnil;
 
@@ -313,13 +316,11 @@ static VALUE _native_initialize(
   VALUE no_signals_workaround_enabled,
   VALUE dynamic_sampling_rate_enabled,
   VALUE dynamic_sampling_rate_overhead_target_percentage,
-  VALUE allocation_sample_every,
   VALUE allocation_profiling_enabled
 ) {
   ENFORCE_BOOLEAN(gc_profiling_enabled);
   ENFORCE_BOOLEAN(no_signals_workaround_enabled);
   ENFORCE_BOOLEAN(dynamic_sampling_rate_enabled);
-  ENFORCE_TYPE(allocation_sample_every, T_FIXNUM);
   ENFORCE_TYPE(dynamic_sampling_rate_overhead_target_percentage, T_FLOAT);
   ENFORCE_BOOLEAN(allocation_profiling_enabled);
 
@@ -329,12 +330,16 @@ static VALUE _native_initialize(
   state->gc_profiling_enabled = (gc_profiling_enabled == Qtrue);
   state->no_signals_workaround_enabled = (no_signals_workaround_enabled == Qtrue);
   state->dynamic_sampling_rate_enabled = (dynamic_sampling_rate_enabled == Qtrue);
-  dynamic_sampling_rate_set_overhead_target_percentage(&state->dynamic_sampling_rate, NUM2DBL(dynamic_sampling_rate_overhead_target_percentage));
-  state->allocation_sample_every = NUM2INT(allocation_sample_every);
   state->allocation_profiling_enabled = (allocation_profiling_enabled == Qtrue);
 
-  if (state->allocation_sample_every <= 0) {
-    rb_raise(rb_eArgError, "Unexpected value for allocation_sample_every: %d. This value must be > 0.", state->allocation_sample_every);
+  double total_overhead_target_percentage = NUM2DBL(dynamic_sampling_rate_overhead_target_percentage);
+  if (!state->allocation_profiling_enabled) {
+    dynamic_sampling_rate_set_overhead_target_percentage(&state->cpu_dynamic_sampling_rate, total_overhead_target_percentage);
+  } else {
+    // TODO: May be nice to offer customization here? Distribute available "overhead" margin with a bias towards one or the other
+    // sampler.
+    dynamic_sampling_rate_set_overhead_target_percentage(&state->cpu_dynamic_sampling_rate, total_overhead_target_percentage / 2);
+    discrete_dynamic_sampler_set_overhead_target_percentage(&state->allocation_sampler, total_overhead_target_percentage / 2);
   }
 
   state->thread_context_collector_instance = enforce_thread_context_collector_instance(thread_context_collector_instance);
@@ -387,7 +392,8 @@ static VALUE _native_sampling_loop(DDTRACE_UNUSED VALUE _self, VALUE instance) {
   if (state->stop_thread == rb_thread_current()) return Qnil;
 
   // Reset the dynamic sampling rate state, if any (reminder: the monotonic clock reference may change after a fork)
-  dynamic_sampling_rate_reset(&state->dynamic_sampling_rate);
+  dynamic_sampling_rate_reset(&state->cpu_dynamic_sampling_rate);
+  discrete_dynamic_sampler_reset(&state->allocation_sampler);
 
   // This write to a global is thread-safe BECAUSE we're still holding on to the global VM lock at this point
   active_sampler_instance_state = state;
@@ -560,7 +566,7 @@ static void *run_sampling_trigger_loop(void *state_ptr) {
     // Note that we deliberately should NOT combine this sleep_for with the one above because the result of
     // `dynamic_sampling_rate_get_sleep` may have changed while the above sleep was ongoing.
     uint64_t extra_sleep =
-      dynamic_sampling_rate_get_sleep(&state->dynamic_sampling_rate, monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE));
+      dynamic_sampling_rate_get_sleep(&state->cpu_dynamic_sampling_rate, monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE));
     if (state->dynamic_sampling_rate_enabled && extra_sleep > 0) sleep_for(extra_sleep);
   }
 
@@ -600,7 +606,7 @@ static VALUE rescued_sample_from_postponed_job(VALUE self_instance) {
 
   long wall_time_ns_before_sample = monotonic_wall_time_now_ns(RAISE_ON_FAILURE);
 
-  if (state->dynamic_sampling_rate_enabled && !dynamic_sampling_rate_should_sample(&state->dynamic_sampling_rate, wall_time_ns_before_sample)) {
+  if (state->dynamic_sampling_rate_enabled && !dynamic_sampling_rate_should_sample(&state->cpu_dynamic_sampling_rate, wall_time_ns_before_sample)) {
     state->stats.skipped_sample_because_of_dynamic_sampling_rate++;
     return Qnil;
   }
@@ -620,7 +626,7 @@ static VALUE rescued_sample_from_postponed_job(VALUE self_instance) {
   state->stats.sampling_time_ns_max = uint64_max_of(sampling_time_ns, state->stats.sampling_time_ns_max);
   state->stats.sampling_time_ns_total += sampling_time_ns;
 
-  dynamic_sampling_rate_after_sample(&state->dynamic_sampling_rate, wall_time_ns_after_sample, sampling_time_ns);
+  dynamic_sampling_rate_after_sample(&state->cpu_dynamic_sampling_rate, wall_time_ns_after_sample, sampling_time_ns);
 
   // Return a dummy VALUE because we're called from rb_rescue2 which requires it
   return Qnil;
@@ -931,18 +937,20 @@ static void on_newobj_event(VALUE tracepoint_data, DDTRACE_UNUSED void *unused)
     return;
   }
 
+  if (state->dynamic_sampling_rate_enabled && !discrete_dynamic_sampler_should_sample(&state->allocation_sampler)) {
+    return;
+  }
+
   // @ivoanjo: Strictly speaking, this is not needed because Ruby should not call the same tracepoint while a previous
   // invocation is still pending, (e.g. it wouldn't call `on_newobj_event` while it's already running), but I decided
   // to keep this here for consistency -- every call to the thread context (other than the special gc calls which are
   // defined as not being able to allocate) sets this.
   state->during_sample = true;
 
-  // TODO: This is a placeholder sampling decision strategy. We plan to replace it with a better one soon (e.g. before
-  // beta), and having something here allows us to test the rest of feature, sampling decision aside.
-  if (allocation_count % state->allocation_sample_every == 0) {
-    // Rescue against any exceptions that happen during sampling
-    safely_call(rescued_sample_allocation, tracepoint_data, state->self_instance);
-  }
+  // Rescue against any exceptions that happen during sampling
+  safely_call(rescued_sample_allocation, tracepoint_data, state->self_instance);
+
+  discrete_dynamic_sampler_after_sample(&state->allocation_sampler);
 
   state->during_sample = false;
 }
@@ -974,7 +982,14 @@ static VALUE rescued_sample_allocation(VALUE tracepoint_data) {
   rb_trace_arg_t *data = rb_tracearg_from_tracepoint(tracepoint_data);
   VALUE new_object = rb_tracearg_object(data);
 
-  thread_context_collector_sample_allocation(state->thread_context_collector_instance, state->allocation_sample_every, new_object);
+  unsigned long allocations_since_last_sample = state->dynamic_sampling_rate_enabled ?
+    // if we're doing dynamic sampling, ask the sampler how many events since last sample
+    discrete_dynamic_sampler_events_since_last_sample(&state->allocation_sampler) :
+    // if we aren't, then we're sampling every event
+    1;
+  // TODO: Signal in the profile that clamping happened?
+  unsigned int weight = allocations_since_last_sample > MAX_ALLOC_WEIGHT ? MAX_ALLOC_WEIGHT : (unsigned int) allocations_since_last_sample;
+  thread_context_collector_sample_allocation(state->thread_context_collector_instance, weight, new_object);
 
   // Return a dummy VALUE because we're called from rb_rescue2 which requires it
   return Qnil;

data/ext/ddtrace_profiling_native_extension/collectors_discrete_dynamic_sampler.c

@@ -0,0 +1,349 @@
+#include "collectors_discrete_dynamic_sampler.h"
+
+#include <ruby.h>
+#include "helpers.h"
+#include "time_helpers.h"
+#include "ruby_helpers.h"
+
+#define BASE_OVERHEAD_PCT 1.0
+#define BASE_SAMPLING_INTERVAL 50
+
+#define ADJUSTMENT_WINDOW_NS SECONDS_AS_NS(1)
+
+#define EMA_SMOOTHING_FACTOR 0.6
+#define EXP_MOVING_AVERAGE(last, avg, first) first ? last : (1-EMA_SMOOTHING_FACTOR) * avg + EMA_SMOOTHING_FACTOR * last
+
+void discrete_dynamic_sampler_init(discrete_dynamic_sampler *sampler, const char *debug_name) {
+  sampler->debug_name = debug_name;
+  discrete_dynamic_sampler_set_overhead_target_percentage(sampler, BASE_OVERHEAD_PCT);
+}
+
+static void _discrete_dynamic_sampler_reset(discrete_dynamic_sampler *sampler, long now_ns) {
+  const char *debug_name = sampler->debug_name;
+  double target_overhead = sampler->target_overhead;
+  (*sampler) = (discrete_dynamic_sampler) {
+    .debug_name = debug_name,
+    .target_overhead = target_overhead,
+    // Act as if a reset is a readjustment (it kinda is!) and wait for a full adjustment window
+    // to compute stats. Otherwise, we'd readjust on the next event that comes and thus be operating
+    // with very incomplete information
+    .last_readjust_time_ns = now_ns,
+    // This fake readjustment will use a hardcoded sampling interval
+    .sampling_interval = BASE_SAMPLING_INTERVAL,
+    .sampling_probability = 1.0 / BASE_SAMPLING_INTERVAL,
+    // But we want to make sure we sample at least once in the next window so that our first
+    // real readjustment has some notion of how heavy sampling is. Therefore, we'll make it so that
+    // the next event is automatically sampled by artificially locating it in the interval threshold.
+    .events_since_last_sample = BASE_SAMPLING_INTERVAL - 1,
+  };
+}
+
+void discrete_dynamic_sampler_reset(discrete_dynamic_sampler *sampler) {
+  long now = monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE);
+  _discrete_dynamic_sampler_reset(sampler, now);
+}
+
+static void _discrete_dynamic_sampler_set_overhead_target_percentage(discrete_dynamic_sampler *sampler, double target_overhead, long now_ns) {
+  if (target_overhead <= 0 || target_overhead > 100) {
+    rb_raise(rb_eArgError, "Target overhead must be a double between ]0,100] was %f", target_overhead);
+  }
+  sampler->target_overhead = target_overhead;
+  _discrete_dynamic_sampler_reset(sampler, now_ns);
+}
+
+void discrete_dynamic_sampler_set_overhead_target_percentage(discrete_dynamic_sampler *sampler, double target_overhead) {
+  long now = monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE);
+  _discrete_dynamic_sampler_set_overhead_target_percentage(sampler, target_overhead, now);
+}
+
+static void maybe_readjust(discrete_dynamic_sampler *sampler, long now);
+
+static bool _discrete_dynamic_sampler_should_sample(discrete_dynamic_sampler *sampler, long now_ns) {
+  // For efficiency reasons we don't do true random sampling but rather systematic
+  // sampling following a sample interval/skip. This can be biased and hide patterns
+  // but the dynamic interval and rather indeterministic pattern of allocations in
+  // most real applications should help reduce the bias impact.
+  sampler->events_since_last_sample++;
+  sampler->events_since_last_readjustment++;
+  bool should_sample = sampler->sampling_interval > 0 && sampler->events_since_last_sample >= sampler->sampling_interval;
+
+  if (should_sample) {
+    sampler->sample_start_time_ns = now_ns;
+  } else {
+    // check if we should readjust our sampler after this event, even if we didn't sample it
+    maybe_readjust(sampler, now_ns);
+  }
+
+  return should_sample;
+}
+
+bool discrete_dynamic_sampler_should_sample(discrete_dynamic_sampler *sampler) {
+  long now = monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE);
+  return _discrete_dynamic_sampler_should_sample(sampler, now);
+}
+
+static long _discrete_dynamic_sampler_after_sample(discrete_dynamic_sampler *sampler, long now_ns) {
+  long last_sampling_time_ns = sampler->sample_start_time_ns == 0 ? 0 : long_max_of(0, now_ns - sampler->sample_start_time_ns);
+  sampler->samples_since_last_readjustment++;
+  sampler->sampling_time_since_last_readjustment_ns += last_sampling_time_ns;
+  sampler->events_since_last_sample = 0;
+
+  // check if we should readjust our sampler after this sample
+  maybe_readjust(sampler, now_ns);
+
+  return last_sampling_time_ns;
+}
+
+long discrete_dynamic_sampler_after_sample(discrete_dynamic_sampler *sampler) {
+  long now = monotonic_wall_time_now_ns(DO_NOT_RAISE_ON_FAILURE);
+  return _discrete_dynamic_sampler_after_sample(sampler, now);
+}
+
+double discrete_dynamic_sampler_probability(discrete_dynamic_sampler *sampler) {
+  return sampler->sampling_probability * 100.;
+}
+
+size_t discrete_dynamic_sampler_events_since_last_sample(discrete_dynamic_sampler *sampler) {
+  return sampler->events_since_last_sample;
+}
+
+static void maybe_readjust(discrete_dynamic_sampler *sampler, long now) {
+  long window_time_ns = sampler->last_readjust_time_ns == 0 ? ADJUSTMENT_WINDOW_NS : now - sampler->last_readjust_time_ns;
+
+  if (window_time_ns < ADJUSTMENT_WINDOW_NS) {
+    // not enough time has passed to perform a readjustment
+    return;
+  }
+
+  // If we got this far, lets recalculate our sampling params based on new observations
+  bool first_readjustment = !sampler->has_completed_full_adjustment_window;
+
+  // Update our running average of events/sec with latest observation
+  sampler->events_per_ns = EXP_MOVING_AVERAGE(
+    (double) sampler->events_since_last_readjustment / window_time_ns,
+    sampler->events_per_ns,
+    first_readjustment
+  );
+
+  // Update our running average of sampling time for a specific event
+  long sampling_window_time_ns = sampler->sampling_time_since_last_readjustment_ns;
+  long sampling_overshoot_time_ns = -1;
+  if (sampler->samples_since_last_readjustment > 0) {
+    // We can only update sampling-related stats if we actually sampled on the last window...
+
+    // Lets update our average sampling time per event
+    long avg_sampling_time_in_window_ns = sampler->samples_since_last_readjustment == 0 ? 0 : sampling_window_time_ns / sampler->samples_since_last_readjustment;
+    sampler->sampling_time_ns = EXP_MOVING_AVERAGE(
+      avg_sampling_time_in_window_ns,
+      sampler->sampling_time_ns,
+      first_readjustment
+    );
+  }
+
+  // Are we meeting our target in practice? If we're consistently overshooting our estimate due to non-uniform allocation patterns lets
+  // adjust our overhead target.
+  // NOTE: Updating this even when no samples occur is a conscious choice which enables us to cooldown extreme adjustments over time.
+  //       If we didn't do this, whenever a big spike caused target_overhead_adjustment to equal target_overhead, we'd get stuck
+  //       in a "probability = 0" state.
+  long reference_target_sampling_time_ns = window_time_ns * (sampler->target_overhead / 100.);
+  // Overshoot by definition is always >= 0. < 0 would be undershooting!
+  sampling_overshoot_time_ns = long_max_of(0, sampler->sampling_time_since_last_readjustment_ns - reference_target_sampling_time_ns);
+  // Our overhead adjustment should always be between [-target_overhead, 0]. Higher adjustments would lead to negative overhead targets
+  // which don't make much sense.
+  double last_target_overhead_adjustment = -double_min_of(sampler->target_overhead, sampling_overshoot_time_ns * 100. / window_time_ns);
+  sampler->target_overhead_adjustment = EXP_MOVING_AVERAGE(
+    last_target_overhead_adjustment,
+    sampler->target_overhead_adjustment,
+    first_readjustment
+  );
+
+  // Apply our overhead adjustment to figure out our real targets for this readjustment.
+  double target_overhead = double_max_of(0, sampler->target_overhead + sampler->target_overhead_adjustment);
+  long target_sampling_time_ns = window_time_ns * (target_overhead / 100.);
+
+  // Recalculate target sampling probability so that the following 2 hold:
+  // * window_time_ns = working_window_time_ns + sampling_window_time_ns
+  //       │                     │                        │
+  //       │                     │                        └ how much time is spent sampling
+  //       │                     └── how much time is spent doing actual app stuff
+  //       └── total (wall) time in this adjustment window
+  // * sampling_window_time_ns <= window_time_ns * target_overhead / 100
+  //
+  // Note that
+  //
+  //   sampling_window_time_ns = samples_in_window * sampling_time_ns =
+  //                                                ┌─ assuming no events will be emitted during sampling
+  //                                                │
+  //                           = events_per_ns * working_window_time_ns * sampling_probability * sampling_time_ns
+  //
+  // Re-ordering for sampling_probability and solving for the upper-bound of sampling_window_time_ns:
+  //
+  //   sampling_window_time_ns = window_time_ns * target_overhead / 100
+  //   sampling_probability = window_time_ns * target_overhead / 100 / (events_per_ns * working_window_time_ns * sampling_time_ns) =
+  //
+  // Which you can intuitively understand as:
+  //
+  //   sampling_probability = max_allowed_time_for_sampling_ns / time_to_sample_all_events_ns
+  //
+  // As a quick sanity check:
+  // * If app is eventing very little or we're sampling very fast, so that time_to_sample_all_events_ns < max_allowed_time_for_sampling_ns
+  //   then probability will be > 1 (but we should clamp to 1 since probabilities higher than 1 don't make sense).
+  // * If app is eventing a lot or our sampling overhead is big, then as time_to_sample_all_events_ns grows, sampling_probability will
+  //   tend to 0.
+  long working_window_time_ns = long_max_of(0, window_time_ns - sampling_window_time_ns);
+  double max_allowed_time_for_sampling_ns = target_sampling_time_ns;
+  long time_to_sample_all_events_ns = sampler->events_per_ns * working_window_time_ns * sampler->sampling_time_ns;
+  if (max_allowed_time_for_sampling_ns == 0) {
+    // if we aren't allowed any sampling time at all, probability has to be 0
+    sampler->sampling_probability = 0;
+  } else {
+    // otherwise apply the formula described above (protecting against div by 0)
+    sampler->sampling_probability = time_to_sample_all_events_ns == 0 ? 1. :
+      double_min_of(1., max_allowed_time_for_sampling_ns / time_to_sample_all_events_ns);
+  }
+
+  // Doing true random selection would involve "tossing a coin" on every allocation. Lets do systematic sampling instead so that our
+  // sampling decision can rely solely on a sampling skip/interval (i.e. more efficient).
+  //
+  //   sampling_interval = events / samples =
+  //                     = event_rate * working_window_time_ns / (event_rate * working_window_time_ns * sampling_probability)
+  //                     = 1 / sampling_probability
+  //
+  // NOTE: The sampling interval has to be an integer since we're dealing with discrete events here. This means that there'll be
+  //       a loss of precision (and thus control) when adjusting between probabilities that lead to non-integer granularity
+  //       changes (e.g. probabilities in the range of ]50%, 100%[ which map to intervals in the range of ]1, 2[). Our approach
+  //       when the sampling interval is a non-integer is to ceil it (i.e. we'll always choose to sample less often).
+  // NOTE: Overhead target adjustments or very big sampling times can in theory bring probability so close to 0 as to effectively
+  //       round down to full 0. This means we have to be careful to handle div-by-0 as well as resulting double intervals that
+  //       are so big they don't fit into the sampling_interval. In both cases lets just disable sampling until next readjustment
+  //       by setting interval to 0.
+  double sampling_interval = sampler->sampling_probability == 0 ? 0 : ceil(1.0 / sampler->sampling_probability);
+  sampler->sampling_interval = sampling_interval > ULONG_MAX ? 0 : sampling_interval;
+
+  #ifdef DD_DEBUG
+    double allocs_in_60s = sampler->events_per_ns * 1e9 * 60;
+    double samples_in_60s = allocs_in_60s * sampler->sampling_probability;
+    double expected_total_sampling_time_in_60s =
+      samples_in_60s * sampler->sampling_time_ns / 1e9;
+    double real_total_sampling_time_in_60s = sampling_window_time_ns / 1e9 * 60 / (window_time_ns / 1e9);
+
+    fprintf(stderr, "[dds.%s] readjusting...\n", sampler->debug_name);
+    fprintf(stderr, "samples_since_last_readjustment=%ld\n", sampler->samples_since_last_readjustment);
+    fprintf(stderr, "window_time=%ld\n", window_time_ns);
+    fprintf(stderr, "events_per_sec=%f\n", sampler->events_per_ns * 1e9);
+    fprintf(stderr, "sampling_time=%ld\n", sampler->sampling_time_ns);
+    fprintf(stderr, "sampling_window_time=%ld\n", sampling_window_time_ns);
+    fprintf(stderr, "sampling_target_time=%ld\n", reference_target_sampling_time_ns);
+    fprintf(stderr, "sampling_overshoot_time=%ld\n", sampling_overshoot_time_ns);
+    fprintf(stderr, "working_window_time=%ld\n", working_window_time_ns);
+    fprintf(stderr, "sampling_interval=%zu\n", sampler->sampling_interval);
+    fprintf(stderr, "sampling_probability=%f\n", sampler->sampling_probability);
+    fprintf(stderr, "expected allocs in 60s=%f\n", allocs_in_60s);
+    fprintf(stderr, "expected samples in 60s=%f\n", samples_in_60s);
+    fprintf(stderr, "expected sampling time in 60s=%f (previous real=%f)\n", expected_total_sampling_time_in_60s, real_total_sampling_time_in_60s);
+    fprintf(stderr, "target_overhead=%f\n", sampler->target_overhead);
+    fprintf(stderr, "target_overhead_adjustment=%f\n", sampler->target_overhead_adjustment);
+    fprintf(stderr, "target_sampling_time=%ld\n", target_sampling_time_ns);
+    fprintf(stderr, "expected max overhead in 60s=%f\n", target_overhead / 100.0 * 60);
+    fprintf(stderr, "-------\n");
+  #endif
+
+  sampler->events_since_last_readjustment = 0;
+  sampler->samples_since_last_readjustment = 0;
+  sampler->sampling_time_since_last_readjustment_ns = 0;
+  sampler->last_readjust_time_ns = now;
+  sampler->has_completed_full_adjustment_window = true;
+}
+
+// ---
+// Below here is boilerplate to expose the above code to Ruby so that we can test it with RSpec as usual.
+
+static VALUE _native_new(VALUE klass);
+static VALUE _native_reset(VALUE self, VALUE now);
+static VALUE _native_set_overhead_target_percentage(VALUE self, VALUE target_overhead, VALUE now);
+static VALUE _native_should_sample(VALUE self, VALUE now);
+static VALUE _native_after_sample(VALUE self, VALUE now);
+static VALUE _native_probability(VALUE self);
+
+typedef struct sampler_state {
+  discrete_dynamic_sampler sampler;
+} sampler_state;
+
+void collectors_discrete_dynamic_sampler_init(VALUE profiling_module) {
+  VALUE collectors_module = rb_define_module_under(profiling_module, "Collectors");
+  VALUE discrete_sampler_module = rb_define_module_under(collectors_module, "DiscreteDynamicSampler");
+  VALUE testing_module = rb_define_module_under(discrete_sampler_module, "Testing");
+  VALUE sampler_class = rb_define_class_under(testing_module, "Sampler", rb_cObject);
+
+  rb_define_alloc_func(sampler_class, _native_new);
+
+  rb_define_method(sampler_class, "_native_reset", _native_reset, 1);
+  rb_define_method(sampler_class, "_native_set_overhead_target_percentage", _native_set_overhead_target_percentage, 2);
+  rb_define_method(sampler_class, "_native_should_sample", _native_should_sample, 1);
+  rb_define_method(sampler_class, "_native_after_sample", _native_after_sample, 1);
+  rb_define_method(sampler_class, "_native_probability", _native_probability, 0);
+}
+
+static const rb_data_type_t sampler_typed_data = {
+  .wrap_struct_name = "Datadog::Profiling::DiscreteDynamicSampler::Testing::Sampler",
+  .function = {
+    .dfree = RUBY_DEFAULT_FREE,
+    .dsize = NULL,
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE _native_new(VALUE klass) {
+  sampler_state *state = ruby_xcalloc(sizeof(sampler_state), 1);
+
+  discrete_dynamic_sampler_init(&state->sampler, "test sampler");
+
+  return TypedData_Wrap_Struct(klass, &sampler_typed_data, state);
+}
+
+static VALUE _native_reset(VALUE self, VALUE now_ns) {
+  ENFORCE_TYPE(now_ns, T_FIXNUM);
+
+  sampler_state *state;
+  TypedData_Get_Struct(self, sampler_state, &sampler_typed_data, state);
+
+  _discrete_dynamic_sampler_reset(&state->sampler, NUM2LONG(now_ns));
+  return Qtrue;
+}
+
+static VALUE _native_set_overhead_target_percentage(VALUE self, VALUE target_overhead, VALUE now_ns) {
+  ENFORCE_TYPE(target_overhead, T_FLOAT);
+  ENFORCE_TYPE(now_ns, T_FIXNUM);
+
+  sampler_state *state;
+  TypedData_Get_Struct(self, sampler_state, &sampler_typed_data, state);
+
+  _discrete_dynamic_sampler_set_overhead_target_percentage(&state->sampler, NUM2DBL(target_overhead), NUM2LONG(now_ns));
+
+  return Qnil;
+}
+
+VALUE _native_should_sample(VALUE self, VALUE now_ns) {
+  ENFORCE_TYPE(now_ns, T_FIXNUM);
+
+  sampler_state *state;
+  TypedData_Get_Struct(self, sampler_state, &sampler_typed_data, state);
+
+  return _discrete_dynamic_sampler_should_sample(&state->sampler, NUM2LONG(now_ns)) ? Qtrue : Qfalse;
+}
+
+VALUE _native_after_sample(VALUE self, VALUE now_ns) {
+  ENFORCE_TYPE(now_ns, T_FIXNUM);
+
+  sampler_state *state;
+  TypedData_Get_Struct(self, sampler_state, &sampler_typed_data, state);
+
+  return LONG2NUM(_discrete_dynamic_sampler_after_sample(&state->sampler, NUM2LONG(now_ns)));
+}
+
+VALUE _native_probability(VALUE self) {
+  sampler_state *state;
+  TypedData_Get_Struct(self, sampler_state, &sampler_typed_data, state);
+
+  return DBL2NUM(discrete_dynamic_sampler_probability(&state->sampler));
+}