ddtrace 0.54.2 → 1.8.0

data/ext/ddtrace_profiling_native_extension/http_transport.c

@@ -0,0 +1,353 @@
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <datadog/profiling.h>
+#include "helpers.h"
+#include "libdatadog_helpers.h"
+#include "ruby_helpers.h"
+
+// Used to report profiling data to Datadog.
+// This file implements the native bits of the Datadog::Profiling::HttpTransport class
+
+static VALUE ok_symbol = Qnil; // :ok in Ruby
+static VALUE error_symbol = Qnil; // :error in Ruby
+
+static ID agentless_id; // id of :agentless in Ruby
+static ID agent_id; // id of :agent in Ruby
+
+static ID log_failure_to_process_tag_id; // id of :log_failure_to_process_tag in Ruby
+
+static VALUE http_transport_class = Qnil;
+static VALUE library_version_string = Qnil;
+
+struct call_exporter_without_gvl_arguments {
+  ddog_ProfileExporter *exporter;
+  ddog_Request *request;
+  ddog_CancellationToken *cancel_token;
+  ddog_SendResult result;
+  bool send_ran;
+};
+
+inline static ddog_ByteSlice byte_slice_from_ruby_string(VALUE string);
+static VALUE _native_validate_exporter(VALUE self, VALUE exporter_configuration);
+static ddog_NewProfileExporterResult create_exporter(VALUE exporter_configuration, VALUE tags_as_array);
+static VALUE handle_exporter_failure(ddog_NewProfileExporterResult exporter_result);
+static ddog_Endpoint endpoint_from(VALUE exporter_configuration);
+static ddog_Vec_tag convert_tags(VALUE tags_as_array);
+static void safely_log_failure_to_process_tag(ddog_Vec_tag tags, VALUE err_details);
+static VALUE _native_do_export(
+  VALUE self,
+  VALUE exporter_configuration,
+  VALUE upload_timeout_milliseconds,
+  VALUE start_timespec_seconds,
+  VALUE start_timespec_nanoseconds,
+  VALUE finish_timespec_seconds,
+  VALUE finish_timespec_nanoseconds,
+  VALUE pprof_file_name,
+  VALUE pprof_data,
+  VALUE code_provenance_file_name,
+  VALUE code_provenance_data,
+  VALUE tags_as_array
+);
+static void *call_exporter_without_gvl(void *call_args);
+static void interrupt_exporter_call(void *cancel_token);
+static VALUE ddtrace_version(void);
+
+void http_transport_init(VALUE profiling_module) {
+  http_transport_class = rb_define_class_under(profiling_module, "HttpTransport", rb_cObject);
+
+  rb_define_singleton_method(http_transport_class, "_native_validate_exporter",  _native_validate_exporter, 1);
+  rb_define_singleton_method(http_transport_class, "_native_do_export",  _native_do_export, 11);
+
+  ok_symbol = ID2SYM(rb_intern_const("ok"));
+  error_symbol = ID2SYM(rb_intern_const("error"));
+  agentless_id = rb_intern_const("agentless");
+  agent_id = rb_intern_const("agent");
+  log_failure_to_process_tag_id = rb_intern_const("log_failure_to_process_tag");
+
+  library_version_string = ddtrace_version();
+  rb_global_variable(&library_version_string);
+}
+
+inline static ddog_ByteSlice byte_slice_from_ruby_string(VALUE string) {
+  ENFORCE_TYPE(string, T_STRING);
+  ddog_ByteSlice byte_slice = {.ptr = (uint8_t *) StringValuePtr(string), .len = RSTRING_LEN(string)};
+  return byte_slice;
+}
+
+static VALUE _native_validate_exporter(DDTRACE_UNUSED VALUE _self, VALUE exporter_configuration) {
+  ENFORCE_TYPE(exporter_configuration, T_ARRAY);
+  ddog_NewProfileExporterResult exporter_result = create_exporter(exporter_configuration, rb_ary_new());
+
+  VALUE failure_tuple = handle_exporter_failure(exporter_result);
+  if (!NIL_P(failure_tuple)) return failure_tuple;
+
+  // We don't actually need the exporter for now -- we just wanted to validate that we could create it with the
+  // settings we were given
+  ddog_NewProfileExporterResult_drop(exporter_result);
+
+  return rb_ary_new_from_args(2, ok_symbol, Qnil);
+}
+
+static ddog_NewProfileExporterResult create_exporter(VALUE exporter_configuration, VALUE tags_as_array) {
+  ENFORCE_TYPE(exporter_configuration, T_ARRAY);
+  ENFORCE_TYPE(tags_as_array, T_ARRAY);
+
+  // This needs to be called BEFORE convert_tags since it can raise an exception and thus cause the ddog_Vec_tag
+  // to be leaked.
+  ddog_Endpoint endpoint = endpoint_from(exporter_configuration);
+
+  ddog_Vec_tag tags = convert_tags(tags_as_array);
+
+  ddog_CharSlice library_name = DDOG_CHARSLICE_C("dd-trace-rb");
+  ddog_CharSlice library_version = char_slice_from_ruby_string(library_version_string);
+  ddog_CharSlice profiling_family = DDOG_CHARSLICE_C("ruby");
+
+  ddog_NewProfileExporterResult exporter_result =
+    ddog_ProfileExporter_new(library_name, library_version, profiling_family, &tags, endpoint);
+
+  ddog_Vec_tag_drop(tags);
+
+  return exporter_result;
+}
+
+static VALUE handle_exporter_failure(ddog_NewProfileExporterResult exporter_result) {
+  if (exporter_result.tag == DDOG_NEW_PROFILE_EXPORTER_RESULT_OK) return Qnil;
+
+  VALUE err_details = ruby_string_from_vec_u8(exporter_result.err);
+
+  ddog_NewProfileExporterResult_drop(exporter_result);
+
+  return rb_ary_new_from_args(2, error_symbol, err_details);
+}
+
+static ddog_Endpoint endpoint_from(VALUE exporter_configuration) {
+  ENFORCE_TYPE(exporter_configuration, T_ARRAY);
+
+  ID working_mode = SYM2ID(rb_ary_entry(exporter_configuration, 0)); // SYM2ID verifies its input so we can do this safely
+
+  if (working_mode != agentless_id && working_mode != agent_id) {
+    rb_raise(rb_eArgError, "Failed to initialize transport: Unexpected working mode, expected :agentless or :agent");
+  }
+
+  if (working_mode == agentless_id) {
+    VALUE site = rb_ary_entry(exporter_configuration, 1);
+    VALUE api_key = rb_ary_entry(exporter_configuration, 2);
+    ENFORCE_TYPE(site, T_STRING);
+    ENFORCE_TYPE(api_key, T_STRING);
+
+    return ddog_Endpoint_agentless(char_slice_from_ruby_string(site), char_slice_from_ruby_string(api_key));
+  } else { // agent_id
+    VALUE base_url = rb_ary_entry(exporter_configuration, 1);
+    ENFORCE_TYPE(base_url, T_STRING);
+
+    return ddog_Endpoint_agent(char_slice_from_ruby_string(base_url));
+  }
+}
+
+__attribute__((warn_unused_result))
+static ddog_Vec_tag convert_tags(VALUE tags_as_array) {
+  ENFORCE_TYPE(tags_as_array, T_ARRAY);
+
+  long tags_count = RARRAY_LEN(tags_as_array);
+  ddog_Vec_tag tags = ddog_Vec_tag_new();
+
+  for (long i = 0; i < tags_count; i++) {
+    VALUE name_value_pair = rb_ary_entry(tags_as_array, i);
+
+    if (!RB_TYPE_P(name_value_pair, T_ARRAY)) {
+      ddog_Vec_tag_drop(tags);
+      ENFORCE_TYPE(name_value_pair, T_ARRAY);
+    }
+
+    // Note: We can index the array without checking its size first because rb_ary_entry returns Qnil if out of bounds
+    VALUE tag_name = rb_ary_entry(name_value_pair, 0);
+    VALUE tag_value = rb_ary_entry(name_value_pair, 1);
+
+    if (!(RB_TYPE_P(tag_name, T_STRING) && RB_TYPE_P(tag_value, T_STRING))) {
+      ddog_Vec_tag_drop(tags);
+      ENFORCE_TYPE(tag_name, T_STRING);
+      ENFORCE_TYPE(tag_value, T_STRING);
+    }
+
+    ddog_PushTagResult push_result =
+      ddog_Vec_tag_push(&tags, char_slice_from_ruby_string(tag_name), char_slice_from_ruby_string(tag_value));
+
+    if (push_result.tag == DDOG_PUSH_TAG_RESULT_ERR) {
+      VALUE err_details = ruby_string_from_vec_u8(push_result.err);
+      ddog_PushTagResult_drop(push_result);
+
+      // libdatadog validates tags and may catch invalid tags that ddtrace didn't actually catch.
+      // We warn users about such tags, and then just ignore them.
+      safely_log_failure_to_process_tag(tags, err_details);
+    } else {
+      ddog_PushTagResult_drop(push_result);
+    }
+  }
+
+  return tags;
+}
+
+static VALUE log_failure_to_process_tag(VALUE err_details) {
+  return rb_funcall(http_transport_class, log_failure_to_process_tag_id, 1, err_details);
+}
+
+// Since we are calling into Ruby code, it may raise an exception. This method ensure that dynamically-allocated tags
+// get cleaned before propagating the exception.
+static void safely_log_failure_to_process_tag(ddog_Vec_tag tags, VALUE err_details) {
+  int exception_state;
+  rb_protect(log_failure_to_process_tag, err_details, &exception_state);
+
+  if (exception_state) {           // An exception was raised
+    ddog_Vec_tag_drop(tags); // clean up
+    rb_jump_tag(exception_state);  // "Re-raise" exception
+  }
+}
+
+// Note: This function handles a bunch of libdatadog dynamically-allocated objects, so it MUST not use any Ruby APIs
+// which can raise exceptions, otherwise the objects will be leaked.
+static VALUE perform_export(
+  ddog_NewProfileExporterResult valid_exporter_result, // Must be called with a valid exporter result
+  ddog_Timespec start,
+  ddog_Timespec finish,
+  ddog_Slice_file slice_files,
+  ddog_Vec_tag *additional_tags,
+  uint64_t timeout_milliseconds
+) {
+  ddog_ProfileExporter *exporter = valid_exporter_result.ok;
+  ddog_CancellationToken *cancel_token = ddog_CancellationToken_new();
+  ddog_Request *request =
+    ddog_ProfileExporter_build(exporter, start, finish, slice_files, additional_tags, timeout_milliseconds);
+
+  // We'll release the Global VM Lock while we're calling send, so that the Ruby VM can continue to work while this
+  // is pending
+  struct call_exporter_without_gvl_arguments args =
+    {.exporter = exporter, .request = request, .cancel_token = cancel_token, .send_ran = false};
+
+  // We use rb_thread_call_without_gvl2 instead of rb_thread_call_without_gvl as the gvl2 variant never raises any
+  // exceptions.
+  //
+  // (With rb_thread_call_without_gvl, if someone calls Thread#kill or something like it on the current thread,
+  // the exception will be raised without us being able to clean up dynamically-allocated stuff, which would leak.)
+  //
+  // Instead, we take care of our own exception checking, and delay the exception raising (`rb_jump_tag` call) until
+  // after we cleaned up any dynamically-allocated resources.
+  //
+  // We run rb_thread_call_without_gvl2 in a loop since an "interrupt" may cause it to return before even running
+  // our code. In such a case, we retry the call -- unless the interrupt was caused by an exception being pending,
+  // and in that case we also give up and break out of the loop.
+  int pending_exception = 0;
+
+  while (!args.send_ran && !pending_exception) {
+    rb_thread_call_without_gvl2(call_exporter_without_gvl, &args, interrupt_exporter_call, cancel_token);
+
+    // To make sure we don't leak memory, we never check for pending exceptions if send ran
+    if (!args.send_ran) pending_exception = check_if_pending_exception();
+  }
+
+  // Cleanup exporter and token, no longer needed
+  ddog_CancellationToken_drop(cancel_token);
+  ddog_NewProfileExporterResult_drop(valid_exporter_result);
+
+  if (pending_exception) {
+    // If we got here send did not run, so we need to explicitly dispose of the request
+    ddog_Request_drop(request);
+
+    // Let Ruby propagate the exception. This will not return.
+    rb_jump_tag(pending_exception);
+  }
+
+  ddog_SendResult result = args.result;
+  bool success = result.tag == DDOG_SEND_RESULT_HTTP_RESPONSE;
+
+  VALUE ruby_status = success ? ok_symbol : error_symbol;
+  VALUE ruby_result = success ? UINT2NUM(result.http_response.code) : ruby_string_from_vec_u8(result.err);
+
+  ddog_SendResult_drop(args.result);
+  // The request itself does not need to be freed as libdatadog takes care of it as part of sending.
+
+  return rb_ary_new_from_args(2, ruby_status, ruby_result);
+}
+
+static VALUE _native_do_export(
+  DDTRACE_UNUSED VALUE _self,
+  VALUE exporter_configuration,
+  VALUE upload_timeout_milliseconds,
+  VALUE start_timespec_seconds,
+  VALUE start_timespec_nanoseconds,
+  VALUE finish_timespec_seconds,
+  VALUE finish_timespec_nanoseconds,
+  VALUE pprof_file_name,
+  VALUE pprof_data,
+  VALUE code_provenance_file_name,
+  VALUE code_provenance_data,
+  VALUE tags_as_array
+) {
+  ENFORCE_TYPE(upload_timeout_milliseconds, T_FIXNUM);
+  ENFORCE_TYPE(start_timespec_seconds, T_FIXNUM);
+  ENFORCE_TYPE(start_timespec_nanoseconds, T_FIXNUM);
+  ENFORCE_TYPE(finish_timespec_seconds, T_FIXNUM);
+  ENFORCE_TYPE(finish_timespec_nanoseconds, T_FIXNUM);
+  ENFORCE_TYPE(pprof_file_name, T_STRING);
+  ENFORCE_TYPE(pprof_data, T_STRING);
+  ENFORCE_TYPE(code_provenance_file_name, T_STRING);
+
+  // Code provenance can be disabled and in that case will be set to nil
+  bool have_code_provenance = !NIL_P(code_provenance_data);
+  if (have_code_provenance) ENFORCE_TYPE(code_provenance_data, T_STRING);
+
+  uint64_t timeout_milliseconds = NUM2ULONG(upload_timeout_milliseconds);
+
+  ddog_Timespec start =
+    {.seconds = NUM2LONG(start_timespec_seconds), .nanoseconds = NUM2UINT(start_timespec_nanoseconds)};
+  ddog_Timespec finish =
+    {.seconds = NUM2LONG(finish_timespec_seconds), .nanoseconds = NUM2UINT(finish_timespec_nanoseconds)};
+
+  int files_to_report = 1 + (have_code_provenance ? 1 : 0);
+  ddog_File files[files_to_report];
+  ddog_Slice_file slice_files = {.ptr = files, .len = files_to_report};
+
+  files[0] = (ddog_File) {
+    .name = char_slice_from_ruby_string(pprof_file_name),
+    .file = byte_slice_from_ruby_string(pprof_data)
+  };
+  if (have_code_provenance) {
+    files[1] = (ddog_File) {
+      .name = char_slice_from_ruby_string(code_provenance_file_name),
+      .file = byte_slice_from_ruby_string(code_provenance_data)
+    };
+  }
+
+  ddog_Vec_tag *null_additional_tags = NULL;
+
+  ddog_NewProfileExporterResult exporter_result = create_exporter(exporter_configuration, tags_as_array);
+  // Note: Do not add anything that can raise exceptions after this line, as otherwise the exporter memory will leak
+
+  VALUE failure_tuple = handle_exporter_failure(exporter_result);
+  if (!NIL_P(failure_tuple)) return failure_tuple;
+
+  return perform_export(exporter_result, start, finish, slice_files, null_additional_tags, timeout_milliseconds);
+}
+
+static void *call_exporter_without_gvl(void *call_args) {
+  struct call_exporter_without_gvl_arguments *args = (struct call_exporter_without_gvl_arguments*) call_args;
+
+  args->result = ddog_ProfileExporter_send(args->exporter, args->request, args->cancel_token);
+  args->send_ran = true;
+
+  return NULL; // Unused
+}
+
+// Called by Ruby when it wants to interrupt call_exporter_without_gvl above, e.g. when the app wants to exit cleanly
+static void interrupt_exporter_call(void *cancel_token) {
+  ddog_CancellationToken_cancel((ddog_CancellationToken *) cancel_token);
+}
+
+static VALUE ddtrace_version(void) {
+  VALUE ddtrace_module = rb_const_get(rb_cObject, rb_intern("DDTrace"));
+  ENFORCE_TYPE(ddtrace_module, T_MODULE);
+  VALUE version_module = rb_const_get(ddtrace_module, rb_intern("VERSION"));
+  ENFORCE_TYPE(version_module, T_MODULE);
+  VALUE version_string = rb_const_get(version_module, rb_intern("STRING"));
+  ENFORCE_TYPE(version_string, T_STRING);
+  return version_string;
+}

