sf-veritas 0.11.10__cp314-cp314-manylinux_2_28_x86_64.whl

sf_veritas/__init__.py

@@ -0,0 +1,46 @@
+# Note: LD_PRELOAD must be set manually by user for C library mode
+# The C library (libsfnettee.so) is available but requires explicit LD_PRELOAD configuration
+
+# Install C-level crash handler FIRST (catches crashes before Python can)
+import sys
+try:
+    sys.stderr.write("[__init__] Attempting to load C crash handler...\n")
+    sys.stderr.flush()
+    from . import _sfcrashhandler
+    sys.stderr.write("[__init__] C crash handler module loaded, installing...\n")
+    sys.stderr.flush()
+    _sfcrashhandler.install()
+    sys.stderr.write("[__init__] C crash handler installed successfully\n")
+    sys.stderr.flush()
+except Exception as e:
+    import traceback
+    sys.stderr.write(f"[WARNING] Failed to install C crash handler: {e}\n")
+    traceback.print_exc(file=sys.stderr)
+    sys.stderr.flush()
+
+# Install Python-level segfault handler as backup
+try:
+    from . import segfault_handler  # noqa: F401
+except Exception:
+    pass  # Silently fail if handler can't be installed
+
+from .function_span_profiler import (
+    skip_tracing,  # Backward compatibility
+    skip_function_tracing,
+    skip_network_tracing,
+    capture_function_spans,
+)
+from .package_metadata import __version__
+from .transmit_exception_to_sailfish import transmit_exception_to_sailfish
+from .unified_interceptor import setup_interceptors, reinitialize_after_fork
+
+__all__ = [
+    "setup_interceptors",
+    "transmit_exception_to_sailfish",
+    "skip_tracing",  # Backward compatibility
+    "skip_function_tracing",
+    "skip_network_tracing",
+    "capture_function_spans",
+    "reinitialize_after_fork",
+    "__version__",
+]

sf_veritas/_auto_preload.py

@@ -0,0 +1,73 @@
+"""
+Auto-detection and configuration of LD_PRELOAD mode.
+
+This module automatically detects if libsfnettee.so is available in the package
+and sets the LD_PRELOAD environment variable if it's not already set. This enables
+LD_PRELOAD mode automatically without requiring manual configuration.
+"""
+
+import os
+import sys
+
+
+def _auto_enable_ld_preload() -> bool:
+    """
+    Check if LD_PRELOAD mode is active.
+
+    This function checks if the C library (libsfnettee.so) is loaded via LD_PRELOAD.
+    It does NOT attempt to automatically enable it - users must set LD_PRELOAD themselves.
+
+    To enable high-performance C library mode, set LD_PRELOAD before starting Python:
+        export LD_PRELOAD=/path/to/site-packages/sf_veritas/libsfnettee.so
+        python your_app.py
+
+    Or in your Dockerfile entrypoint:
+        ENV LD_PRELOAD=/usr/local/lib/python3.12/site-packages/sf_veritas/libsfnettee.so
+
+    Returns:
+        True if LD_PRELOAD mode is active (C library loaded)
+        False if not active (will use Python patches)
+    """
+    # Check if LD_PRELOAD is already set with libsfnettee.so
+    current_ld_preload = os.getenv("LD_PRELOAD", "")
+    if "libsfnettee.so" in current_ld_preload or "_sfteepreload" in current_ld_preload:
+        if os.getenv("SF_DEBUG", "false").lower() == "true":
+            sys.stderr.write(f"[sf_veritas] ✓ C library active via LD_PRELOAD: {current_ld_preload}\n")
+            sys.stderr.flush()
+        return True
+
+    # Not active - check if library exists and print helpful message
+    try:
+        package_dir = os.path.dirname(os.path.abspath(__file__))
+        libsfnettee_path = os.path.join(package_dir, "libsfnettee.so")
+
+        if os.path.isfile(libsfnettee_path):
+            if os.getenv("SF_DEBUG", "false").lower() == "true":
+                sys.stderr.write(f"[sf_veritas] C library available but not loaded (using Python patches)\n")
+                sys.stderr.write(f"[sf_veritas] For better performance, set LD_PRELOAD before starting Python:\n")
+                sys.stderr.write(f"[sf_veritas]   export LD_PRELOAD={libsfnettee_path}\n")
+                sys.stderr.flush()
+        else:
+            if os.getenv("SF_DEBUG", "false").lower() == "true":
+                sys.stderr.write(f"[sf_veritas] C library not found at {libsfnettee_path}\n")
+                sys.stderr.write(f"[sf_veritas] Using Python patches (slower but works)\n")
+                sys.stderr.flush()
+    except Exception:
+        pass
+
+    return False
+
+
+# Check if LD_PRELOAD mode is active
+_LD_PRELOAD_ACTIVE = _auto_enable_ld_preload()
+
+# Enable Python SSL mode when LD_PRELOAD is active (default ON)
+# This tells the C library to disable its SSL hooks (Python handles HTTPS, C handles HTTP)
+if _LD_PRELOAD_ACTIVE:
+    # Default to '1' (C SSL hooks disabled) unless explicitly overridden
+    if 'SF_SSL_PYTHON_MODE' not in os.environ:
+        os.environ['SF_SSL_PYTHON_MODE'] = '1'
+
+    if os.getenv("SF_DEBUG", "false").lower() == "true":
+        sys.stderr.write("[sf_veritas] ✓ Python SSL mode enabled (C handles HTTP, Python handles HTTPS)\n")
+        sys.stderr.flush()

