feat(crashtracking): unhandled exception reporting FFI (#1597)

gyuheon0h · web-flow · commit c8121f422d2c · 2026-02-20T23:43:54.000Z
# What does this PR do? Add FFI interface for reporting unhandled exception. Also adds tests for it. *The FFI examples test infra part is largely claude code driven* PR below on the stack: [feat(crashtracking): report unhandled exceptions](#1596) # Motivation What inspired you to submit this pull request? # Additional Notes Anything else we should know when reviewing? # How to test the change? Run ffi example tests Co-authored-by: gyuheon.oh <gyuheon.oh@datadoghq.com>
diff --git a/examples/ffi/CMakeLists.txt b/examples/ffi/CMakeLists.txt
@@ -65,6 +65,9 @@ set_vcruntime_link_type(telemetry_metrics ${VCRUNTIME_LINK_TYPE})
 if(NOT WIN32)
   add_executable(crashtracking crashtracking.c)
   target_link_libraries(crashtracking PRIVATE Datadog::Profiling)
+
+  add_executable(crashtracking_unhandled_exception crashtracking_unhandled_exception.c)
+  target_link_libraries(crashtracking_unhandled_exception PRIVATE Datadog::Profiling)
 endif()
 
 add_executable(trace_exporter trace_exporter.c)
diff --git a/examples/ffi/crashtracking_unhandled_exception.c b/examples/ffi/crashtracking_unhandled_exception.c
@@ -0,0 +1,185 @@
+// Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+//
+// FFI test for ddog_crasht_report_unhandled_exception.
+//
+// This test initializes the crashtracker (without a live signal handler),
+// builds a small runtime StackTrace, calls report_unhandled_exception, and
+// verifies that a crash report file is produced in the current directory.
+//
+// Usage:
+//   crashtracking_unhandled_exception [receiver_binary_path]
+//
+// The receiver binary path may also be supplied via the
+// DDOG_CRASHT_TEST_RECEIVER environment variable.  When run through
+// `cargo ffi-test` the variable is set automatically.
+
+#include <datadog/common.h>
+#include <datadog/crashtracker.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static ddog_CharSlice slice(const char *s) {
+  return (ddog_CharSlice){.ptr = s, .len = strlen(s)};
+}
+
+static void handle_void(ddog_VoidResult result, const char *ctx) {
+  if (result.tag != DDOG_VOID_RESULT_OK) {
+    ddog_CharSlice msg = ddog_Error_message(&result.err);
+    fprintf(stderr, "FAIL [%s]: %.*s\n", ctx, (int)msg.len, msg.ptr);
+    ddog_Error_drop(&result.err);
+    exit(EXIT_FAILURE);
+  }
+}
+
+static void push_named_frame(ddog_crasht_Handle_StackTrace *trace,
+                              const char *function_name, uintptr_t ip) {
+  ddog_crasht_StackFrame_NewResult fr = ddog_crasht_StackFrame_new();
+  if (fr.tag != DDOG_CRASHT_STACK_FRAME_NEW_RESULT_OK) {
+    ddog_CharSlice msg = ddog_Error_message(&fr.err);
+    fprintf(stderr, "FAIL [StackFrame_new]: %.*s\n", (int)msg.len, msg.ptr);
+    ddog_Error_drop(&fr.err);
+    exit(EXIT_FAILURE);
+  }
+
+  ddog_crasht_Handle_StackFrame *frame =
+      (ddog_crasht_Handle_StackFrame *)malloc(sizeof(*frame));
+  if (!frame) {
+    fputs("FAIL [malloc frame]\n", stderr);
+    exit(EXIT_FAILURE);
+  }
+  *frame = fr.ok;
+
+  handle_void(ddog_crasht_StackFrame_with_function(frame, slice(function_name)),
+               "StackFrame_with_function");
+  if (ip != 0) {
+    handle_void(ddog_crasht_StackFrame_with_ip(frame, ip),
+                 "StackFrame_with_ip");
+  }
+
+  /* push_frame consumes the frame */
+  handle_void(ddog_crasht_StackTrace_push_frame(trace, frame, /*incomplete=*/true),
+               "StackTrace_push_frame");
+  free(frame);
+}
+
+// Entry point
+int main(int argc, char **argv) {
+  const char *receiver_path = NULL;
+  if (argc >= 2) {
+    receiver_path = argv[1];
+  } else {
+    receiver_path = getenv("DDOG_CRASHT_TEST_RECEIVER");
+  }
+  if (!receiver_path || receiver_path[0] == '\0') {
+    fputs("FAIL: receiver binary path not provided.\n"
+          "      Pass it as argv[1] or set DDOG_CRASHT_TEST_RECEIVER.\n",
+          stderr);
+    return EXIT_FAILURE;
+  }
+
+  static const char output_file[] = "crashreport_unhandled_exception.json";
+  static const char stderr_file[] = "crashreport_unhandled_exception.stderr";
+  static const char stdout_file[] = "crashreport_unhandled_exception.stdout";
+
+  // Forward the dynamic-linker search path to the receiver process.
+  // The receiver is execve'd with an explicit environment so it does not
+  // inherit the parent's env automatically.  The variable name differs by OS:
+  //   Linux / ELF  → LD_LIBRARY_PATH
+  //   macOS        → DYLD_LIBRARY_PATH
+#ifdef __APPLE__
+  const char *ld_search_path_var   = "DYLD_LIBRARY_PATH";
+#else
+  const char *ld_search_path_var   = "LD_LIBRARY_PATH";
+#endif
+  const char *ld_library_path = getenv(ld_search_path_var);
+  ddog_crasht_EnvVar env_vars[1];
+  ddog_crasht_Slice_EnvVar env_slice = {.ptr = NULL, .len = 0};
+  if (ld_library_path && ld_library_path[0] != '\0') {
+    env_vars[0].key = slice(ld_search_path_var);
+    env_vars[0].val = slice(ld_library_path);
+    env_slice.ptr = env_vars;
+    env_slice.len = 1;
+  }
+
+  ddog_crasht_ReceiverConfig receiver_config = {
+      .path_to_receiver_binary = slice(receiver_path),
+      .optional_stderr_filename = slice(stderr_file),
+      .optional_stdout_filename = slice(stdout_file),
+      .env = env_slice,
+  };
+
+  struct ddog_Endpoint *endpoint =
+      ddog_endpoint_from_filename(slice(output_file));
+
+  struct ddog_crasht_Slice_CInt signals = ddog_crasht_default_signals();
+  ddog_crasht_Config config = {
+      .create_alt_stack = false,
+      .endpoint = endpoint,
+      .resolve_frames = DDOG_CRASHT_STACKTRACE_COLLECTION_DISABLED,
+      .signals = {.ptr = signals.ptr, .len = signals.len},
+  };
+
+  ddog_crasht_Metadata metadata = {
+      .library_name    = slice("crashtracking-ffi-test"),
+      .library_version = slice("0.0.0"),
+      .family          = slice("native"),
+      .tags            = NULL,
+  };
+
+  handle_void(ddog_crasht_init(config, receiver_config, metadata),
+               "ddog_crasht_init");
+  ddog_endpoint_drop(endpoint);
+
+  // Build a runtime StackTrace with two synthetic frames.
+  ddog_crasht_StackTrace_NewResult tr = ddog_crasht_StackTrace_new();
+  if (tr.tag != DDOG_CRASHT_STACK_TRACE_NEW_RESULT_OK) {
+    ddog_CharSlice msg = ddog_Error_message(&tr.err);
+    fprintf(stderr, "FAIL [StackTrace_new]: %.*s\n", (int)msg.len, msg.ptr);
+    ddog_Error_drop(&tr.err);
+    return EXIT_FAILURE;
+  }
+
+  ddog_crasht_Handle_StackTrace *trace =
+      (ddog_crasht_Handle_StackTrace *)malloc(sizeof(*trace));
+  if (!trace) {
+    fputs("FAIL [malloc trace]\n", stderr);
+    return EXIT_FAILURE;
+  }
+  *trace = tr.ok;
+
+  push_named_frame(trace, "com.example.MyApp.processRequest", 0x1000);
+  push_named_frame(trace, "com.example.runtime.EventLoop.run",  0x2000);
+  push_named_frame(trace, "com.example.runtime.main",           0x3000);
+
+  handle_void(ddog_crasht_StackTrace_set_complete(trace),
+               "StackTrace_set_complete");
+
+  // Report the unhandled exception.  This call:
+  //   - spawns the receiver process,
+  //   - sends the crash report over the socket,
+  //   - waits for the receiver to finish writing the report,
+  //   - returns Ok on success.
+  handle_void(
+      ddog_crasht_report_unhandled_exception(
+          slice("com.example.UncaughtRuntimeException"),
+          slice("Something went very wrong in the runtime"),
+          trace),
+      "ddog_crasht_report_unhandled_exception");
+
+  free(trace);
+
+  // Verify a report file was produced.
+  FILE *f = fopen(output_file, "r");
+  if (!f) {
+    fprintf(stderr, "FAIL: expected crash report at '%s' but file not found\n",
+            output_file);
+    return EXIT_FAILURE;
+  }
+  fclose(f);
+
+  printf("PASS: crash report written to '%s'\n", output_file);
+  return EXIT_SUCCESS;
+}
+
diff --git a/libdd-crashtracker-ffi/src/collector/mod.rs b/libdd-crashtracker-ffi/src/collector/mod.rs
@@ -10,8 +10,9 @@ pub use additional_tags::*;
 pub use counters::*;
 pub use datatypes::*;
 use function_name::named;
