cw-datadog 2.23.0.2

data/ext/libdatadog_api/extconf.rb

@@ -0,0 +1,110 @@
+# rubocop:disable Style/StderrPuts
+# rubocop:disable Style/GlobalVars
+
+require 'rubygems'
+require_relative '../libdatadog_extconf_helpers'
+
+def skip_building_extension!(reason)
+  $stderr.puts(
+    "WARN: Skipping build of libdatadog_api (#{reason}). Some functionality will not be available."
+  )
+
+  fail_install_if_missing_extension = ENV['DD_FAIL_INSTALL_IF_MISSING_EXTENSION'].to_s.strip.downcase == 'true'
+
+  if fail_install_if_missing_extension
+    require 'mkmf'
+    Logging.message("[datadog] Failure cause: #{reason}")
+  else
+    File.write('Makefile', 'all install clean: # dummy makefile that does nothing')
+  end
+
+  exit
+end
+
+if ENV['DD_NO_EXTENSION'].to_s.strip.downcase == 'true'
+  skip_building_extension!('the `DD_NO_EXTENSION` environment variable is/was set to `true` during installation')
+end
+skip_building_extension!('current Ruby VM is not supported') if RUBY_ENGINE != 'ruby'
+skip_building_extension!('Microsoft Windows is not supported') if Gem.win_platform?
+
+libdatadog_issue = Datadog::LibdatadogExtconfHelpers.load_libdatadog_or_get_issue
+skip_building_extension!("issue setting up `libdatadog` gem: #{libdatadog_issue}") if libdatadog_issue
+
+require 'mkmf'
+
+# Because we can't control what compiler versions our customers use, shipping with -Werror by default is a no-go.
+# But we can enable it in CI, so that we quickly spot any new warnings that just got introduced.
+append_cflags '-Werror' if ENV['DATADOG_GEM_CI'] == 'true'
+
+# Older gcc releases may not default to C99 and we need to ask for this. This is also used:
+# * by upstream Ruby -- search for gnu99 in the codebase
+# * by msgpack, another datadog gem dependency
+#   (https://github.com/msgpack/msgpack-ruby/blob/18ce08f6d612fe973843c366ac9a0b74c4e50599/ext/msgpack/extconf.rb#L8)
+append_cflags '-std=gnu99'
+
+# Allow defining variables at any point in a function
+append_cflags '-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.
+append_cflags '-Werror-implicit-function-declaration'
+
+# Warn on unused parameters to functions. Use `DDTRACE_UNUSED` to mark things as known-to-not-be-used.
+append_cflags '-Wunused-parameter'
+
+# The native extension is not intended to expose any symbols/functions for other native libraries to use;
+# the sole exception being `Init_libdatadog_api` which needs to be visible for Ruby to call it when
+# it `dlopen`s the library.
+#
+# By setting this compiler flag, we tell it to assume that everything is private unless explicitly stated.
+# For more details see https://gcc.gnu.org/wiki/Visibility
+append_cflags '-fvisibility=hidden'
+
+# Avoid legacy C definitions
+append_cflags '-Wold-style-definition'
+
+# Enable all other compiler warnings
+append_cflags '-Wall'
+append_cflags '-Wextra'
+
+if ENV['DDTRACE_DEBUG'] == 'true'
+  $defs << '-DDD_DEBUG'
+  CONFIG['optflags'] = '-O0'
+  CONFIG['debugflags'] = '-ggdb3'
+end
+
+# If we got here, libdatadog is available and loaded
+ENV['PKG_CONFIG_PATH'] = "#{ENV["PKG_CONFIG_PATH"]}:#{Libdatadog.pkgconfig_folder}"
+Logging.message("[datadog] PKG_CONFIG_PATH set to #{ENV["PKG_CONFIG_PATH"].inspect}\n")
+$stderr.puts("Using libdatadog #{Libdatadog::VERSION} from #{Libdatadog.pkgconfig_folder}")
+
+unless pkg_config('datadog_profiling_with_rpath')
+  Logging.message("[datadog] Ruby detected the pkg-config command is #{$PKGCONFIG.inspect}\n")
+
+  if Datadog::LibdatadogExtconfHelpers.pkg_config_missing?
+    skip_building_extension!('the `pkg-config` system tool is missing')
+  else
+    skip_building_extension!('there was a problem in setting up the `libdatadog` dependency')
+  end
+end
+
+# See comments on the helper methods being used for why we need to additionally set this.
+# The extremely excessive escaping around ORIGIN below seems to be correct and was determined after a lot of
+# experimentation. We need to get these special characters across a lot of tools untouched...
+extra_relative_rpaths = [
+  Datadog::LibdatadogExtconfHelpers.libdatadog_folder_relative_to_native_lib_folder(current_folder: __dir__),
+  *Datadog::LibdatadogExtconfHelpers.libdatadog_folder_relative_to_ruby_extensions_folders,
+]
+extra_relative_rpaths.each { |folder| $LDFLAGS += " -Wl,-rpath,$$$\\\\{ORIGIN\\}/#{folder.to_str}" }
+Logging.message("[datadog] After pkg-config $LDFLAGS were set to: #{$LDFLAGS.inspect}\n")
+
+# 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 = "libdatadog_api.#{RUBY_VERSION[/\d+.\d+/]}_#{RUBY_PLATFORM}".freeze
+
+create_makefile(EXTENSION_NAME)
+
+# rubocop:enable Style/GlobalVars
+# rubocop:enable Style/StderrPuts