sf_veritas/_sfconfig.c

@@ -0,0 +1,162 @@
+// Python C extension module to configure the C library
+// This provides a clean, secure interface using dlsym to find runtime symbols
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+#include <dlfcn.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+// Function pointers for the C library functions
+typedef void (*sf_set_sink_url_t)(const char *url);
+typedef void (*sf_set_api_key_t)(const char *key);
+typedef void (*sf_set_service_uuid_t)(const char *uuid);
+typedef void (*sf_initialize_t)(void);
+
+static sf_set_sink_url_t sf_set_sink_url_ptr = NULL;
+static sf_set_api_key_t sf_set_api_key_ptr = NULL;
+static sf_set_service_uuid_t sf_set_service_uuid_ptr = NULL;
+static sf_initialize_t sf_initialize_ptr = NULL;
+static int symbols_resolved = 0;
+
+// Lazy symbol resolution - called on first use of any function
+static void ensure_symbols_resolved(void) {
+    if (symbols_resolved) {
+        return;  // Already resolved
+    }
+
+    // Clear any previous dlsym errors
+    dlerror();
+
+    // Use RTLD_DEFAULT to search all loaded libraries (including LD_PRELOAD)
+    sf_set_sink_url_ptr = (sf_set_sink_url_t)dlsym(RTLD_DEFAULT, "sf_set_sink_url");
+    const char *err1 = dlerror();
+
+    sf_set_api_key_ptr = (sf_set_api_key_t)dlsym(RTLD_DEFAULT, "sf_set_api_key");
+    const char *err2 = dlerror();
+
+    sf_set_service_uuid_ptr = (sf_set_service_uuid_t)dlsym(RTLD_DEFAULT, "sf_set_service_uuid");
+    const char *err3 = dlerror();
+
+    sf_initialize_ptr = (sf_initialize_t)dlsym(RTLD_DEFAULT, "sf_initialize");
+    const char *err4 = dlerror();
+
+    // Debug output to help diagnose symbol resolution issues
+    if (!sf_set_sink_url_ptr || !sf_set_api_key_ptr || !sf_set_service_uuid_ptr || !sf_initialize_ptr) {
+        const char *ld_preload = getenv("LD_PRELOAD");
+        fprintf(stderr, "[_sfconfig] Symbol resolution FAILED!\n");
+        fprintf(stderr, "  LD_PRELOAD=%s\n", ld_preload ? ld_preload : "(not set)");
+        fprintf(stderr, "  sf_set_sink_url: %s (%s)\n",
+                sf_set_sink_url_ptr ? "OK" : "FAILED", err1 ? err1 : "no error");
+        fprintf(stderr, "  sf_set_api_key: %s (%s)\n",
+                sf_set_api_key_ptr ? "OK" : "FAILED", err2 ? err2 : "no error");
+        fprintf(stderr, "  sf_set_service_uuid: %s (%s)\n",
+                sf_set_service_uuid_ptr ? "OK" : "FAILED", err3 ? err3 : "no error");
+        fprintf(stderr, "  sf_initialize: %s (%s)\n",
+                sf_initialize_ptr ? "OK" : "FAILED", err4 ? err4 : "no error");
+        fflush(stderr);
+    }
+
+    symbols_resolved = 1;
+}
+
+// Python wrapper: sf_set_sink_url(url: str) -> None
+static PyObject* py_sf_set_sink_url(PyObject* self, PyObject* args) {
+    const char *url;
+    if (!PyArg_ParseTuple(args, "s", &url)) {
+        return NULL;
+    }
+
+    // Lazy symbol resolution on first call
+    ensure_symbols_resolved();
+
+    if (!sf_set_sink_url_ptr) {
+        PyErr_SetString(PyExc_RuntimeError, "C library not loaded (LD_PRELOAD not active?)");
+        return NULL;
+    }
+    sf_set_sink_url_ptr(url);
+    Py_RETURN_NONE;
+}
+
+// Python wrapper: sf_set_api_key(key: str) -> None
+static PyObject* py_sf_set_api_key(PyObject* self, PyObject* args) {
+    const char *key;
+    if (!PyArg_ParseTuple(args, "s", &key)) {
+        return NULL;
+    }
+
+    // Lazy symbol resolution on first call
+    ensure_symbols_resolved();
+
+    if (!sf_set_api_key_ptr) {
+        PyErr_SetString(PyExc_RuntimeError, "C library not loaded (LD_PRELOAD not active?)");
+        return NULL;
+    }
+    sf_set_api_key_ptr(key);
+    Py_RETURN_NONE;
+}
+
+// Python wrapper: sf_set_service_uuid(uuid: str) -> None
+static PyObject* py_sf_set_service_uuid(PyObject* self, PyObject* args) {
+    const char *uuid;
+    if (!PyArg_ParseTuple(args, "s", &uuid)) {
+        return NULL;
+    }
+
+    // Lazy symbol resolution on first call
+    ensure_symbols_resolved();
+
+    if (!sf_set_service_uuid_ptr) {
+        PyErr_SetString(PyExc_RuntimeError, "C library not loaded (LD_PRELOAD not active?)");
+        return NULL;
+    }
+    sf_set_service_uuid_ptr(uuid);
+    Py_RETURN_NONE;
+}
+
+// Python wrapper: sf_initialize() -> None
+static PyObject* py_sf_initialize(PyObject* self, PyObject* args) {
+    // Lazy symbol resolution on first call
+    ensure_symbols_resolved();
+
+    if (!sf_initialize_ptr) {
+        PyErr_SetString(PyExc_RuntimeError, "C library not loaded (LD_PRELOAD not active?)");
+        return NULL;
+    }
+    sf_initialize_ptr();
+    Py_RETURN_NONE;
+}
+
+// Method definitions
+static PyMethodDef SfConfigMethods[] = {
+    {"set_sink_url", py_sf_set_sink_url, METH_VARARGS,
+     "Set the GraphQL endpoint URL for the C library"},
+    {"set_api_key", py_sf_set_api_key, METH_VARARGS,
+     "Set the API key for the C library"},
+    {"set_service_uuid", py_sf_set_service_uuid, METH_VARARGS,
+     "Set the service UUID for the C library"},
+    {"initialize", py_sf_initialize, METH_NOARGS,
+     "Initialize and activate the C library (sets SF_INITIALIZED=1)"},
+    {NULL, NULL, 0, NULL}
+};
+
+// Module definition
+static struct PyModuleDef sfconfig_module = {
+    PyModuleDef_HEAD_INIT,
+    "_sfconfig",
+    "Configuration interface for the Sailfish C library",
+    -1,
+    SfConfigMethods
+};
+
+// Module initialization
+PyMODINIT_FUNC PyInit__sfconfig(void) {
+    PyObject *module = PyModule_Create(&sfconfig_module);
+    if (module == NULL) {
+        return NULL;
+    }
+
+    // Symbol resolution is done lazily on first function call
+    // This ensures the C library is fully loaded before we try to find symbols
+
+    return module;
+}

