Skip to main content

Module panic_telemetry

Module panic_telemetry 

Source
Expand description

Structured panic telemetry for debugging Rust panics that become R errors.

Three separate panic→R-error paths exist in miniextendr (ALTREP trampolines, connection callbacks, and unwind_protect). This module provides a unified hook point that fires before each panic is converted to an R error.

§Relationship to the three emission paths

This module is observability, not emission. It does not raise R conditions and does not change how panics become errors; it only lets a caller observe them. The three actual emission paths are documented on crate::error_value:

fire is invoked from each catch site before the panic message is encoded into a tagged condition value, so a registered hook sees every Rust-origin failure regardless of which of the three paths produced it. Typical uses: routing to tracing / log, capturing stack snapshots for crash reports, or surfacing the panic message in test harnesses where R’s stderr is buffered. The hook must not raise R conditions itself (it runs inside the panic-handling path) and must not panic — secondary panics from the hook are caught and silently suppressed by fire (this crate, pub(crate)).

§Usage

ⓘ
use miniextendr_api::panic_telemetry::{set_panic_telemetry_hook, PanicReport, PanicSource};

set_panic_telemetry_hook(|report| {
    eprintln!("[{:?}] panic: {}", report.source, report.message);
});

§Threads

Every panic→R-error boundary runs on R’s main thread, so the hook lives there: a thread-local slot, set and fired on that thread, and the closure need not be Send or Sync. A hook set on another thread stays in that thread’s slot and never sees the main thread’s panics.

§Performance

fire() reads a thread-local slot and, with a hook set, clones its Rc. The hook only fires on panic paths, never on hot paths.

Re-exports§

use std::cell::RefCell; 🔒
use std::panic::AssertUnwindSafe; 🔒
use std::panic::catch_unwind; 🔒
use std::rc::Rc; 🔒

Structs§

PanicReport
A structured panic report passed to the telemetry hook.

Enums§

PanicSource
Describes where a panic originated before being converted to an R error.

Constants§

HOOK 🔒

Functions§

clear_panic_telemetry_hook
Remove the current panic telemetry hook, if any.
fire 🔒
Fire the telemetry hook if one is set.
set_panic_telemetry_hook
Register a panic telemetry hook on R’s main thread.

Type Aliases§

Hook 🔒