data/ext/libdatadog_api/init.c

@@ -0,0 +1,18 @@
+#include <ruby.h>
+
+#include "datadog_ruby_common.h"
+#include "crashtracker.h"
+#include "process_discovery.h"
+#include "library_config.h"
+
+void ddsketch_init(VALUE core_module);
+
+void DDTRACE_EXPORT Init_libdatadog_api(void) {
+  VALUE datadog_module = rb_define_module("Datadog");
+  VALUE core_module = rb_define_module_under(datadog_module, "Core");
+
+  crashtracker_init(core_module);
+  process_discovery_init(core_module);
+  library_config_init(core_module);
+  ddsketch_init(core_module);
+}

data/ext/libdatadog_api/library_config.c

@@ -0,0 +1,172 @@
+#include <ruby.h>
+#include <datadog/library-config.h>
+
+#include "library_config.h"
+#include "datadog_ruby_common.h"
+
+static VALUE _native_configurator_new(VALUE klass);
+static VALUE _native_configurator_get(VALUE self);
+
+// Used for testing in RSpec
+static VALUE _native_configurator_with_local_path(DDTRACE_UNUSED VALUE _self, VALUE rb_configurator, VALUE path);
+static VALUE _native_configurator_with_fleet_path(DDTRACE_UNUSED VALUE _self, VALUE rb_configurator, VALUE path);
+
+static VALUE config_logged_result_class = Qnil;
+
+// ddog_Configurator memory management
+static void configurator_free(void *configurator_ptr) {
+  ddog_Configurator *configurator = (ddog_Configurator *)configurator_ptr;
+
+  ddog_library_configurator_drop(configurator);
+}
+
+static const rb_data_type_t configurator_typed_data = {
+  .wrap_struct_name = "Datadog::Core::Configuration::StableConfig::Configurator",
+  .function = {
+    .dfree = configurator_free,
+    .dsize = NULL,
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+// ddog_LibraryConfigLoggedResult memory management
+static void config_logged_result_free(void *config_logged_result_ptr) {
+  ddog_LibraryConfigLoggedResult *config_logged_result = (ddog_LibraryConfigLoggedResult *)config_logged_result_ptr;
+
+  ddog_library_config_drop(*config_logged_result);
+  ruby_xfree(config_logged_result_ptr);
+}
+
+static const rb_data_type_t config_logged_result_typed_data = {
+  .wrap_struct_name = "Datadog::Core::Configuration::StableConfigLoggedResult",
+  .function = {
+    .dfree = config_logged_result_free,
+    .dsize = NULL,
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+void library_config_init(VALUE core_module) {
+  rb_global_variable(&config_logged_result_class);
+  VALUE configuration_module = rb_define_module_under(core_module, "Configuration");
+  VALUE stable_config_module = rb_define_module_under(configuration_module, "StableConfig");
+  VALUE configurator_class = rb_define_class_under(stable_config_module, "Configurator", rb_cObject);
+  config_logged_result_class = rb_define_class_under(configuration_module, "StableConfigLoggedResult", rb_cObject);
+
+  rb_define_alloc_func(configurator_class, _native_configurator_new);
+  rb_define_method(configurator_class, "get", _native_configurator_get, 0);
+
+  // Used for testing in RSpec
+  VALUE testing_module = rb_define_module_under(stable_config_module, "Testing");
+  rb_define_singleton_method(testing_module, "with_local_path", _native_configurator_with_local_path, 2);
+  rb_define_singleton_method(testing_module, "with_fleet_path", _native_configurator_with_fleet_path, 2);
+
+  rb_undef_alloc_func(config_logged_result_class); // It cannot be created from Ruby code and only serves as an intermediate object for the Ruby GC
+}
+
+static VALUE _native_configurator_new(VALUE klass) {
+  // We always collect debug logs, so if DD_TRACE_DEBUG is set by stable config, we'll be able to log them.
+  ddog_Configurator *configurator = ddog_library_configurator_new(true, DDOG_CHARSLICE_C("ruby"));
+
+  ddog_library_configurator_with_detect_process_info(configurator);
+
+  return TypedData_Wrap_Struct(klass, &configurator_typed_data, configurator);
+}
+
+static VALUE _native_configurator_with_local_path(DDTRACE_UNUSED VALUE _self, VALUE rb_configurator, VALUE path) {
+  ddog_Configurator *configurator;
+  TypedData_Get_Struct(rb_configurator, ddog_Configurator, &configurator_typed_data, configurator);
+
+  ENFORCE_TYPE(path, T_STRING);
+
+  ddog_library_configurator_with_local_path(configurator, cstr_from_ruby_string(path));
+
+  return Qnil;
+}
+
+static VALUE _native_configurator_with_fleet_path(DDTRACE_UNUSED VALUE _self, VALUE rb_configurator, VALUE path) {
+  ddog_Configurator *configurator;
+  TypedData_Get_Struct(rb_configurator, ddog_Configurator, &configurator_typed_data, configurator);
+
+  ENFORCE_TYPE(path, T_STRING);
+
+  ddog_library_configurator_with_fleet_path(configurator, cstr_from_ruby_string(path));
+
+  return Qnil;
+}
+
+static VALUE _native_configurator_get(VALUE self) {
+  ddog_Configurator *configurator;
+  TypedData_Get_Struct(self, ddog_Configurator, &configurator_typed_data, configurator);
+
+  // Wrapping config_logged_result into a Ruby object enables the Ruby GC to manage its memory
+  // We need to allocate memory for config_logged_result because once it is out of scope, it will be freed (at the end of this function)
+  // So we cannot reference it with &config_logged_result
+  // We are doing this in case one of the ruby API raises an exception before the end of this function,
+  // so the allocated memory will still be freed
+  ddog_LibraryConfigLoggedResult *configurator_logged_result = ruby_xcalloc(1, sizeof(ddog_LibraryConfigLoggedResult));
+  *configurator_logged_result = ddog_library_configurator_get(configurator);
+  VALUE config_logged_result_rb = TypedData_Wrap_Struct(config_logged_result_class, &config_logged_result_typed_data, configurator_logged_result);
+
+  if (configurator_logged_result->tag == DDOG_LIBRARY_CONFIG_LOGGED_RESULT_ERR) {
+    ddog_Error err = configurator_logged_result->err;
+    VALUE message = get_error_details_and_drop(&err);
+    if (is_config_loaded()) {
+      log_warning(message);
+    } else {
+      log_warning_without_config(message);
+    }
+    RB_GC_GUARD(config_logged_result_rb);
+    return rb_hash_new();
+  }
+
+  VALUE logs = Qnil;
+  if (configurator_logged_result->ok.logs.length > 0) {
+    logs = rb_utf8_str_new_cstr(configurator_logged_result->ok.logs.ptr);
+  }
+
+  ddog_Vec_LibraryConfig config_vec = configurator_logged_result->ok.value;
+
+  VALUE local_config_hash = rb_hash_new();
+  VALUE fleet_config_hash = rb_hash_new();
+
+  bool local_config_id_set = false;
+  bool fleet_config_id_set = false;
+  VALUE local_hash = rb_hash_new();
+  VALUE fleet_hash = rb_hash_new();
+  for (uintptr_t i = 0; i < config_vec.len; i++) {
+    ddog_LibraryConfig config = config_vec.ptr[i];
+    VALUE selected_hash;
+    if (config.source == DDOG_LIBRARY_CONFIG_SOURCE_LOCAL_STABLE_CONFIG) {
+      selected_hash = local_config_hash;
+      if (!local_config_id_set) {
+        local_config_id_set = true;
+        if (config.config_id.length > 0) {
+          rb_hash_aset(local_hash, ID2SYM(rb_intern("id")), rb_utf8_str_new_cstr(config.config_id.ptr));
+        }
+      }
+    }
+    else {
+      selected_hash = fleet_config_hash;
+      if (!fleet_config_id_set) {
+        fleet_config_id_set = true;
+        if (config.config_id.length > 0) {
+          rb_hash_aset(fleet_hash, ID2SYM(rb_intern("id")), rb_utf8_str_new_cstr(config.config_id.ptr));
+        }
+      }
+    }
+
+    rb_hash_aset(selected_hash, rb_utf8_str_new_cstr(config.name.ptr), rb_utf8_str_new_cstr(config.value.ptr));
+  }
+
+  rb_hash_aset(local_hash, ID2SYM(rb_intern("config")), local_config_hash);
+  rb_hash_aset(fleet_hash, ID2SYM(rb_intern("config")), fleet_config_hash);
+
+  VALUE result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("logs")), logs);
+  rb_hash_aset(result, ID2SYM(rb_intern("local")), local_hash);
+  rb_hash_aset(result, ID2SYM(rb_intern("fleet")), fleet_hash);
+
+  RB_GC_GUARD(config_logged_result_rb);
+  return result;
+}

data/ext/libdatadog_api/library_config.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "datadog_ruby_common.h"
+
+void library_config_init(VALUE core_module);
+
+static inline bool is_config_loaded(void) {
+  VALUE datadog_module = rb_const_get(rb_cObject, rb_intern("Datadog"));
+  VALUE is_config_loaded = rb_funcall(datadog_module, rb_intern("configuration?"), 0);
+
+  return is_config_loaded == Qtrue;
+}
+
+static inline VALUE log_warning_without_config(VALUE warning) {
+  VALUE datadog_module = rb_const_get(rb_cObject, rb_intern("Datadog"));
+  VALUE logger = rb_funcall(datadog_module, rb_intern("logger_without_configuration"), 0);
+
+  return rb_funcall(logger, rb_intern("warn"), 1, warning);
+}
+
+static inline ddog_CStr cstr_from_ruby_string(VALUE string) {
+  ENFORCE_TYPE(string, T_STRING);
+  ddog_CStr cstr = {.ptr = RSTRING_PTR(string), .length = RSTRING_LEN(string)};
+  return cstr;
+}

data/ext/libdatadog_api/process_discovery.c

@@ -0,0 +1,118 @@
+#include <errno.h>
+#include <stdlib.h>
+#include <ruby.h>
+#include <datadog/library-config.h>
+
+#include "datadog_ruby_common.h"
+
+static VALUE _native_store_tracer_metadata(int argc, VALUE *argv, DDTRACE_UNUSED VALUE _self);
+static VALUE _native_to_rb_int(DDTRACE_UNUSED VALUE _self, VALUE tracer_memfd);
+static VALUE _native_close_tracer_memfd(DDTRACE_UNUSED VALUE _self, VALUE tracer_memfd, VALUE logger);
+
+static void tracer_memfd_free(void *ptr) {
+  int *fd = (int *)ptr;
+  if (*fd != -1) {
+    close(*fd);
+  }
+  ruby_xfree(ptr);
+}
+
+static const rb_data_type_t tracer_memfd_type = {
+  .wrap_struct_name = "Datadog::Core::ProcessDiscovery::TracerMemfd",
+  .function = {
+    .dfree = tracer_memfd_free,
+    .dsize = NULL,
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+void process_discovery_init(VALUE core_module) {
+  VALUE process_discovery_module = rb_define_module_under(core_module, "ProcessDiscovery");
+  VALUE tracer_memfd_class = rb_define_class_under(process_discovery_module, "TracerMemfd", rb_cObject);
+  rb_undef_alloc_func(tracer_memfd_class); // Class cannot be instantiated from Ruby
+
+  rb_define_module_function(process_discovery_module, "_native_store_tracer_metadata", _native_store_tracer_metadata, -1);
+  rb_define_module_function(process_discovery_module, "_native_to_rb_int", _native_to_rb_int, 1);
+  rb_define_module_function(process_discovery_module, "_native_close_tracer_memfd", _native_close_tracer_memfd, 2);
+}
+
+static VALUE _native_store_tracer_metadata(int argc, VALUE *argv, VALUE self) {
+  VALUE logger;
+  VALUE options;
+  rb_scan_args(argc, argv, "1:", &logger, &options);
+  if (options == Qnil) options = rb_hash_new();
+
+  VALUE runtime_id = rb_hash_fetch(options, ID2SYM(rb_intern("runtime_id")));
+  VALUE tracer_language = rb_hash_fetch(options, ID2SYM(rb_intern("tracer_language")));
+  VALUE tracer_version = rb_hash_fetch(options, ID2SYM(rb_intern("tracer_version")));
+  VALUE hostname = rb_hash_fetch(options, ID2SYM(rb_intern("hostname")));
+  VALUE service_name = rb_hash_fetch(options, ID2SYM(rb_intern("service_name")));
+  VALUE service_env = rb_hash_fetch(options, ID2SYM(rb_intern("service_env")));
+  VALUE service_version = rb_hash_fetch(options, ID2SYM(rb_intern("service_version")));
+  VALUE process_tags = rb_hash_fetch(options, ID2SYM(rb_intern("process_tags")));
+  VALUE container_id = rb_hash_fetch(options, ID2SYM(rb_intern("container_id")));
+
+  ENFORCE_TYPE(runtime_id, T_STRING);
+  ENFORCE_TYPE(tracer_language, T_STRING);
+  ENFORCE_TYPE(tracer_version, T_STRING);
+  ENFORCE_TYPE(hostname, T_STRING);
+  ENFORCE_TYPE(service_name, T_STRING);
+  ENFORCE_TYPE(service_env, T_STRING);
+  ENFORCE_TYPE(service_version, T_STRING);
+  ENFORCE_TYPE(process_tags, T_STRING);
+  ENFORCE_TYPE(container_id, T_STRING);
+
+  void* builder = ddog_tracer_metadata_new();
+
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_RUNTIME_ID, StringValueCStr(runtime_id));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_TRACER_LANGUAGE, StringValueCStr(tracer_language));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_TRACER_VERSION, StringValueCStr(tracer_version));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_HOSTNAME, StringValueCStr(hostname));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_SERVICE_NAME, StringValueCStr(service_name));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_SERVICE_ENV, StringValueCStr(service_env));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_SERVICE_VERSION, StringValueCStr(service_version));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_PROCESS_TAGS, StringValueCStr(process_tags));
+  ddog_tracer_metadata_set(builder, DDOG_METADATA_KIND_CONTAINER_ID, StringValueCStr(container_id));
+
+  ddog_Result_TracerMemfdHandle result = ddog_tracer_metadata_store(builder);
+  ddog_tracer_metadata_free(builder);
+
+  if (result.tag == DDOG_RESULT_TRACER_MEMFD_HANDLE_ERR_TRACER_MEMFD_HANDLE) {
+    rb_funcall(logger, rb_intern("debug"), 1, rb_sprintf("Failed to store the tracer configuration in a memory file descriptor: %"PRIsVALUE, get_error_details_and_drop(&result.err)));
+    return Qnil;
+  }
+
+  // &result.ok is a ddog_TracerMemfdHandle, which is a struct only containing int fd, which is a file descriptor
+  // We should just return the fd
+  int *fd = ruby_xmalloc(sizeof(int));
+
+  *fd = result.ok.fd;
+  VALUE tracer_memfd_class = rb_const_get(self, rb_intern("TracerMemfd"));
+  VALUE tracer_memfd = TypedData_Wrap_Struct(tracer_memfd_class, &tracer_memfd_type, fd);
+  return tracer_memfd;
+}
+
+static VALUE _native_to_rb_int(DDTRACE_UNUSED VALUE _self, VALUE tracer_memfd) {
+  int *fd;
+  TypedData_Get_Struct(tracer_memfd, int, &tracer_memfd_type, fd);
+  return INT2NUM(*fd);
+}
+
+static VALUE _native_close_tracer_memfd(DDTRACE_UNUSED VALUE _self, VALUE tracer_memfd, VALUE logger) {
+  int *fd;
+  TypedData_Get_Struct(tracer_memfd, int, &tracer_memfd_type, fd);
+  if (*fd == -1) {
+    rb_funcall(logger, rb_intern("debug"), 1, rb_sprintf("The tracer configuration memory file descriptor has already been closed"));
+    return Qnil;
+  }
+
+  int close_result = close(*fd);
+  *fd = -1;
+
+  if (close_result == -1) {
+    rb_funcall(logger, rb_intern("debug"), 1, rb_sprintf("Failed to close the tracer configuration memory file descriptor: %s", strerror(errno)));
+    return Qnil;
+  }
+
+  return Qnil;
+}