-use libdd_common_ffi::{wrap_with_void_ffi_result, Slice, VoidResult};
-use libdd_crashtracker::{CrashtrackerReceiverConfig, DEFAULT_SYMBOLS};
+use libdd_common_ffi::slice::AsBytes;
+use libdd_common_ffi::{wrap_with_void_ffi_result, CharSlice, Handle, Slice, ToInner, VoidResult};
+use libdd_crashtracker::{CrashtrackerReceiverConfig, StackTrace, DEFAULT_SYMBOLS};
 pub use spans::*;
 
 #[no_mangle]
@@ -177,3 +178,56 @@ pub unsafe extern "C" fn ddog_crasht_init_without_receiver(
 pub extern "C" fn ddog_crasht_default_signals() -> Slice<'static, libc::c_int> {
     Slice::new(&DEFAULT_SYMBOLS)
 }
+
+#[no_mangle]
+#[must_use]
+#[named]
+/// Report an unhandled exception as a crash event.
+///
+/// This function sends a crash report for an unhandled exception detected
+/// by the runtime. It is intended to be called when the process is in a
+/// terminal state due to an unhandled exception.
+///
+/// # Parameters
+/// - `error_type`: Optional type/class of the exception (e.g. "NullPointerException"). Pass empty
+///   CharSlice for unknown.
+/// - `error_message`: Optional error message. Pass empty CharSlice for no message.
+/// - `runtime_stack`: Stack trace from the runtime. Consumed by this call.
+///
+/// If the crash-tracker has not been initialized, this function is a no-op.
+///
+/// # Side effects
+///   This function disables the signal-based crash handler before performing
+///   any work. This means that if the process receives a fatal signal (SIGSEGV)
+///   during or after this call, the crashtracker will not produce a
+///   second crash report. The previous signal handler (if any) will still be
+///   chained.
+///
+/// # Failure mode
+///   If a fatal signal occurs while this function is in progress, the calling
+///   process is in an unrecoverable state; the crashtracker cannot report the
+///   secondary fault and the caller's own signal handler (if any) will execute
+///   in a potentially corrupted context. Callers should treat this function as a
+///   terminal operation and exit shortly after it returns.
+///
+/// # Safety
+///   Crash-tracking functions are not reentrant.
+///   No other crash-handler functions should be called concurrently.
+///   The `runtime_stack` handle must be valid and will be consumed.
+pub unsafe extern "C" fn ddog_crasht_report_unhandled_exception(
+    error_type: CharSlice,
+    error_message: CharSlice,
+    mut runtime_stack: *mut Handle<StackTrace>,
+) -> VoidResult {
+    wrap_with_void_ffi_result!({
+        let error_type_opt = error_type.try_to_string_option()?;
+        let error_message_opt = error_message.try_to_string_option()?;
+        let stack = *runtime_stack.take()?;
+
+        libdd_crashtracker::report_unhandled_exception(
+            error_type_opt.as_deref(),
+            error_message_opt.as_deref(),
+            stack,
+        )?;
+    })
+}
diff --git a/tools/src/bin/ffi_test.rs b/tools/src/bin/ffi_test.rs
@@ -128,6 +128,57 @@ fn skip_examples() -> &'static HashMap<&'static str, &'static str> {
     })
 }
 
