Crate libdd_crashtracker 

This module implements a crashtracker based on catching UNIX signals and uploading the result to the backend.

Architecturally, it consists of two parts:

1. A signal handler, which catches a UNIX signal (SIGSEGV, SIGBUS, SIGABRT) associated with a crash, and and collects information about the state of the program at crash time. The signal handler runs under a constrained environment where many standard operations are illegal. https://man7.org/linux/man-pages/man7/signal-safety.7.html In particular, memory allocation, and synchronization such as mutexes, are potentially UB. The signal handler therefore does as little as possible in process, and instead writes data across a socket to a separate receiver process. The signal handler then waits for the receiver process to exit in order to reap its exit status (otherwise, upon the termination of the crashing process the child will be re-parented to PID 1 in the current PID namespace, which can be problematic for some user applications) and restores the previous signal handler. Once the receiver has completed, the crash-handler returns, allowing the previous crash handler (if any) to execute, maintaining the customer experience as much as possible.
2. The receiver process, which is spawned by the signal handler. It is connected by an anynomous AF_UNIX socketpair() to the parent process. When a crash occurs, the receiver gathers the information from the pipe, adds additional data about the system state (e.g. /proc/cpuinfo and /proc/meminfo), formats it into a crash report, uploads it to the backend, and then exits. The signal handler must wait for the receiver in order to reap its exit status.

Data collected:

1. The data collected by the crash-handler includes:
   1. The signal type leading to the crash
   2. The stacktrace at time of crash (for the crashing thread). Depending on a flag, this can either be resolved, or raw addresses. Resolving addresses provide more data, but sometimes crashes the crash handler (ironic).
   3. System level info (e.g. /proc/self/maps).
   4. The result of counters describing the current state of the profiler.
2. Data augmented by the receiver includes:
   1. Metadata provided by the caller (e.g. library & profiler versions).
   2. System info: OS version, /proc/cpuinfo /proc/meminfo, etc.
   3. A timestamp and GUID for tracking the crash report.

Handling of forks Safety issues

Structs

CachedElfResolvers

CrashInfo

CrashInfoBuilder

CrashPing

CrashPingBuilder

CrashtrackerConfiguration

CrashtrackerConfigurationBuilder

CrashtrackerReceiverConfig

ErrorData

ErrorDataBuilder

ErrorObject

ErrorsIntakeConfig

ErrorsIntakePayload

ErrorsIntakeSettings

Settings gathers configuration options we receive from the environment

ErrorsIntakeUploader

Experimental

Metadata

OsInfo

ProcInfo

RuntimeStack

Runtime stack representation for JSON serialization

RuntimeStackFrame

SharedLibrary

SigInfo

Span

StackFrame

StackTrace

TelemetryCrashUploader

ThreadData

Ucontext

Structured representation of the CPU register state captured from a ucontext_t at the time of a crash signal.

Enums

BuildIdType

CallbackData

CallbackError

ErrorKind

FileType

OpTypes

This enum represents operations a the tracked library might be engaged in. Currently only implemented for profiling. The idea is that if a crash consistently occurs while a particular operation is ongoing, its likely related.

SiCodes

See https://man7.org/linux/man-pages/man2/sigaction.2.html MUST REMAIN IN SYNC WITH THE ENUM IN emit_sigcodes.c

SignalNames

See https://man7.org/linux/man-pages/man7/signal.7.html

SourceType

StacktraceCollection

Stacktrace collection occurs in the context of a crashing process. If the stack is sufficiently corruputed, it is possible (but unlikely), for stack trace collection itself to crash. We recommend fully enabling stacktrace collection, but having an environment variable to allow downgrading the collector.

Constants

DEFAULT_DD_SITE

PROD_ERRORS_INTAKE_SUBDOMAIN

Statics

DEFAULT_SYMBOLS

Traits

UnknownValue

Functions

async_receiver_entry_point_stream

async_receiver_entry_point_unix_listener

async_receiver_entry_point_unix_socket

begin_op

Track that an operation (of type op) has begun. Currently, we assume states are discrete (i.e. not nested). PRECONDITIONS: This function assumes that the crash-tracker is initialized. ATOMICITY: This function is atomic.

clear_additional_tags

clear_runtime_callback^⚠

Clear the registered runtime callback

clear_spans

clear_traces

consume_and_emit_additional_tags

default_max_threads

default_signals

disable

Disables the crashtracker. Note that this does not restore the old signal handlers, but rather turns crash-tracking into a no-op, and then chains the old handlers. This means that handlers registered after the crashtracker will continue to work as expected.

enable

Enables the crashtracker, if had been previously disabled. If crashtracking has not been initialized, this function will have no effect.

end_op

Track that an operation (of type op) has finished. Currently, we assume states are discrete (i.e. not nested). PRECONDITIONS: This function assumes that the crash-tracker is initialized. ATOMICITY: This function is atomic.

get_expected_receiver_pid

Returns the currently registered expected receiver PID, or 0 if unset.

get_receiver_unix_socket

get_registered_callback_type_ptr^⚠

Get the callback type C string pointer from the currently registered callback

get_tests_folder_path

init

Initialize the crash-tracking infrastructure.

insert_additional_tag

insert_span

insert_trace

is_runtime_callback_registered

Returns true if a callback is registered, false otherwise

on_fork

Reinitialize the crash-tracking infrastructure after a fork. This should be one of the first things done after a fork, to minimize the chance that a crash occurs between the fork, and this call. In particular, reset the counters that track the profiler state machine.

receiver_entry_point_stdin

receiver_entry_point_unix_socket

reconfigure

Reconfigure the crash-tracking infrastructure.

register_runtime_frame_callback

register_runtime_stacktrace_string_callback

remove_additional_tag

remove_span

remove_trace

report_unhandled_exception

This function is designed to be when a program is at a terminal state and the application wants to report an unhandled exception to the crashtracker If this crashes, then the application will also crash. Ensure that this API is called when the application is at a terminal state and exit quickly after.

reset_counters

Resets all counters to 0. Expected to be used after a fork, to reset the counters on the child ATOMICITY: The reset of each individual counter is atomic, but the entire reset is NOT. Should only be used when no conflicting updates can occur, e.g. after a fork but before ops start on the child.

set_expected_receiver_pid

Register the expected receiver PID for socket-based crash receivers.

signal_from_signum

Converts a signum into a Signal. Can’t use the from trait because we don’t own either type.

translate_si_code

update_config

Updates the crashtracker config for this process Config is stored in a global variable and sent to the crashtracking receiver when a crash occurs.

update_metadata

Updates the crashtracker metadata for this process Metadata is stored in a global variable and sent to the crashtracking receiver when a crash occurs.

Type Aliases

RuntimeFrameCallback

Function signature for runtime frame collection callbacks

RuntimeStacktraceStringCallback

Function signature for runtime stacktrace string collection callbacks