datadog 2.4.0 → 2.44.0

data/ext/datadog_profiling_native_extension/stack_recorder.h

@@ -3,17 +3,26 @@
 #include <datadog/profiling.h>
 #include <ruby.h>
 
+typedef struct {
+  // In: The object being allocated, and its class. (Its weight is the `alloc_samples` in `sample_values` below.)
+  VALUE new_object;
+  ddog_CharSlice alloc_class;
+  // Out: Set by `record_sample` to whether a `recorder_commit_heap_recordings_may_lose_gvl` callback is needed
+  bool out_needs_commit;
+} heap_sample_values;
+
 typedef struct {
   int64_t cpu_time_ns;
   int64_t wall_time_ns;
   uint32_t cpu_or_wall_samples;
   uint32_t alloc_samples;
   uint32_t alloc_samples_unscaled;
-  bool heap_sample;
   int64_t timeline_wall_time_ns;
+  // When not NULL, this sample also gets recorded for heap profiling
+  heap_sample_values *heap_sample;
 } sample_values;
 
-typedef struct sample_labels {
+typedef struct {
   ddog_prof_Slice_Label labels;
 
   // This is used to allow the `Collectors::Stack` to modify the existing label, if any. This MUST be NULL or point
@@ -26,5 +35,7 @@ typedef struct sample_labels {
 
 void record_sample(VALUE recorder_instance, ddog_prof_Slice_Location locations, sample_values values, sample_labels labels);
 void record_endpoint(VALUE recorder_instance, uint64_t local_root_span_id, ddog_CharSlice endpoint);
-void track_object(VALUE recorder_instance, VALUE new_object, unsigned int sample_weight, ddog_CharSlice *alloc_class);
+void recorder_commit_heap_recordings_may_lose_gvl(VALUE recorder_instance);
+void recorder_heap_update_may_lose_gvl(VALUE recorder_instance);
+void recorder_install_on_serialize(VALUE recorder_instance, VALUE thread_context_collector_instance);
 VALUE enforce_recorder_instance(VALUE object);

data/ext/datadog_profiling_native_extension/time_helpers.h

@@ -4,22 +4,24 @@
 #include <errno.h>
 #include <time.h>
 
-#include "extconf.h" // Needed for HAVE_CLOCK_MONOTONIC_COARSE
+#include "extconf.h"
 #include "ruby_helpers.h"
 
-#define SECONDS_AS_NS(value) (value * 1000 * 1000 * 1000L)
-#define MILLIS_AS_NS(value) (value * 1000 * 1000L)
+#define SECONDS_AS_NS(value) ((value) * 1000L * 1000L * 1000L)
+#define MILLIS_AS_NS(value)  ((value) * 1000L * 1000L)
+#define MICROS_AS_NS(value)  ((value) * 1000L)
 
 typedef enum { RAISE_ON_FAILURE, DO_NOT_RAISE_ON_FAILURE } raise_on_failure_setting;
 
 #define INVALID_TIME -1
 
 typedef struct {
+  // INVALID_TIME until the first conversion, and the only field used to decide if the state needs to be (re)computed
   long system_epoch_ns_reference;
   long delta_to_epoch_ns;
 } monotonic_to_system_epoch_state;
 
-#define MONOTONIC_TO_SYSTEM_EPOCH_INITIALIZER {.system_epoch_ns_reference = INVALID_TIME, .delta_to_epoch_ns = INVALID_TIME}
+#define MONOTONIC_TO_SYSTEM_EPOCH_INITIALIZER {.system_epoch_ns_reference = INVALID_TIME}
 
 static inline long retrieve_clock_as_ns(clockid_t clock_id, raise_on_failure_setting raise_on_failure) {
   struct timespec clock_value;
@@ -32,25 +34,30 @@ static inline long retrieve_clock_as_ns(clockid_t clock_id, raise_on_failure_set
   return clock_value.tv_nsec + SECONDS_AS_NS(clock_value.tv_sec);
 }
 
-static inline long monotonic_wall_time_now_ns(raise_on_failure_setting raise_on_failure) { return retrieve_clock_as_ns(CLOCK_MONOTONIC, raise_on_failure); }
+// CLOCK_MONOTONIC on macOS only has microsecond precision, CLOCK_MONOTONIC_RAW has nanosecond precision
+#ifdef __APPLE__
+  #define CLOCK_MONOTONIC_FOR_PROFILING CLOCK_MONOTONIC_RAW
+  #define CLOCK_MONOTONIC_COARSE_FOR_PROFILING CLOCK_MONOTONIC_RAW_APPROX
+#else
+  #define CLOCK_MONOTONIC_FOR_PROFILING CLOCK_MONOTONIC
+  #define CLOCK_MONOTONIC_COARSE_FOR_PROFILING CLOCK_MONOTONIC_COARSE
+#endif
+
+static inline long monotonic_wall_time_now_ns(raise_on_failure_setting raise_on_failure) { return retrieve_clock_as_ns(CLOCK_MONOTONIC_FOR_PROFILING, raise_on_failure); }
 static inline long system_epoch_time_now_ns(raise_on_failure_setting raise_on_failure)   { return retrieve_clock_as_ns(CLOCK_REALTIME,  raise_on_failure); }
 
 // Coarse instants use CLOCK_MONOTONIC_COARSE on Linux which is expected to provide resolution in the millisecond range:
 // https://docs.redhat.com/en/documentation/red_hat_enterprise_linux_for_real_time/7/html/reference_guide/sect-posix_clocks#Using_clock_getres_to_compare_clock_resolution
 // We introduce here a separate type for it, so as to make it harder to misuse/more explicit when these timestamps are used
 
-typedef struct coarse_instant {
+typedef struct {
   long timestamp_ns;
 } coarse_instant;
 
 static inline coarse_instant to_coarse_instant(long timestamp_ns) { return (coarse_instant) {.timestamp_ns = timestamp_ns}; }
 
 static inline coarse_instant monotonic_coarse_wall_time_now_ns(void) {
- #ifdef HAVE_CLOCK_MONOTONIC_COARSE // Linux
-    return to_coarse_instant(retrieve_clock_as_ns(CLOCK_MONOTONIC_COARSE, DO_NOT_RAISE_ON_FAILURE));
-  #else // macOS
-    return to_coarse_instant(retrieve_clock_as_ns(CLOCK_MONOTONIC, DO_NOT_RAISE_ON_FAILURE));
-  #endif
+  return to_coarse_instant(retrieve_clock_as_ns(CLOCK_MONOTONIC_COARSE_FOR_PROFILING, DO_NOT_RAISE_ON_FAILURE));
 }
 
 long monotonic_to_system_epoch_ns(monotonic_to_system_epoch_state *state, long monotonic_wall_time_ns);

data/ext/datadog_profiling_native_extension/unsafe_api_calls_check.c

@@ -0,0 +1,48 @@
+#include <ruby.h>
+#include <ruby/debug.h>
+#include <stdbool.h>
+
+#include "datadog_ruby_common.h"
+#include "ruby_helpers.h"
+#include "unsafe_api_calls_check.h"
+#include "extconf.h"
+
+static bool inside_unsafe_context = false;
+
+#ifndef NO_POSTPONED_TRIGGER
+  static rb_postponed_job_handle_t check_for_unsafe_api_calls_handle;
+#endif
+
+static void check_for_unsafe_api_calls(DDTRACE_UNUSED void *_unused);
+
+void unsafe_api_calls_check_init(void) {
+  #ifndef NO_POSTPONED_TRIGGER
+    int unused_flags = 0;
+
+    check_for_unsafe_api_calls_handle = rb_postponed_job_preregister(unused_flags, check_for_unsafe_api_calls, NULL);
+
+   if (check_for_unsafe_api_calls_handle == POSTPONED_JOB_HANDLE_INVALID) {
+     raise_error(rb_eRuntimeError, "Failed to register check_for_unsafe_api_calls_handle postponed job (got POSTPONED_JOB_HANDLE_INVALID)");
+   }
+  #endif
+}
+
+void debug_enter_unsafe_context(void) {
+  inside_unsafe_context = true;
+
+  #ifndef NO_POSTPONED_TRIGGER
+    rb_postponed_job_trigger(check_for_unsafe_api_calls_handle);
+  #else
+    rb_postponed_job_register(0, check_for_unsafe_api_calls, NULL);
+  #endif
+}
+
+void debug_leave_unsafe_context(void) {
+  inside_unsafe_context = false;
+}
+
+static void check_for_unsafe_api_calls(DDTRACE_UNUSED void *_unused) {
+  if (inside_unsafe_context) rb_bug(
+    "Datadog Ruby profiler detected callback nested inside sample. Please report this at https://github.com/datadog/dd-trace-rb/blob/master/CONTRIBUTING.md#found-a-bug"
+  );
+}

data/ext/datadog_profiling_native_extension/unsafe_api_calls_check.h

@@ -0,0 +1,36 @@
+#pragma once
+
+// This checker is used to detect accidental thread scheduling switching points happening during profiling sampling.
+//
+// Specifically, when the profiler is sampling, we're never supposed to call into Ruby code (e.g. methods
+// implemented using Ruby code) or allocate Ruby objects.
+// That's because those events introduce thread switch points, and really we don't want the VM switching between threads
+// in the middle of the profiler sampling. This includes raising exceptions.
+//
+// Raising exceptions as the very last operation, to stop the profiler is ok, but comes a caveat: raising exceptions
+// will fail the unsafe check. When testing exception paths, you must disable unsafe checking for that test execution.
+// See `allow_exception` usage for how to we disable it for testing today.
+//
+// The above is especially true in situations such as GC profiling or allocation/heap profiling, as in those situations
+// we can even crash the Ruby VM if we switch away at the wrong time.
+//
+// The below APIs can be used to detect these situations. They work by relying on the following observation:
+// in most (all?) thread switch points, Ruby will check for interrupts and run the postponed jobs.
+//
+// Thus, if we set a flag while we're sampling (inside_unsafe_context), trigger the postponed job, and then only unset
+// the flag after sampling, the correct thing to happen is that the postponed job should never see the flag.
+//
+// If, however, we have a bug and there's a thread switch point, our postponed job will see the flag and immediately
+// stop the Ruby VM before further damage happens (and hopefully giving us a stack trace clearly pointing to the culprit).
+//
+// Note that this check currently does not detect Ruby object allocations, as those do not check for interrupts.
+
+void unsafe_api_calls_check_init(void);
+
+// IMPORTANT: This method **MUST** only be called from test code, as it causes an immediate hard-crash on the Ruby VM
+// when it detects a potential issue, and that's not something we want for production apps.
+//
+// In the future we may introduce some kind of setting (off by default) to also allow this to be safely be used
+// in production code if needed.
+void debug_enter_unsafe_context(void);
+void debug_leave_unsafe_context(void);

data/ext/libdatadog_api/crashtracker.c

@@ -2,27 +2,27 @@
 #include <datadog/crashtracker.h>
 
 #include "datadog_ruby_common.h"
+#include "helpers.h"
 
 static VALUE _native_start_or_update_on_fork(int argc, VALUE *argv, DDTRACE_UNUSED VALUE _self);
 static VALUE _native_stop(DDTRACE_UNUSED VALUE _self);
-static void crashtracker_init(VALUE crashtracking_module);
+
+void crashtracker_report_exception_init(VALUE crashtracker_class);
+
+static bool first_init = true;
 
 // Used to report Ruby VM crashes.
 // Once initialized, segfaults will be reported automatically using libdatadog.
 
-void DDTRACE_EXPORT Init_libdatadog_api(void) {
-  VALUE datadog_module = rb_define_module("Datadog");
-  VALUE core_module = rb_define_module_under(datadog_module, "Core");
+void crashtracker_init(VALUE core_module) {
   VALUE crashtracking_module = rb_define_module_under(core_module, "Crashtracking");
-
-  crashtracker_init(crashtracking_module);
-}
-
-void crashtracker_init(VALUE crashtracking_module) {
   VALUE crashtracker_class = rb_define_class_under(crashtracking_module, "Component", rb_cObject);
 
   rb_define_singleton_method(crashtracker_class, "_native_start_or_update_on_fork", _native_start_or_update_on_fork, -1);
   rb_define_singleton_method(crashtracker_class, "_native_stop", _native_stop, 0);
+
+  // Initialize Ruby non-signal-crash reporting
+  crashtracker_report_exception_init(crashtracker_class);
 }
 
 static VALUE _native_start_or_update_on_fork(int argc, VALUE *argv, DDTRACE_UNUSED VALUE _self) {
@@ -47,32 +47,33 @@ static VALUE _native_start_or_update_on_fork(int argc, VALUE *argv, DDTRACE_UNUS
   ENFORCE_TYPE(action, T_SYMBOL);
   ENFORCE_TYPE(upload_timeout_seconds, T_FIXNUM);
 
-  if (action != start_action && action != update_on_fork_action) rb_raise(rb_eArgError, "Unexpected action: %+"PRIsVALUE, action);
+  if (action != start_action && action != update_on_fork_action) raise_error(rb_eArgError, "Unexpected action: %+"PRIsVALUE, action);
 
   VALUE version = datadog_gem_version();
 
-  // Tags and endpoint are heap-allocated, so after here we can't raise exceptions otherwise we'll leak this memory
+  // Tags are heap-allocated, so after here we can't raise exceptions otherwise we'll leak this memory
   // Start of exception-free zone to prevent leaks {{
-  ddog_Endpoint *endpoint = ddog_endpoint_from_url(char_slice_from_ruby_string(agent_base_url));
   ddog_Vec_Tag tags = convert_tags(tags_as_array);
 
   ddog_crasht_Config config = {
     .additional_files = {},
-    // The Ruby VM already uses an alt stack to detect stack overflows so the crash handler must not overwrite it.
+    // @ivoanjo: The Ruby VM already uses an alt stack to detect stack overflows.
     //
-    // @ivoanjo: Specifically, with `create_alt_stack = true` I saw a segfault, such as Ruby 2.6's bug with
+    // In libdatadog < 14 with `create_alt_stack = true` I saw a segfault, such as Ruby 2.6's bug with
     // "Process.detach(fork { exit! }).instance_variable_get(:@foo)" being turned into a
     // "-e:1:in `instance_variable_get': stack level too deep (SystemStackError)" by Ruby.
-    //
     // The Ruby crash handler also seems to get confused when this option is enabled and
     // "Process.kill('SEGV', Process.pid)" gets run.
+    //
+    // This actually changed in libdatadog 14, so I could see no issues with `create_alt_stack = true`, but not
+    // overriding what Ruby set up seems a saner default to keep anyway.
     .create_alt_stack = false,
-    .endpoint = endpoint,
+    .use_alt_stack = true,
+    .endpoint = {.url = char_slice_from_ruby_string(agent_base_url)},
     .resolve_frames = DDOG_CRASHT_STACKTRACE_COLLECTION_ENABLED_WITH_SYMBOLS_IN_RECEIVER,
-    .timeout_secs = FIX2INT(upload_timeout_seconds),
-    // Waits for crash tracker to finish reporting the issue before letting the Ruby process die; see
-    // https://github.com/DataDog/libdatadog/pull/477 for details
-    .wait_for_receiver = true,
+    .timeout_ms = FIX2INT(upload_timeout_seconds) * 1000,
+    .collect_all_threads = true,
+    .max_threads = 128,
   };
 
   ddog_crasht_Metadata metadata = {
@@ -95,29 +96,31 @@ static VALUE _native_start_or_update_on_fork(int argc, VALUE *argv, DDTRACE_UNUS
     .optional_stdout_filename = {},
   };
 
-  ddog_crasht_Result result =
+  ddog_VoidResult result =
     action == start_action ?
-      ddog_crasht_init_with_receiver(config, receiver_config, metadata) :
+      (first_init ?
+        ddog_crasht_init(config, receiver_config, metadata) :
+        ddog_crasht_reconfigure(config, receiver_config, metadata)
+      ) :
       ddog_crasht_update_on_fork(config, receiver_config, metadata);
 
+  // We use first_init to know which of [init, reconfigure] needs to be called. BUT if init failed we actually need
+  // to call init next time again, not reconfigure.
+  if (result.tag == DDOG_VOID_RESULT_OK) first_init = false;
+
   // Clean up before potentially raising any exceptions
   ddog_Vec_Tag_drop(tags);
-  ddog_endpoint_drop(endpoint);
   // }} End of exception-free zone to prevent leaks
 
-  if (result.tag == DDOG_CRASHT_RESULT_ERR) {
-    rb_raise(rb_eRuntimeError, "Failed to start/update the crash tracker: %"PRIsVALUE, get_error_details_and_drop(&result.err));
-  }
+  CHECK_VOID_RESULT("Failed to start/update the crash tracker", result);
 
   return Qtrue;
 }
 
 static VALUE _native_stop(DDTRACE_UNUSED VALUE _self) {
-  ddog_crasht_Result result = ddog_crasht_shutdown();
+  ddog_VoidResult result = ddog_crasht_disable();
 
-  if (result.tag == DDOG_CRASHT_RESULT_ERR) {
-    rb_raise(rb_eRuntimeError, "Failed to stop the crash tracker: %"PRIsVALUE, get_error_details_and_drop(&result.err));
-  }
+  CHECK_VOID_RESULT("Failed to stop the crash tracker", result);
 
   return Qtrue;
 }

data/ext/libdatadog_api/crashtracker.h

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

data/ext/libdatadog_api/crashtracker_report_exception.c

@@ -0,0 +1,126 @@
+#include <datadog/common.h>
+#include <datadog/crashtracker.h>
+#include <ruby.h>
+
+#include "datadog_ruby_common.h"
+
+static VALUE _native_report_ruby_exception(VALUE _self, VALUE exception_type,
+                                          VALUE message, VALUE frames_data);
+
+static bool process_crash_frames(VALUE frames_data, ddog_crasht_Handle_StackTrace *stack_trace);
+
+void crashtracker_report_exception_init(VALUE crashtracker_class) {
+  rb_define_singleton_method(crashtracker_class, "_native_report_ruby_exception",
+                            _native_report_ruby_exception, 3);
+}
+
+static VALUE _native_report_ruby_exception(DDTRACE_UNUSED VALUE _self, VALUE exception_type,
+                                          VALUE message, VALUE frames_data) {
+  ENFORCE_TYPE(exception_type, T_STRING);
+  ENFORCE_TYPE(message, T_STRING);
+  ENFORCE_TYPE(frames_data, T_ARRAY);
+
+  // Build stack trace
+  ddog_crasht_StackTrace_NewResult stack_result = ddog_crasht_StackTrace_new();
+  if (stack_result.tag != DDOG_CRASHT_STACK_TRACE_NEW_RESULT_OK) {
+    ddog_Error_drop(&stack_result.err);
+    return Qfalse;
+  }
+
+  ddog_crasht_Handle_StackTrace *stack_trace = &stack_result.ok;
+
+  bool frames_ok = process_crash_frames(frames_data, stack_trace);
+  if (frames_ok) {
+    ddog_VoidResult complete_result = ddog_crasht_StackTrace_set_complete(stack_trace);
+    if (complete_result.tag != DDOG_VOID_RESULT_OK) {
+      ddog_crasht_StackTrace_drop(stack_trace);
+      ddog_Error_drop(&complete_result.err);
+      return Qfalse;
+    }
+  }
+
+  // ddog_crasht_report_unhandled_exception takes ownership of stack_trace
+  ddog_VoidResult result = ddog_crasht_report_unhandled_exception(
+    char_slice_from_ruby_string(exception_type),
+    char_slice_from_ruby_string(message),
+    stack_trace
+  );
+
+  if (result.tag != DDOG_VOID_RESULT_OK) {
+    ddog_Error_drop(&result.err);
+    return Qfalse;
+  }
+
+  return Qtrue;
+}
+
+static bool process_crash_frames(VALUE frames_data, ddog_crasht_Handle_StackTrace *stack_trace) {
+  size_t frame_count = RARRAY_LEN(frames_data);
+
+  // Return false and early so we can mark the stack as incomplete
+  // libdatadog's definition of an incomplete stack is that it has no frames
+  // or that report generation died in the middle of unwinding frames
+  if (frame_count == 0) {
+    return false;
+  }
+
+  for (size_t i = 0; i < frame_count; i++) {
+    VALUE frame_array = RARRAY_AREF(frames_data, i);
+
+    // ruby should guarantee [String, String, Integer]
+    if (!RB_TYPE_P(frame_array, T_ARRAY) || RARRAY_LEN(frame_array) != 3) {
+      // Malformed data from Ruby; this is a bug, bail out
+      return false;
+    }
+
+    VALUE file_val = RARRAY_AREF(frame_array, 0);
+    VALUE func_val = RARRAY_AREF(frame_array, 1);
+    VALUE line_val = RARRAY_AREF(frame_array, 2);
+
+    // validate types; Ruby should guarantee these
+    if (!RB_TYPE_P(file_val, T_STRING) || !RB_TYPE_P(func_val, T_STRING) || !RB_TYPE_P(line_val, T_FIXNUM)) {
+      // Type mismatch from Ruby; this is a bug, bail out
+      return false;
+    }
+
+    ddog_crasht_StackFrame_NewResult frame_result = ddog_crasht_StackFrame_new();
+    if (frame_result.tag != DDOG_CRASHT_STACK_FRAME_NEW_RESULT_OK) {
+      ddog_Error_drop(&frame_result.err);
+      return false;
+    }
+
+    ddog_crasht_Handle_StackFrame *frame = &frame_result.ok;
+
+    ddog_VoidResult file_result = ddog_crasht_StackFrame_with_file(frame, char_slice_from_ruby_string(file_val));
+    if (file_result.tag != DDOG_VOID_RESULT_OK) {
+      ddog_crasht_StackFrame_drop(frame);
+      ddog_Error_drop(&file_result.err);
+      return false;
+    }
+    ddog_VoidResult func_result = ddog_crasht_StackFrame_with_function(frame, char_slice_from_ruby_string(func_val));
+    if (func_result.tag != DDOG_VOID_RESULT_OK) {
+      ddog_crasht_StackFrame_drop(frame);
+      ddog_Error_drop(&func_result.err);
+      return false;
+    }
+
+    uint32_t line = (uint32_t)FIX2INT(line_val);
+    if (line > 0) {
+      ddog_VoidResult line_result = ddog_crasht_StackFrame_with_line(frame, line);
+      if (line_result.tag != DDOG_VOID_RESULT_OK) {
+        ddog_crasht_StackFrame_drop(frame);
+        ddog_Error_drop(&line_result.err);
+        return false;
+      }
+    }
+
+    ddog_VoidResult push_result = ddog_crasht_StackTrace_push_frame(stack_trace, frame, true);
+    if (push_result.tag != DDOG_VOID_RESULT_OK) {
+      ddog_crasht_StackFrame_drop(frame);
+      ddog_Error_drop(&push_result.err);
+      return false;
+    }
+  }
+
+  return true;
+}

data/ext/libdatadog_api/datadog_ruby_common.c

@@ -1,21 +1,51 @@
 #include "datadog_ruby_common.h"
+#include <stdarg.h>
 
 // IMPORTANT: Currently this file is copy-pasted between extensions. Make sure to update all versions when doing any change!
 
-void raise_unexpected_type(VALUE value, const char *value_name, const char *type_name, const char *file, int line, const char* function_name) {
-  rb_exc_raise(
-    rb_exc_new_str(
-      rb_eTypeError,
-      rb_sprintf("wrong argument %"PRIsVALUE" for '%s' (expected a %s) at %s:%d:in `%s'",
-        rb_inspect(value),
-        value_name,
-        type_name,
-        file,
-        line,
-        function_name
-      )
+static ID telemetry_message_id;
+
+void raise_unexpected_type(VALUE value, const char *value_name, const char *type_name, const char *file, int line, const char *function_name) {
+  // All of the below come from `ENFORCE_TYPE` and are constant for their call-site
+  VALUE simple_message = rb_sprintf("wrong argument for '%s' (expected a %s) at %s:%d:in `%s'",
+    value_name,
+    type_name,
+    file,
+    line,
+    function_name
+  );
+  VALUE exception = rb_exc_new_str(
+    rb_eTypeError,
+    rb_sprintf("wrong argument %"PRIsVALUE" for '%s' (expected a %s) at %s:%d:in `%s'",
+      rb_inspect(value),
+      value_name,
+      type_name,
+      file,
+      line,
+      function_name
     )
   );
+  rb_ivar_set(exception, telemetry_message_id, simple_message);
+  rb_exc_raise(exception);
+}
+
+// Raises an exception with separate telemetry-safe and detailed messages.
+// NOTE: Raising an exception always invokes Ruby code so it requires the GVL and is not compatible with "debug_enter_unsafe_context".
+// @see debug_enter_unsafe_context
+void private_raise_exception(VALUE exception, const char *static_message) {
+  rb_ivar_set(exception, telemetry_message_id, rb_str_new_cstr(static_message));
+  rb_exc_raise(exception);
+}
+
+// Use `raise_error` the macro instead, as it provides additional argument checks.
+void private_raise_error(VALUE exception_class, const char *fmt, ...) {
+  va_list args;
+  va_start(args, fmt);
+  VALUE detailed_message = rb_vsprintf(fmt, args);
+  va_end(args);
+
+  VALUE exception = rb_exc_new_str(exception_class, detailed_message);
+  private_raise_exception(exception, fmt);
 }
 
 VALUE datadog_gem_version(void) {
@@ -29,10 +59,7 @@ VALUE datadog_gem_version(void) {
 }
 
 static VALUE log_failure_to_process_tag(VALUE err_details) {
-  VALUE datadog_module = rb_const_get(rb_cObject, rb_intern("Datadog"));
-  VALUE logger = rb_funcall(datadog_module, rb_intern("logger"), 0);
-
-  return rb_funcall(logger, rb_intern("warn"), 1, rb_sprintf("Failed to convert tag: %"PRIsVALUE, err_details));
+  return log_warning(rb_sprintf("Failed to convert tag: %"PRIsVALUE, err_details));
 }
 
 __attribute__((warn_unused_result))
@@ -81,3 +108,45 @@ ddog_Vec_Tag convert_tags(VALUE tags_as_array) {
 
   return tags;
 }
+
+size_t read_ddogerr_string_and_drop(ddog_Error *error, char *string, size_t capacity) {
+  if (capacity == 0 || string == NULL) {
+    // short-circuit, we can't write anything
+    ddog_Error_drop(error);
+    return 0;
+  }
+
+  ddog_CharSlice error_msg_slice = ddog_Error_message(error);
+  size_t error_msg_size = error_msg_slice.len;
+  // Account for extra null char for proper cstring
+  if (error_msg_size >= capacity) {
+    // Error message too big, lets truncate it to capacity - 1 to allow for extra null at end
+    error_msg_size = capacity - 1;
+  }
+  strncpy(string, error_msg_slice.ptr, error_msg_size);
+  string[error_msg_size] = '\0';
+  ddog_Error_drop(error);
+  return error_msg_size;
+}
+
+static void verify_libdatadog_version(void) {
+  rb_eval_string(
+    "require 'libdatadog';"
+    "expected = '" EXPECTED_LIBDATADOG_VERSION "';"
+    "if expected != Libdatadog::VERSION;"
+      "raise(LoadError, <<MSG\n"
+        "The `datadog` gem needs to be reinstalled whenever the `libdatadog` gem version is changed. "
+        "The currently-installed version of `datadog` was built to work with `libdatadog` gem version #{expected} "
+        "but the currently-loaded version of `libdatadog` is #{Libdatadog::VERSION}. "
+        "To fix this, reinstall the `datadog` gem (e.g. `bundle exec gem pristine datadog`) "
+        "or contact Datadog support for help at <https://docs.datadoghq.com/help/>.\n"
+        "MSG\n"
+      ");"
+    "end"
+  );
+}
+
+void datadog_ruby_common_init(void) {
+  telemetry_message_id = rb_intern("@telemetry_message");
+  verify_libdatadog_version();
+}

data/ext/libdatadog_api/datadog_ruby_common.h

@@ -3,7 +3,17 @@
 // IMPORTANT: Currently this file is copy-pasted between extensions. Make sure to update all versions when doing any change!
 
 #include <ruby.h>
-#include <datadog/profiling.h>
+#include <datadog/common.h>
+
+// All recommended backward compatible macros for keyword argument functions can be found here:
+// https://github.com/ruby/ruby/blob/master/doc/extension.rdoc#defining-backward-compatible-macros-for-keyword-argument-functions
+#ifndef RB_PASS_KEYWORDS
+/* Only define macros on Ruby <2.7 */
+#define rb_funcallv_kw(o, m, c, v, kw) rb_funcallv(o, m, c, v)
+#endif
+
+// Must be called once during initialization
+void datadog_ruby_common_init(void);
 
 // Used to mark symbols to be exported to the outside of the extension.
 // Consider very carefully before tagging a function with this.
@@ -27,8 +37,32 @@
 #define ENFORCE_BOOLEAN(value) \
   { if (RB_UNLIKELY(value != Qtrue && value != Qfalse)) raise_unexpected_type(value, ADD_QUOTES(value), "true or false", __FILE__, __LINE__, __func__); }
 
+#define ENFORCE_TYPED_DATA(value, type) \
+  { if (RB_UNLIKELY(!rb_typeddata_is_kind_of(value, type))) raise_unexpected_type(value, ADD_QUOTES(value), "TypedData of type " ADD_QUOTES(type), __FILE__, __LINE__, __func__); }
+
 NORETURN(void raise_unexpected_type(VALUE value, const char *value_name, const char *type_name, const char *file, int line, const char* function_name));
 
+// Raises an exception of the specified class with the formatted string as its message.
+// This macro ensures that the literal string is sent for telemetry, while the formatted
+// message is the default `Exception#message`.
+// *Ruby exceptions not raised through this function will not be reported via telemetry.*
+#define raise_error(exception_class, fmt, ...) \
+  private_raise_error(exception_class, "" fmt, ##__VA_ARGS__)
+
+NORETURN(
+  void private_raise_error(VALUE exception_class, const char *fmt, ...)
+  __attribute__ ((format (printf, 2, 3)));
+);
+
+// Raises an exception with separate telemetry-safe and detailed messages.
+// NOTE: Raising an exception always invokes Ruby code so it requires the GVL and is not compatible with "debug_enter_unsafe_context".
+// @see debug_enter_unsafe_context
+NORETURN(
+  void private_raise_exception(VALUE exception, const char *static_message)
+);
+
+#define MAX_RAISE_MESSAGE_SIZE 256
+
 // Helper to retrieve Datadog::VERSION::STRING
 VALUE datadog_gem_version(void);
 
@@ -38,6 +72,13 @@ static inline ddog_CharSlice char_slice_from_ruby_string(VALUE string) {
   return char_slice;
 }
 
+static inline VALUE log_warning(VALUE warning) {
+  VALUE datadog_module = rb_const_get(rb_cObject, rb_intern("Datadog"));
+  VALUE logger = rb_funcall(datadog_module, rb_intern("logger"), 0);
+
+  return rb_funcall(logger, rb_intern("warn"), 1, warning);
+}
+
 __attribute__((warn_unused_result))
 ddog_Vec_Tag convert_tags(VALUE tags_as_array);
 
@@ -51,3 +92,8 @@ static inline VALUE get_error_details_and_drop(ddog_Error *error) {
   ddog_Error_drop(error);
   return result;
 }
+
+// Utility function to be able to extract an error cstring from a ddog_Error.
+// Returns the amount of characters written to string (which are necessarily
+// bounded by capacity - 1 since the string will be null-terminated).
+size_t read_ddogerr_string_and_drop(ddog_Error *error, char *string, size_t capacity);