+/// Per-test environment variables.  The runner sets these before spawning
+/// the test executable so that tests which need external resources (e.g. the
+/// receiver binary) can find them without hard-coding paths.
+fn per_test_env(name: &str, project_root: &Path) -> Vec<(String, String)> {
+    match name {
+        "crashtracking_unhandled_exception" => {
+            // The receiver binary and shared library may live in either
+            // "release/" (local/ffi_test build) or "artifacts/" (CI pre-built).
+            // Check both and use whichever exists.
+            let make_paths = |dir: &str| {
+                let base = project_root.join(dir);
+                (
+                    base.join("bin").join("libdatadog-crashtracking-receiver"),
+                    base.join("lib"),
+                )
+            };
+            let (receiver, lib_dir) = ["release", "artifacts"]
+                .iter()
+                .map(|dir| make_paths(dir))
+                .find(|(bin, _)| bin.exists())
+                .unwrap_or_else(|| make_paths("release"));
+
+            // The C test binary is dynamically linked against libdatadog_profiling.{so,dylib}
+            // which is not on the system library path.  Set the platform-specific linker
+            // search path so the binary can load, and the C test forwards it via getenv()
+            // into the receiver's explicit execve environment.
+            // Linux  → LD_LIBRARY_PATH
+            // macOS  → DYLD_LIBRARY_PATH
+            #[cfg(target_os = "macos")]
+            let search_path_var = "DYLD_LIBRARY_PATH";
+            #[cfg(not(target_os = "macos"))]
+            let search_path_var = "LD_LIBRARY_PATH";
+
+            let lib_path = match std::env::var(search_path_var) {
+                Ok(existing) if !existing.is_empty() => {
+                    format!("{}:{}", lib_dir.display(), existing)
+                }
+                _ => lib_dir.display().to_string(),
+            };
+            vec![
+                (
+                    "DDOG_CRASHT_TEST_RECEIVER".to_string(),
+                    receiver.display().to_string(),
+                ),
+                (search_path_var.to_string(), lib_path),
+            ]
+        }
+        _ => vec![],
+    }
+}
+
 fn expected_failures() -> &'static HashMap<&'static str, &'static str> {
     static MAP: OnceLock<HashMap<&'static str, &'static str>> = OnceLock::new();
     MAP.get_or_init(|| {
@@ -287,11 +338,16 @@ fn setup_work_dir(project_root: &Path) -> Result<PathBuf> {
 }
 
 /// Spawn a test process and return child with captured output handles
-fn spawn_test(exe_path: &Path, work_dir: &Path) -> Result<std::process::Child> {
+fn spawn_test(
+    exe_path: &Path,
+    work_dir: &Path,
+    env_vars: &[(String, String)],
+) -> Result<std::process::Child> {
     Command::new(exe_path)
         .current_dir(work_dir)
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
+        .envs(env_vars.iter().map(|(k, v)| (k, v)))
         .spawn()
         .with_context(|| format!("spawning {}", exe_path.display()))
 }
@@ -387,11 +443,18 @@ fn determine_status(
     }
 }
 
-fn run_test(name: &str, exe_path: &Path, work_dir: &Path, timeout: Duration) -> TestResult {
+fn run_test(
+    name: &str,
+    exe_path: &Path,
+    work_dir: &Path,
+    project_root: &Path,
+    timeout: Duration,
+) -> TestResult {
     let is_expected_failure = expected_failures().contains_key(name);
+    let env_vars = per_test_env(name, project_root);
     let start = Instant::now();
 
-    let child = match spawn_test(exe_path, work_dir) {
+    let child = match spawn_test(exe_path, work_dir, &env_vars) {
         Ok(c) => c,
         Err(e) => {
             return TestResult {
@@ -507,7 +570,7 @@ fn run_examples(
             continue;
         }
 
-        let result = run_test(name, exe, &work_dir, timeout);
+        let result = run_test(name, exe, &work_dir, project_root, timeout);
         result.print();
         results.push(result);
     }