data/ext/ddtrace_profiling_native_extension/libdatadog_helpers.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <datadog/profiling.h>
+#include "ruby_helpers.h"
+
+inline static ddog_CharSlice char_slice_from_ruby_string(VALUE string) {
+  ENFORCE_TYPE(string, T_STRING);
+  ddog_CharSlice char_slice = {.ptr = StringValuePtr(string), .len = RSTRING_LEN(string)};
+  return char_slice;
+}
+
+inline static VALUE ruby_string_from_vec_u8(ddog_Vec_u8 string) {
+  return rb_str_new((char *) string.ptr, string.len);
+}

data/ext/ddtrace_profiling_native_extension/native_extension_helpers.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+# typed: ignore
+
+require 'libdatadog'
+require 'pathname'
+
+module Datadog
+  module Profiling
+    # Helpers for extconf.rb
+    module NativeExtensionHelpers
+      # Can be set when customers want to skip compiling the native extension entirely
+      ENV_NO_EXTENSION = 'DD_PROFILING_NO_EXTENSION'
+      # Can be set to force rubygems to fail gem installation when profiling extension could not be built
+      ENV_FAIL_INSTALL_IF_MISSING_EXTENSION = 'DD_PROFILING_FAIL_INSTALL_IF_MISSING_EXTENSION'
+
+      # 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 self.fail_install_if_missing_extension?
+        ENV[ENV_FAIL_INSTALL_IF_MISSING_EXTENSION].to_s.strip.downcase == 'true'
+      end
+
+      # Used as an workaround for a limitation with how dynamic linking works in environments where ddtrace and
+      # libdatadog are moved after the extension gets compiled.
+      #
+      # Because the libddpprof native library is installed on a non-standard system path, in order for it to be
+      # found by the system dynamic linker (e.g. what takes care of dlopen(), which is used to load the profiling
+      # native extension), we need to add a "runpath" -- a list of folders to search for libdatadog.
+      #
+      # This runpath gets hardcoded at native library linking time. You can look at it using the `readelf` tool in
+      # Linux: e.g. `readelf -d ddtrace_profiling_native_extension.2.7.3_x86_64-linux.so`.
+      #
+      # In older versions of ddtrace, we only set as runpath an absolute path to libdatadog.
+      # (This gets set automatically by the call
+      # to `pkg_config('datadog_profiling_with_rpath')` in `extconf.rb`). This worked fine as long as libdatadog was **NOT**
+      # moved from the folder it was present at ddtrace installation/linking time.
+      #
+      # Unfortunately, environments such as Heroku and AWS Elastic Beanstalk move gems around in the filesystem after
+      # installation. Thus, the profiling native extension could not be loaded in these environments
+      # (see https://github.com/DataDog/dd-trace-rb/issues/2067) because libdatadog could not be found.
+      #
+      # To workaround this issue, this method computes the **relative** path between the folder where the profiling
+      # native extension is going to be installed and the folder where libdatadog is installed, and returns it
+      # to be set as an additional runpath. (Yes, you can set multiple runpath folders to be searched).
+      #
+      # This way, if both gems are moved together (and it turns out that they are in these environments),
+      # the relative path can still be traversed to find libdatadog.
+      #
+      # This is incredibly awful, and it's kinda bizarre how it's not possible to just find these paths at runtime
+      # and set them correctly; rather than needing to set stuff at linking-time and then praying to $deity that
+      # weird moves don't happen.
+      #
+      # As a curiosity, `LD_LIBRARY_PATH` can be used to influence the folders that get searched but **CANNOT BE
+      # SET DYNAMICALLY**, e.g. it needs to be set at the start of the process (Ruby VM) and thus it's not something
+      # we could setup when doing a `require`.
+      #
+      def self.libdatadog_folder_relative_to_native_lib_folder(
+        current_folder: __dir__,
+        libdatadog_pkgconfig_folder: Libdatadog.pkgconfig_folder
+      )
+        return unless libdatadog_pkgconfig_folder
+
+        profiling_native_lib_folder = "#{current_folder}/../../lib/"
+        libdatadog_lib_folder = "#{libdatadog_pkgconfig_folder}/../"
+
+        Pathname.new(libdatadog_lib_folder).relative_path_from(Pathname.new(profiling_native_lib_folder)).to_s
+      end
+
+      # Used to check if profiler is supported, including user-visible clear messages explaining why their
+      # system may not be supported.
+      module Supported
+        private_class_method def self.explain_issue(*reason, suggested:)
+          { reason: reason, suggested: suggested }
+        end
+
+        def self.supported?
+          unsupported_reason.nil?
+        end
+
+        def self.unsupported_reason
+          disabled_via_env? ||
+            on_jruby? ||
+            on_truffleruby? ||
+            on_windows? ||
+            on_macos? ||
+            on_unknown_os? ||
+            not_on_amd64_or_arm64? ||
+            on_ruby_2_1? ||
+            expected_to_use_mjit_but_mjit_is_disabled? ||
+            libdatadog_not_usable?
+        end
+
+        # This banner will show up in the logs/terminal while compiling the native extension
+        def self.failure_banner_for(reason:, suggested:, fail_install:)
+          prettify_lines = proc { |lines| Array(lines).map { |line| "| #{line.ljust(76)} |" }.join("\n") }
+          outcome =
+            if fail_install
+              [
+                'Failing installation immediately because the ',
+                "`#{ENV_FAIL_INSTALL_IF_MISSING_EXTENSION}` environment variable is set",
+                'to `true`.',
+                'When contacting support, please include the <mkmf.log> file that is shown ',
+                'below.',
+              ]
+            else
+              [
+                'The Datadog Continuous Profiler will not be available,',
+                'but all other ddtrace features will work fine!',
+              ]
+            end
+
+          %(
++------------------------------------------------------------------------------+
+| Could not compile the Datadog Continuous Profiler because                    |
+#{prettify_lines.call(reason)}
+|                                                                              |
+#{prettify_lines.call(outcome)}
+|                                                                              |
+#{prettify_lines.call(suggested)}
++------------------------------------------------------------------------------+
+          )
+        end
+
+        # This will be saved in a file to later be presented while operating the gem
+        def self.render_skipped_reason_file(reason:, suggested:)
+          [*reason, *suggested].join(' ')
+        end
+
+        # mkmf sets $PKGCONFIG after the `pkg_config` gets used in extconf.rb. When `pkg_config` is unsuccessful, we use
+        # this helper to decide if we can show more specific error message vs a generic "something went wrong".
+        def self.pkg_config_missing?(command: $PKGCONFIG) # rubocop:disable Style/GlobalVars
+          pkg_config_available = command && xsystem("#{command} --version")
+
+          pkg_config_available != true
+        end
+
+        CONTACT_SUPPORT = [
+          'For help solving this issue, please contact Datadog support at',
+          '<https://docs.datadoghq.com/help/>.',
+          'You can also check out the Continuous Profiler troubleshooting page at',
+          '<https://dtdg.co/ruby-profiler-troubleshooting>.'
+        ].freeze
+
+        REPORT_ISSUE = [
+          '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 :)',
+        ].freeze
+
+        GET_IN_TOUCH = [
+          "Get in touch with us if you're interested in profiling your app!"
+        ].freeze
+
+        UPGRADE_RUBY = [
+          'Upgrade to a modern Ruby to enable profiling for your app.'
+        ].freeze
+
+        # Validation for this check is done in extconf.rb because it relies on mkmf
+        FAILED_TO_CONFIGURE_LIBDATADOG = explain_issue(
+          'there was a problem in setting up the `libdatadog` dependency.',
+          suggested: CONTACT_SUPPORT,
+        )
+
+        # Validation for this check is done in extconf.rb because it relies on mkmf
+        COMPILATION_BROKEN = explain_issue(
+          'compilation of the Ruby VM just-in-time header failed.',
+          'Your C compiler or Ruby VM just-in-time compiler seem to be broken.',
+          suggested: CONTACT_SUPPORT,
+        )
+
+        # Validation for this check is done in extconf.rb because it relies on mkmf
+        PKG_CONFIG_IS_MISSING = explain_issue(
+          #+-----------------------------------------------------------------------------+
+          'the `pkg-config` system tool is missing.',
+          'This issue can usually be fixed by installing:',
+          '1. the `pkg-config` package on Homebrew and Debian/Ubuntu-based Linux;',
+          '2. the `pkgconf` package on Arch and Alpine-based Linux;',
+          '3. the `pkgconf-pkg-config` package on Fedora/Red Hat-based Linux.',
+          suggested: CONTACT_SUPPORT,
+        )
+
+        # Validation for this check is done in extconf.rb because it relies on mkmf
+        COMPILER_ATOMIC_MISSING = explain_issue(
+          'your C compiler is missing support for the <stdatomic.h> header.',
+          'This issue can usually be fixed by upgrading to a later version of your',
+          'operating system image or compiler.',
+          suggested: CONTACT_SUPPORT,
+        )
+
+        private_class_method def self.disabled_via_env?
+          disabled_via_env = explain_issue(
+            'the `DD_PROFILING_NO_EXTENSION` environment variable is/was set to',
+            '`true` during installation.',
+            suggested: REPORT_ISSUE,
+          )
+
+          return unless ENV[ENV_NO_EXTENSION].to_s.strip.downcase == 'true'
+
+          disabled_via_env
+        end
+
+        private_class_method def self.on_jruby?
+          jruby_not_supported = explain_issue(
+            'JRuby is not supported by the Datadog Continuous Profiler.',
+            suggested: GET_IN_TOUCH,
+          )
+
+          jruby_not_supported if RUBY_ENGINE == 'jruby'
+        end
+
+        private_class_method def self.on_truffleruby?
+          truffleruby_not_supported = explain_issue(
+            'TruffleRuby is not supported by the ddtrace gem.',
+            suggested: GET_IN_TOUCH,
+          )
+
+          truffleruby_not_supported if RUBY_ENGINE == 'truffleruby'
+        end
+
+        # See https://docs.datadoghq.com/tracing/setup_overview/setup/ruby/#microsoft-windows-support for current
+        # state of Windows support in ddtrace.
+        private_class_method def self.on_windows?
+          windows_not_supported = explain_issue(
+            'Microsoft Windows is not supported by the Datadog Continuous Profiler.',
+            suggested: GET_IN_TOUCH,
+          )
+
+          windows_not_supported if Gem.win_platform?
+        end
+
+        private_class_method def self.on_macos?
+          macos_not_supported = explain_issue(
+            'macOS is currently not supported by the Datadog Continuous Profiler.',
+            suggested: GET_IN_TOUCH,
+          )
+          # For development only; not supported otherwise
+          macos_testing_override = ENV['DD_PROFILING_MACOS_TESTING'] == 'true'
+
+          macos_not_supported if RUBY_PLATFORM.include?('darwin') && !macos_testing_override
+        end
+
+        private_class_method def self.on_unknown_os?
+          unknown_os_not_supported = explain_issue(
+            'your operating system is not supported by the Datadog Continuous Profiler.',
+            suggested: GET_IN_TOUCH,
+          )
+
+          unknown_os_not_supported unless RUBY_PLATFORM.include?('darwin') || RUBY_PLATFORM.include?('linux')
+        end
+
+        private_class_method def self.not_on_amd64_or_arm64?
+          architecture_not_supported = explain_issue(
+            'your CPU architecture is not supported by the Datadog Continuous Profiler.',
+            suggested: GET_IN_TOUCH,
+          )
+
+          architecture_not_supported unless RUBY_PLATFORM.start_with?('x86_64', 'aarch64')
+        end
+
+        private_class_method def self.on_ruby_2_1?
+          ruby_version_not_supported = explain_issue(
+            'the profiler only supports Ruby 2.2 or newer.',
+            suggested: UPGRADE_RUBY,
+          )
+
+          ruby_version_not_supported if RUBY_VERSION.start_with?('2.1.')
+        end
+
+        # On some Rubies, we require the mjit header to be present. If Ruby was installed without MJIT support, we also skip
+        # building the extension.
+        private_class_method def self.expected_to_use_mjit_but_mjit_is_disabled?
+          ruby_without_mjit = explain_issue(
+            '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.',
+            suggested: CONTACT_SUPPORT,
+          )
+
+          ruby_without_mjit if CAN_USE_MJIT_HEADER && RbConfig::CONFIG['MJIT_SUPPORT'] != 'yes'
+        end
+
+        private_class_method def self.libdatadog_not_usable?
+          no_binaries_for_current_platform = explain_issue(
+            'the `libdatadog` gem installed on your system is missing binaries for your',
+            'platform variant.',
+            "(Your platform: `#{Gem::Platform.local}`)",
+            '(Available binaries: ',
+            "`#{Libdatadog.available_binaries.join('`, `')}`)",
+            suggested: CONTACT_SUPPORT,
+          )
+
+          no_binaries_for_current_platform unless Libdatadog.pkgconfig_folder
+        end
+      end
+    end
+  end
+end