ddtrace 0.42.0 → 0.54.2

data/docs/ProfilingDevelopment.md

@@ -0,0 +1,107 @@
+# Profiling Development
+
+This file contains development notes specific to the profiling feature.
+
+For a more practical view of getting started with development of `ddtrace`, see <DevelopmentGuide.md>.
+
+## Profiling components high-level view
+
+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`: 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
+  profiling abilities after the VM forks (such as re-instrumenting the main thread, and restarting profiler threads).
+* `Pprof::*` (in <../lib/ddtrace/profiling/pprof>): Converts samples captured in the `Recorder` into the pprof format.
+* `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.
+* `Flush`: Entity class used to represent metadata for a given profile.
+* `Profiler`: Profiling entry point, which coordinates collectors and a scheduler.
+* `Recorder`: Stores profiling events gathered by `Collector`s.
+* `Scheduler`: Periodically (every 1 minute) takes data from the `Recorder` and pushes them to all configured
+  `Exporter`s. Runs on its own background thread.
+
+## Initialization
+
+When started via `ddtracerb exec` (together with `DD_PROFILING_ENABLED=true`), initialization goes through the following
+flow:
+
+1. <../lib/ddtrace/profiling/preload.rb> triggers the creation of the `Datadog.profiler` instance by calling the method
+2. `Datadog.profiler` is handled by `Datadog::Configuration`, which triggers the configuration of `ddtrace` components
+   in `#build_components`
+3. Inside `Datadog::Components`, the `build_profiler` method triggers the execution of the `Tasks::Setup`
+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 as such:
+    ```asciiflow
+            +------------+
+            |  Profiler  |
+            +-+-------+--+
+              |       |
+              v       v
+    +---------+--+  +-+---------+
+    | Collectors |  | Scheduler |
+    +---------+--+  +-+-------+-+
+              |       |       |
+              v       |       v
+        +-----+-+     |  +----+------+
+        | Stack |     |  | Exporters |
+        +-----+-+     |  +-----------+
+              |       |
+              v       v
+            +-+-------+-+
+            | Recorder  |
+            +-----------+
+    ```
+6. The profiler gets started when `startup!` is called by `Datadog::Configuration` after component creation.
+
+## Run-time execution
+
+During run-time, the `Scheduler` and the `Collectors::Stack` each execute on their own background thread.
+
+The `Collectors::Stack` samples stack traces of threads, capturing both CPU-time (if available) and wall-clock, storing
+them in the `Recorder`.
+
+The `Scheduler` wakes up every 1 minute to flush the results of the `Recorder` into one or more `exporter`s.
+Usually only one exporter is in use. By default, the `Exporter` delegates to the default `Transport::HTTP` transport, which
+takes care of encoding the data and reporting it to the datadog agent (or to the API, when running without an agent).
+
+## 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 `local root span id` and `span id` for the given trace/span.
+
+This is done using the `Datadog::Profiling::TraceIdentifiers::Helper` that retrieves a `root_span_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.

data/ext/ddtrace_profiling_native_extension/NativeExtensionDesign.md

@@ -0,0 +1,86 @@
+# Profiling Native Extension Design
+
+The profiling native extension is used to implement features which are expensive (in terms of resources) or otherwise
+impossible to implement using Ruby code.
+
+This extension is quite coupled with MRI Ruby ("C Ruby") internals, and is not intended to support other rubies such as
+JRuby or TruffleRuby. When below we say "Ruby", read it as "MRI Ruby".
+
+## Disabling
+
+The profiling native extension can be disabled by setting `DD_PROFILING_NO_EXTENSION=true` when installing or running
+the gem. Setting `DD_PROFILING_NO_EXTENSION` at installation time skips compilation of the extension entirely.
+
+(If you're a customer and needed to use this, please tell us why on <https://github.com/DataDog/dd-trace-rb/issues/new>.)
+
+Currently the profiler can still "limp along" when the native extension is disabled, but the plan is to require it
+in future releases -- e.g. disabling the extension will disable profiling entirely.
+
+## Safety
+
+The profiling native extension is (and must always be) designed to **not cause failures** during gem installation, even
+if some features, Ruby versions, or operating systems are not supported.
+
+E.g. the extension must cleanly build on Ruby 2.1 (or the oldest Ruby version we support at the time) on Windows,
+even if at run time it will effectively do nothing for such a setup.
+
+We have a CI setup to help validate this, but this is really important to keep in mind when adding to or changing the
+existing codebase.
+
+## Usage of private VM headers
+
+To implement some of the features below, we sometimes require access to private Ruby header files (that describe VM
+internal types, structures and functions).
+
+Because these private header files are not included in regular Ruby installations, we have two different workarounds:
+
+1. for Ruby versions >= 2.6 we make use use the Ruby private MJIT header
+2. for Ruby versions < 2.6 (legacy Rubies) we make use of the `debase-ruby_core_source` gem
+
+Functions which make use of these headers are defined in the <private_vm_api_acccess.c> file.
+
+**Important Note**: Our medium/long-term plan is to stop relying on all private Ruby headers, and instead request and
+contribute upstream changes so that they become official public VM APIs.
+
+### Approach 1: Using the Ruby private MJIT header
+
+Ruby versions >= 2.6 introduced a JIT compiler called MJIT. This compiler does not directly generate machine code;
+instead it generates C code and uses the system C compiler to turn it into machine code.
+
+The generated C code `#include`s a private header -- which we reference as "the MJIT header" everywhere.
+The MJIT header gets shipped with all MJIT-enabled Rubies and includes the layout of many internal VM structures;
+and of course the intention is that it is only used by the Ruby MJIT compiler.
+
+This header is placed inside the `include/` directory in a Ruby installation, and is named for that specific Ruby
+version. e.g. `rb_mjit_min_header-2.7.4.h`.
+
+### Approach 2: Using the `debase-ruby_core_source` gem
+
+The [`debase-ruby_core_source`](https://github.com/ruby-debug/debase-ruby_core_source) contains almost no code;
+instead, it just contains per-Ruby-version folders with the private VM headers (`.h`) files for that version.
+
+Thus, even though a regular Ruby installation does not include these files, we can access the copy inside this gem.
+
+## Feature: Getting thread CPU-time clock_ids
+
+* **OS support**: Linux
+* **Ruby support**: 2.6+
+
+To enable CPU-time profiling, we use the `pthread_getcpuclockid(pthread_t thread, clockid_t *clockid)` C function to
+obtain a `clockid_t` that can then be used with the `Process.clock_gettime` method (or directly with the
+`clock_gettime()` C function).
+
+The challenge with using `pthread_getcpuclockid()` is that we need to get the `pthread_t` for a given Ruby `Thread`
+object. We previously did this with a weird combination of monkey patching and `pthread_self()` (effectively patching
+every `Thread` to run `pthread_self()` at initialization time and stash that value somewhere), but this had a number
+of downsides.
+
+The approach we use in the profiling native extension is to reach inside the internal structure of the `Thread` object,
+and extract the `pthread_t` that Ruby itself keeps, but does not expose. This is implemented in the `pthread_id_for()`
+function in `private_vm_api_acccess.c`. Thus, using this trick we can at any point in execution go from a `Thread`
+object into the `clockid_t` that we need.
+
+Note that `pthread_getcpuclockid()` is not available on macOS (nor, obviously, on Windows), and hence this feature
+is currently Linux-specific. Thus, in the <clock_id_from_pthread.c> file we implement the feature for supported Ruby
+setups but if something is missing we instead compile in <clock_id_noop.c> that includes a no-op implementation of the
+feature.

data/ext/ddtrace_profiling_native_extension/clock_id.h

@@ -0,0 +1,4 @@
+#pragma once
+
+void self_test_clock_id();
+VALUE clock_id_for(VALUE self, VALUE thread);

data/ext/ddtrace_profiling_native_extension/clock_id_from_pthread.c

@@ -0,0 +1,52 @@
+#include "extconf.h"
+
+// This file is only compiled on systems where pthread_getcpuclockid() is available;
+// Otherwise we compile clock_id_noop.c
+#ifdef HAVE_PTHREAD_GETCPUCLOCKID
+
+#include <pthread.h>
+#include <time.h>
+#include <errno.h>
+
+#include <ruby.h>
+
+#ifdef RUBY_2_1_WORKAROUND
+#include <thread_native.h>
+#else
+#include <ruby/thread_native.h>
+#endif
+
+#include "private_vm_api_access.h"
+
+#include "clock_id.h"
+
+// Validate that our home-cooked pthread_id_for() matches pthread_self() for the current thread
+void self_test_clock_id() {
+  rb_nativethread_id_t expected_pthread_id = pthread_self();
+  rb_nativethread_id_t actual_pthread_id = pthread_id_for(rb_thread_current());
+
+  if (expected_pthread_id != actual_pthread_id) rb_raise(rb_eRuntimeError, "pthread_id_for() self-test failed");
+}
+
+VALUE clock_id_for(VALUE self, VALUE thread) {
+  rb_nativethread_id_t thread_id = pthread_id_for(thread);
+
+  clockid_t clock_id;
+  int error = pthread_getcpuclockid(thread_id, &clock_id);
+
+  if (error == 0) {
+    return CLOCKID2NUM(clock_id);
+  } else {
+    switch(error) {
+      // The more specific error messages are based on the pthread_getcpuclockid(3) man page
+      case ENOENT:
+        rb_exc_raise(rb_syserr_new(error, "Failed to get clock_id for given thread: Per-thread CPU time clocks are not supported by the system."));
+      case ESRCH:
+        rb_exc_raise(rb_syserr_new(error, "Failed to get clock_id for given thread: No thread could be found."));
+      default:
+        rb_exc_raise(rb_syserr_new(error, "Failed to get clock_id for given thread"));
+    }
+  }
+}
+
+#endif

data/ext/ddtrace_profiling_native_extension/clock_id_noop.c

@@ -0,0 +1,14 @@
+#include "extconf.h"
+
+// This file is the dual of clock_id_from_pthread.c for systems where that info
+// is not available.
+#ifndef HAVE_PTHREAD_GETCPUCLOCKID
+
+#include <ruby.h>
+
+#include "clock_id.h"
+
+void self_test_clock_id() { } // Nothing to check
+VALUE clock_id_for(VALUE self, VALUE thread) { return Qnil; } // Nothing to return
+
+#endif

data/ext/ddtrace_profiling_native_extension/extconf.rb

@@ -0,0 +1,197 @@
+# typed: ignore
+# rubocop:disable Style/StderrPuts
+
+# Older Rubies don't have the MJIT header, used by the JIT compiler, so we need to use a different approach
+CAN_USE_MJIT_HEADER = RUBY_VERSION >= '2.6'
+
+def on_jruby?
+  # We don't support JRuby for profiling, and JRuby doesn't support native extensions, so let's just skip this entire
+  # thing so that JRuby users of dd-trace-rb aren't impacted.
+  RUBY_ENGINE == 'jruby'
+end
+
+def on_truffleruby?
+  # We don't officially support TruffleRuby for dd-trace-rb at all BUT let's not break adventurous customers that
+  # want to give it a try.
+  RUBY_ENGINE == 'truffleruby'
+end
+
+def on_windows?
+  # Microsoft Windows is unsupported, so let's not build the extension there.
+  Gem.win_platform?
+end
+
+def expected_to_use_mjit_but_mjit_is_disabled?
+  # On some Rubies, we require the mjit header to be present. If Ruby was installed without MJIT support, we also skip
+  # building the extension.
+  mjit_disabled = CAN_USE_MJIT_HEADER && RbConfig::CONFIG['MJIT_SUPPORT'] != 'yes'
+
+  if mjit_disabled
+    $stderr.puts(%(
++------------------------------------------------------------------------------+
+| Your Ruby has been compiled without JIT support (--disable-jit-support).     |
+| The profiling native extension requires a Ruby compiled with JIT support,    |
+| even if the JIT is not in use by the application itself.                     |
+|                                                                              |
+| WARNING: Without the profiling native extension, some profiling features     |
+| will not be available.                                                       |
++------------------------------------------------------------------------------+
+
+))
+  end
+
+  mjit_disabled
+end
+
+def disabled_via_env?
+  # Experimental toggle to disable building the extension.
+  # Disabling the extension will lead to the profiler not working in future releases.
+  # If you needed to use this, please tell us why on <https://github.com/DataDog/dd-trace-rb/issues/new>.
+  ENV['DD_PROFILING_NO_EXTENSION'].to_s.downcase == 'true'
+end
+
+def skip_building_extension?
+  disabled_via_env? || on_jruby? || on_truffleruby? || on_windows? || expected_to_use_mjit_but_mjit_is_disabled?
+end
+
+# IMPORTANT: When adding flags, remember that our customers compile with a wide range of gcc/clang versions, so
+# doublecheck that what you're adding can be reasonably expected to work on their systems.
+def add_compiler_flag(flag)
+  $CFLAGS << ' ' << flag
+end
+
+def skip_building_extension!
+  File.write('Makefile', 'all install clean: # dummy makefile that does nothing')
+  exit
+end
+
+if skip_building_extension?
+  $stderr.puts(%(
++------------------------------------------------------------------------------+
+| Skipping build of profiling native extension and replacing it with a no-op   |
+| Makefile                                                                     |
++------------------------------------------------------------------------------+
+
+))
+  skip_building_extension!
+end
+
+$stderr.puts(%(
++------------------------------------------------------------------------------+
+| ** Preparing to build the ddtrace native extension... **                     |
+|                                                                              |
+| If you run into any failures during this step, you can set the               |
+| `DD_PROFILING_NO_EXTENSION` environment variable to `true` e.g.              |
+| `$ DD_PROFILING_NO_EXTENSION=true bundle install` to skip this step.         |
+|                                                                              |
+| Disabling the extension will lead to the ddtrace profiling features not      |
+| working in future releases.                                                  |
+| If you needed to use this, please tell us why on                             |
+| <https://github.com/DataDog/dd-trace-rb/issues/new> so we can fix it :\)      |
+|                                                                              |
+| Thanks for using ddtrace! You rock!                                          |
++------------------------------------------------------------------------------+
+
+))
+
+# NOTE: we MUST NOT require 'mkmf' before we check the #skip_building_extension? because the require triggers checks
+# that may fail on an environment not properly setup for building Ruby extensions.
+require 'mkmf'
+
+# Gets really noisy when we include the MJIT header, let's omit it
+add_compiler_flag '-Wno-unused-function'
+
+# Allow defining variables at any point in a function
+add_compiler_flag '-Wno-declaration-after-statement'
+
+# If we forget to include a Ruby header, the function call may still appear to work, but then
+# cause a segfault later. Let's ensure that never happens.
+add_compiler_flag '-Werror-implicit-function-declaration'
+
+if RUBY_PLATFORM.include?('linux')
+  # Supposedly, the correct way to do this is
+  # ```
+  # have_library 'pthread'
+  # have_func 'pthread_getcpuclockid'
+  # ```
+  # but it broke the build on Windows and on older Ruby versions (2.1 and 2.2)
+  # so instead we just assume that we have the function we need on Linux, and nowhere else
+  $defs << '-DHAVE_PTHREAD_GETCPUCLOCKID'
+end
+
+# Tag the native extension library with the Ruby version and Ruby platform.
+# This makes it easier for development (avoids "oops I forgot to rebuild when I switched my Ruby") and ensures that
+# the wrong library is never loaded.
+# When requiring, we need to use the exact same string, including the version and the platform.
+EXTENSION_NAME = "ddtrace_profiling_native_extension.#{RUBY_VERSION}_#{RUBY_PLATFORM}".freeze
+
+if CAN_USE_MJIT_HEADER
+  mjit_header_file_name = "rb_mjit_min_header-#{RUBY_VERSION}.h"
+
+  # Validate that the mjit header can actually be compiled on this system. We learned via
+  # https://github.com/DataDog/dd-trace-rb/issues/1799 and https://github.com/DataDog/dd-trace-rb/issues/1792
+  # that even if the header seems to exist, it may not even compile.
+  # `have_macro` actually tries to compile a file that mentions the given macro, so if this passes, we should be good to
+  # use the MJIT header.
+  # Finally, the `COMMON_HEADERS` conflict with the MJIT header so we need to temporarily disable them for this check.
+  original_common_headers = MakeMakefile::COMMON_HEADERS
+  MakeMakefile::COMMON_HEADERS = ''.freeze
+  unless have_macro('RUBY_MJIT_H', mjit_header_file_name)
+    $stderr.puts(%(
++------------------------------------------------------------------------------+
+| WARNING: Unable to compile a needed component for ddtrace native extension.  |
+| Your C compiler or Ruby VM just-in-time compiler seems to be broken.         |
+|                                                                              |
+| You will be NOT be able to use ddtrace profiling features,                   |
+| but all other features will work fine!                                       |
+|                                                                              |
+| For help solving this issue, please contact Datadog support at               |
+| <https://docs.datadoghq.com/help/>.                                          |
++------------------------------------------------------------------------------+
+
+))
+    skip_building_extension!
+  end
+  MakeMakefile::COMMON_HEADERS = original_common_headers
+
+  $defs << '-DUSE_MJIT_HEADER'
+
+  # NOTE: This needs to come after all changes to $defs
+  create_header
+
+  # The MJIT header is always (afaik?) suffixed with the exact Ruby VM version,
+  # including patch (e.g. 2.7.2). Thus, we add to the header file a definition
+  # containing the exact file, so that it can be used in a #include in the C code.
+  header_contents =
+    File.read($extconf_h)
+        .sub('#endif',
+             <<-EXTCONF_H.strip
+#define RUBY_MJIT_HEADER "#{mjit_header_file_name}"
+
+#endif
+             EXTCONF_H
+            )
+  File.open($extconf_h, 'w') { |file| file.puts(header_contents) }
+
+  create_makefile EXTENSION_NAME
+else
+  # On older Rubies, we use the debase-ruby_core_source gem to get access to private VM headers.
+  # This gem ships source code copies of these VM headers for the different Ruby VM versions;
+  # see https://github.com/ruby-debug/debase-ruby_core_source for details
+
+  thread_native_for_ruby_2_1 = proc { true }
+  if RUBY_VERSION < '2.2'
+    # This header became public in Ruby 2.2, but we need to pull it from the private headers folder for 2.1
+    thread_native_for_ruby_2_1 = proc { have_header('thread_native.h') }
+    $defs << '-DRUBY_2_1_WORKAROUND'
+  end
+
+  create_header
+
+  require 'debase/ruby_core_source'
+  dir_config('ruby') # allow user to pass in non-standard core include directory
+
+  Debase::RubyCoreSource
+    .create_makefile_with_core(proc { have_header('vm_core.h') && thread_native_for_ruby_2_1.call }, EXTENSION_NAME)
+end
+# rubocop:enable Style/StderrPuts

data/ext/ddtrace_profiling_native_extension/private_vm_api_access.c

@@ -0,0 +1,35 @@
+#include "extconf.h"
+
+// This file exports functions used to access private Ruby VM APIs and internals.
+// To do this, it imports a few VM internal (private) headers.
+//
+// **Important Note**: Our medium/long-term plan is to stop relying on all private Ruby headers, and instead request and
+// contribute upstream changes so that they become official public VM APIs.
+//
+// In the meanwhile, be very careful when changing things here :)
+
+#ifdef USE_MJIT_HEADER
+// Pick up internal structures from the private Ruby MJIT header file
+#include RUBY_MJIT_HEADER
+#else
+// On older Rubies, use a copy of the VM internal headers shipped in the debase-ruby_core_source gem
+#include <vm_core.h>
+#endif
+
+// MRI has a similar rb_thread_ptr() function which we can't call it directly
+// because Ruby does not expose the thread_data_type publicly.
+// Instead, we have our own version of that function, and we lazily initialize the thread_data_type pointer
+// from a known-correct object: the current thread.
+//
+// Note that beyond returning the rb_thread_struct*, rb_check_typeddata() raises an exception
+// if the argument passed in is not actually a `Thread` instance.
+static inline struct rb_thread_struct *thread_struct_from_object(VALUE thread) {
+  static const rb_data_type_t *thread_data_type = NULL;
+  if (thread_data_type == NULL) thread_data_type = RTYPEDDATA_TYPE(rb_thread_current());
+
+  return (struct rb_thread_struct *) rb_check_typeddata(thread, thread_data_type);
+}
+
+rb_nativethread_id_t pthread_id_for(VALUE thread) {
+  return thread_struct_from_object(thread)->thread_id;
+}

data/ext/ddtrace_profiling_native_extension/private_vm_api_access.h

@@ -0,0 +1,3 @@
+#pragma once
+
+rb_nativethread_id_t pthread_id_for(VALUE thread);

data/ext/ddtrace_profiling_native_extension/profiling.c

@@ -0,0 +1,22 @@
+#include <ruby.h>
+
+#include "clock_id.h"
+
+static VALUE native_working_p(VALUE self);
+
+void Init_ddtrace_profiling_native_extension(void) {
+  VALUE datadog_module = rb_define_module("Datadog");
+  VALUE profiling_module = rb_define_module_under(datadog_module, "Profiling");
+  VALUE native_extension_module = rb_define_module_under(profiling_module, "NativeExtension");
+
+  rb_define_singleton_method(native_extension_module, "native_working?", native_working_p, 0);
+  rb_funcall(native_extension_module, rb_intern("private_class_method"), 1, ID2SYM(rb_intern("native_working?")));
+
+  rb_define_singleton_method(native_extension_module, "clock_id_for", clock_id_for, 1); // from clock_id.h
+}
+
+static VALUE native_working_p(VALUE self) {
+  self_test_clock_id();
+
+  return Qtrue;
+}

data/lib/datadog/ci/configuration/components.rb

@@ -0,0 +1,31 @@
+# typed: true
+require 'datadog/ci/context_flush'
+
+module Datadog
+  module CI
+    module Configuration
+      # Adds CI behavior to Datadog trace components
+      module Components
+        def initialize(settings)
+          # Activate CI mode if enabled
+          activate_ci_mode!(settings) if settings.ci_mode.enabled
+
+          # Initialize normally
+          super
+        end
+
+        def activate_ci_mode!(settings)
+          # Activate underlying tracing test mode
+          settings.test_mode.enabled = true
+
+          # Choose user defined ContextFlush or default to CI ContextFlush
+          settings.test_mode.context_flush = settings.ci_mode.context_flush \
+                                             || Datadog::CI::ContextFlush::Finished.new
+
+          # Pass through any other options
+          settings.test_mode.writer_options = settings.ci_mode.writer_options
+        end
+      end
+    end
+  end
+end

data/lib/datadog/ci/configuration/settings.rb

@@ -0,0 +1,37 @@
+# typed: false
+require 'datadog/ci/ext/settings'
+
+module Datadog
+  module CI
+    module Configuration
+      # Adds CI behavior to Datadog trace settings
+      module Settings
+        def self.extended(base)
+          base = base.singleton_class unless base.is_a?(Class)
+          add_settings!(base)
+        end
+
+        def self.add_settings!(base)
+          base.class_eval do
+            settings :ci_mode do
+              option :enabled do |o|
+                o.default { env_to_bool(Datadog::CI::Ext::Settings::ENV_MODE_ENABLED, false) }
+                o.lazy
+              end
+
+              option :context_flush do |o|
+                o.default { nil }
+                o.lazy
+              end
+
+              option :writer_options do |o|
+                o.default { {} }
+                o.lazy
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/ci/context_flush.rb

@@ -0,0 +1,29 @@
+# typed: true
+require 'ddtrace/context_flush'
+
+module Datadog
+  module CI
+    module ContextFlush
+      # Common behavior for CI flushing
+      module Tagging
+        # Decorate a trace with CI tags
+        def get_trace(context)
+          context.get do |trace|
+            # Origin tag is required on every span
+            trace.each { |span| context.attach_origin(span) } if trace
+          end
+        end
+      end
+
+      # Consumes only completed traces (where all spans have finished)
+      class Finished < Datadog::ContextFlush::Finished
+        prepend Tagging
+      end
+
+      # Performs partial trace flushing to avoid large traces residing in memory for too long
+      class Partial < Datadog::ContextFlush::Partial
+        prepend Tagging
+      end
+    end
+  end
+end

data/lib/datadog/ci/contrib/cucumber/configuration/settings.rb

@@ -0,0 +1,31 @@
+# typed: false
+require 'ddtrace/contrib/configuration/settings'
+require 'datadog/ci/contrib/cucumber/ext'
+
+module Datadog
+  module CI
+    module Contrib
+      module Cucumber
+        module Configuration
+          # Custom settings for the Cucumber integration
+          class Settings < Datadog::Contrib::Configuration::Settings
+            option :enabled do |o|
+              o.default { env_to_bool(Ext::ENV_ENABLED, true) }
+              o.lazy
+            end
+
+            option :service_name do |o|
+              o.default { Datadog.configuration.service_without_fallback || Ext::SERVICE_NAME }
+              o.lazy
+            end
+
+            option :operation_name do |o|
+              o.default { ENV.key?(Ext::ENV_OPERATION_NAME) ? ENV[Ext::ENV_OPERATION_NAME] : Ext::OPERATION_NAME }
+              o.lazy
+            end
+          end
+        end
+      end
+    end
+  end
+end