data/ext/libdatadog_api/process_discovery.h

@@ -0,0 +1,5 @@
+#pragma once
+
+#include "datadog_ruby_common.h"
+
+void process_discovery_init(VALUE core_module);

data/ext/libdatadog_extconf_helpers.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'pathname'
+
+module Datadog
+  # Contains a bunch of shared helpers that get used during building of extensions that link to libdatadog
+  #
+  # Note: Specs for this file currently live in `spec/datadog/profiling/native_extension_helpers_spec.rb`.
+  module LibdatadogExtconfHelpers
+    # Used to make sure the correct gem version gets loaded, as extconf.rb does not get run with "bundle exec" and thus
+    # may see multiple libdatadog versions. See https://github.com/DataDog/dd-trace-rb/pull/2531 for the horror story.
+    LIBDATADOG_VERSION = '~> 23.0.0.1.0'
+
+    # Used as an workaround for a limitation with how dynamic linking works in environments where the datadog gem and
+    # libdatadog are moved after the extension gets compiled.
+    #
+    # Because the libdatadog 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
+    # native extensions), 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 datadog_profiling_native_extension.2.7.3_x86_64-linux.so`.
+    #
+    # In older versions of the datadog gem, 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 datadog gem 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
+    # native extensions are 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:,
+      libdatadog_pkgconfig_folder: Libdatadog.pkgconfig_folder
+    )
+      return unless libdatadog_pkgconfig_folder
+
+      native_lib_folder = "#{current_folder}/../../lib/"
+      libdatadog_lib_folder = "#{libdatadog_pkgconfig_folder}/../"
+
+      Pathname.new(libdatadog_lib_folder).relative_path_from(Pathname.new(native_lib_folder)).to_s
+    end
+
+    # In https://github.com/DataDog/dd-trace-rb/pull/3582 we got a report of a customer for which the native extension
+    # only got installed into the extensions folder.
+    #
+    # But then this fix was not enough to fully get them moving because then they started to see the issue from
+    # https://github.com/DataDog/dd-trace-rb/issues/2067 / https://github.com/DataDog/dd-trace-rb/pull/2125 :
+    #
+    # > Profiling was requested but is not supported, profiling disabled: There was an error loading the profiling
+    # > native extension due to 'RuntimeError Failure to load datadog_profiling_native_extension.3.2.2_x86_64-linux
+    # > due to libdatadog_profiling.so: cannot open shared object file: No such file or directory
+    #
+    # The problem is that when loading the native extension from the extensions directory, the relative rpath we add
+    # with the #libdatadog_folder_relative_to_native_lib_folder helper above is not correct, we need to add a relative
+    # rpath to the extensions directory.
+    #
+    # So how do we find the full path where the native extension is placed?
+    # * From https://github.com/ruby/ruby/blob/83f02d42e0a3c39661dc99c049ab9a70ff227d5b/lib/bundler/runtime.rb#L166
+    #   `extension_dirs = Dir["#{Gem.dir}/extensions/*/*/*"] + Dir["#{Gem.dir}/bundler/gems/extensions/*/*/*"]`
+    #   we get that's in one of two fixed subdirectories of `Gem.dir`
+    # * From https://github.com/ruby/ruby/blob/83f02d42e0a3c39661dc99c049ab9a70ff227d5b/lib/rubygems/basic_specification.rb#L111-L115
+    #   we get the structure of the subdirectory (platform/extension_api_version/gem_and_version)
+    #
+    # Thus, `Gem.dir` of `/var/app/current/vendor/bundle/ruby/3.2.0` becomes (for instance)
+    # `/var/app/current/vendor/bundle/ruby/3.2.0/extensions/x86_64-linux/3.2.0/datadog-2.0.0/` or
+    # `/var/app/current/vendor/bundle/ruby/3.2.0/bundler/gems/extensions/x86_64-linux/3.2.0/datadog-2.0.0/`
+    #
+    # We then compute the relative path between these folders and the libdatadog folder, and use that as a relative path.
+    def self.libdatadog_folder_relative_to_ruby_extensions_folders(
+      gem_dir: Gem.dir,
+      libdatadog_pkgconfig_folder: Libdatadog.pkgconfig_folder
+    )
+      return unless libdatadog_pkgconfig_folder
+
+      # For the purposes of calculating a folder relative to the other, we don't actually NEED to fill in the
+      # platform, extension_api_version and gem version. We're basically just after how many folders it is deep from
+      # the Gem.dir.
+      expected_ruby_extensions_folders = [
+        "#{gem_dir}/extensions/platform/extension_api_version/datadog_version/",
+        "#{gem_dir}/bundler/gems/extensions/platform/extension_api_version/datadog_version/",
+      ]
+      libdatadog_lib_folder = "#{libdatadog_pkgconfig_folder}/../"
+
+      expected_ruby_extensions_folders.map do |folder|
+        Pathname.new(libdatadog_lib_folder).relative_path_from(Pathname.new(folder)).to_s
+      end
+    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) # standard:disable Style/GlobalVars
+      pkg_config_available = command && xsystem("#{command} --version")
+
+      pkg_config_available != true
+    end
+
+    def self.try_loading_libdatadog
+      gem 'libdatadog', LIBDATADOG_VERSION
+      require 'libdatadog'
+      nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      if block_given?
+        yield e
+      else
+        e
+      end
+    end
+
+    # Note: This helper is currently only used in the `libdatadog_api/extconf.rb` BUT still lives here to enable testing.
+    def self.load_libdatadog_or_get_issue
+      try_loading_libdatadog do |exception|
+        return "There was an error loading `libdatadog`: #{exception.class} #{exception.message}"
+      end
+
+      unless Libdatadog.pkgconfig_folder
+        "The `libdatadog` gem installed on your system is missing binaries for your platform variant. " \
+          "Your platform: " \
+          "`#{Libdatadog.current_platform}`; available binaries: `#{Libdatadog.available_binaries.join("`, `")}`"
+      end
+    end
+  end
+end