sf_veritas/_sfcrashhandler.c

@@ -0,0 +1,267 @@
+// C-level crash handler that prints registers and stack addresses
+// This catches segfaults that happen in C code before Python can handle them
+
+// Ensure we have write() and fsync() available
+#ifndef _POSIX_C_SOURCE
+#define _POSIX_C_SOURCE 200809L
+#endif
+
+// macOS requires _XOPEN_SOURCE for ucontext
+#ifdef __APPLE__
+#define _XOPEN_SOURCE 600
+#endif
+
+#include <Python.h>
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <execinfo.h>
+#include <sys/types.h>
+
+// Platform-specific includes for register access
+#if defined(__linux__)
+#include <ucontext.h>
+#include <sys/syscall.h>
+#elif defined(__APPLE__)
+#include <sys/ucontext.h>
+#endif
+
+// Get thread ID
+static long gettid(void) {
+#ifdef SYS_gettid
+    return (long)syscall(SYS_gettid);
+#else
+    return (long)getpid();
+#endif
+}
+
+// Signal handler that prints everything
+static void crash_handler(int sig, siginfo_t *si, void *ctx) {
+    ucontext_t *uc = (ucontext_t *)ctx;
+    void *backtrace_buffer[100];
+    int backtrace_size;
+    char **bt_symbols;
+    int i;
+
+    // Make stderr unbuffered to ensure output appears
+    setvbuf(stderr, NULL, _IONBF, 0);
+
+    // Print to stderr directly (unbuffered)
+    const char *sig_name =
+        sig == SIGSEGV ? "SIGSEGV" :
+        sig == SIGABRT ? "SIGABRT" :
+        sig == SIGBUS  ? "SIGBUS" :
+        sig == SIGFPE  ? "SIGFPE" :
+        sig == SIGILL  ? "SIGILL" : "UNKNOWN";
+
+    // Write directly to fd 2 (stderr) to bypass buffering entirely
+    const char *header = "\n\n=== CRASH HANDLER TRIGGERED ===\n";
+    write(2, header, strlen(header));
+
+    fprintf(stderr, "\n");
+    fprintf(stderr, "================================================================================\n");
+    fprintf(stderr, "CRASH DETECTED: Signal %d (%s)\n", sig, sig_name);
+    fprintf(stderr, "================================================================================\n");
+    fprintf(stderr, "Process ID:  %d\n", getpid());
+    fprintf(stderr, "Thread ID:   %ld\n", gettid());
+    fprintf(stderr, "Signal code: %d\n", si->si_code);
+    fprintf(stderr, "Fault addr:  %p\n", si->si_addr);
+    fprintf(stderr, "\n");
+
+    // Print registers (platform-specific)
+#if defined(__linux__) && defined(__x86_64__)
+    fprintf(stderr, "--- x86_64 Registers (Linux) ---\n");
+    fprintf(stderr, "RIP: 0x%016llx  RSP: 0x%016llx  RBP: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RIP],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RSP],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RBP]);
+    fprintf(stderr, "RAX: 0x%016llx  RBX: 0x%016llx  RCX: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RAX],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RBX],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RCX]);
+    fprintf(stderr, "RDX: 0x%016llx  RSI: 0x%016llx  RDI: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RDX],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RSI],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_RDI]);
+    fprintf(stderr, "R8:  0x%016llx  R9:  0x%016llx  R10: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R8],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R9],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R10]);
+    fprintf(stderr, "R11: 0x%016llx  R12: 0x%016llx  R13: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R11],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R12],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R13]);
+    fprintf(stderr, "R14: 0x%016llx  R15: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R14],
+            (unsigned long long)uc->uc_mcontext.gregs[REG_R15]);
+#elif defined(__linux__) && defined(__aarch64__)
+    fprintf(stderr, "--- ARM64 Registers (Linux) ---\n");
+    fprintf(stderr, "PC:  0x%016llx  SP:  0x%016llx  FP:  0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext.pc,
+            (unsigned long long)uc->uc_mcontext.sp,
+            (unsigned long long)uc->uc_mcontext.regs[29]);
+    for (i = 0; i < 29; i += 3) {
+        fprintf(stderr, "X%-2d: 0x%016llx  ", i, (unsigned long long)uc->uc_mcontext.regs[i]);
+        if (i + 1 < 29)
+            fprintf(stderr, "X%-2d: 0x%016llx  ", i+1, (unsigned long long)uc->uc_mcontext.regs[i+1]);
+        if (i + 2 < 29)
+            fprintf(stderr, "X%-2d: 0x%016llx", i+2, (unsigned long long)uc->uc_mcontext.regs[i+2]);
+        fprintf(stderr, "\n");
+    }
+#elif defined(__APPLE__) && defined(__x86_64__)
+    fprintf(stderr, "--- x86_64 Registers (macOS) ---\n");
+    fprintf(stderr, "RIP: 0x%016llx  RSP: 0x%016llx  RBP: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__rip,
+            (unsigned long long)uc->uc_mcontext->__ss.__rsp,
+            (unsigned long long)uc->uc_mcontext->__ss.__rbp);
+    fprintf(stderr, "RAX: 0x%016llx  RBX: 0x%016llx  RCX: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__rax,
+            (unsigned long long)uc->uc_mcontext->__ss.__rbx,
+            (unsigned long long)uc->uc_mcontext->__ss.__rcx);
+    fprintf(stderr, "RDX: 0x%016llx  RSI: 0x%016llx  RDI: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__rdx,
+            (unsigned long long)uc->uc_mcontext->__ss.__rsi,
+            (unsigned long long)uc->uc_mcontext->__ss.__rdi);
+    fprintf(stderr, "R8:  0x%016llx  R9:  0x%016llx  R10: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__r8,
+            (unsigned long long)uc->uc_mcontext->__ss.__r9,
+            (unsigned long long)uc->uc_mcontext->__ss.__r10);
+    fprintf(stderr, "R11: 0x%016llx  R12: 0x%016llx  R13: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__r11,
+            (unsigned long long)uc->uc_mcontext->__ss.__r12,
+            (unsigned long long)uc->uc_mcontext->__ss.__r13);
+    fprintf(stderr, "R14: 0x%016llx  R15: 0x%016llx\n",
+            (unsigned long long)uc->uc_mcontext->__ss.__r14,
+            (unsigned long long)uc->uc_mcontext->__ss.__r15);
+#elif defined(__APPLE__) && defined(__aarch64__)
+    fprintf(stderr, "--- ARM64 Registers (macOS) ---\n");
+    fprintf(stderr, "PC:  0x%016llx  SP:  0x%016llx  FP:  0x%016llx\n",
+            (unsigned long long)__darwin_arm_thread_state64_get_pc(uc->uc_mcontext->__ss),
+            (unsigned long long)__darwin_arm_thread_state64_get_sp(uc->uc_mcontext->__ss),
+            (unsigned long long)__darwin_arm_thread_state64_get_fp(uc->uc_mcontext->__ss));
+    for (i = 0; i < 29; i += 3) {
+        fprintf(stderr, "X%-2d: 0x%016llx  ", i, (unsigned long long)uc->uc_mcontext->__ss.__x[i]);
+        if (i + 1 < 29)
+            fprintf(stderr, "X%-2d: 0x%016llx  ", i+1, (unsigned long long)uc->uc_mcontext->__ss.__x[i+1]);
+        if (i + 2 < 29)
+            fprintf(stderr, "X%-2d: 0x%016llx", i+2, (unsigned long long)uc->uc_mcontext->__ss.__x[i+2]);
+        fprintf(stderr, "\n");
+    }
+#else
+    fprintf(stderr, "--- Registers (architecture not recognized) ---\n");
+    (void)uc;  // Suppress unused variable warning
+#endif
+    fprintf(stderr, "\n");
+
+    // Print native backtrace
+    fprintf(stderr, "--- Native Stack Trace (C level) ---\n");
+    backtrace_size = backtrace(backtrace_buffer, 100);
+    bt_symbols = backtrace_symbols(backtrace_buffer, backtrace_size);
+
+    if (bt_symbols) {
+        for (i = 0; i < backtrace_size; i++) {
+            fprintf(stderr, "[%2d] %s\n", i, bt_symbols[i]);
+        }
+        free(bt_symbols);
+    } else {
+        fprintf(stderr, "Failed to get backtrace symbols\n");
+    }
+    fprintf(stderr, "\n");
+
+    // Print raw stack memory
+    fprintf(stderr, "--- Stack Memory (32 bytes from fault) ---\n");
+    unsigned char *fault_ptr = (unsigned char *)si->si_addr;
+    fprintf(stderr, "Fault address: %p\n", fault_ptr);
+
+    // Try to read memory around fault address (may fail)
+    // Print stack pointer area instead
+#if defined(__linux__) && defined(__x86_64__)
+    unsigned long long *sp = (unsigned long long *)uc->uc_mcontext.gregs[REG_RSP];
+#elif defined(__linux__) && defined(__aarch64__)
+    unsigned long long *sp = (unsigned long long *)uc->uc_mcontext.sp;
+#elif defined(__APPLE__) && defined(__x86_64__)
+    unsigned long long *sp = (unsigned long long *)uc->uc_mcontext->__ss.__rsp;
+#elif defined(__APPLE__) && defined(__aarch64__)
+    unsigned long long *sp = (unsigned long long *)__darwin_arm_thread_state64_get_sp(uc->uc_mcontext->__ss);
+#else
+    unsigned long long *sp = NULL;
+#endif
+
+    if (sp) {
+        fprintf(stderr, "Stack at RSP/SP (%p):\n", sp);
+        for (i = 0; i < 4; i++) {
+            fprintf(stderr, "  [SP+%2d] 0x%016llx\n", i*8, (unsigned long long)sp[i]);
+        }
+    }
+    fprintf(stderr, "\n");
+
+    fprintf(stderr, "================================================================================\n");
+    fprintf(stderr, "Use addr2line to decode addresses:\n");
+    fprintf(stderr, "  addr2line -e /path/to/_sffuncspan.*.so <address>\n");
+    fprintf(stderr, "================================================================================\n");
+    fprintf(stderr, "\n");
+
+    fflush(stderr);
+    fsync(2);  // Force write to disk
+
+    const char *footer = "\n=== END CRASH HANDLER ===\n\n";
+    write(2, footer, strlen(footer));
+
+    // Re-raise signal with default handler (generates core dump)
+    signal(sig, SIG_DFL);
+    raise(sig);
+}
+
+// Install crash handler
+static PyObject *install_crash_handler(PyObject *self, PyObject *args) {
+    struct sigaction sa;
+    memset(&sa, 0, sizeof(sa));
+    sa.sa_sigaction = crash_handler;
+    sa.sa_flags = SA_SIGINFO | SA_RESTART;
+    sigemptyset(&sa.sa_mask);
+
+    if (sigaction(SIGSEGV, &sa, NULL) == -1) {
+        PyErr_SetString(PyExc_RuntimeError, "Failed to install SIGSEGV handler");
+        return NULL;
+    }
+    if (sigaction(SIGABRT, &sa, NULL) == -1) {
+        PyErr_SetString(PyExc_RuntimeError, "Failed to install SIGABRT handler");
+        return NULL;
+    }
+    if (sigaction(SIGBUS, &sa, NULL) == -1) {
+        PyErr_SetString(PyExc_RuntimeError, "Failed to install SIGBUS handler");
+        return NULL;
+    }
+    if (sigaction(SIGFPE, &sa, NULL) == -1) {
+        PyErr_SetString(PyExc_RuntimeError, "Failed to install SIGFPE handler");
+        return NULL;
+    }
+    if (sigaction(SIGILL, &sa, NULL) == -1) {
+        PyErr_SetString(PyExc_RuntimeError, "Failed to install SIGILL handler");
+        return NULL;
+    }
+
+    fprintf(stderr, "[_sfcrashhandler] C-level crash handlers installed (PID=%d)\n", getpid());
+    fflush(stderr);
+
+    Py_RETURN_NONE;
+}
+
+static PyMethodDef crash_handler_methods[] = {
+    {"install", install_crash_handler, METH_NOARGS, "Install C-level crash handler"},
+    {NULL, NULL, 0, NULL}
+};
+
+static struct PyModuleDef crash_handler_module = {
+    PyModuleDef_HEAD_INIT,
+    "_sfcrashhandler",
+    "C-level crash handler for debugging segfaults",
+    -1,
+    crash_handler_methods
+};
+
+PyMODINIT_FUNC PyInit__sfcrashhandler(void) {
+    return PyModule_Create(&crash_handler_module);
+}