sentry.h File Reference

#include <glib.h>

Include dependency graph for sentry.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	dt_sentry_crash_observer_t) (const char *backtrace, size_t backtrace_len)
	Handed the crash backtrace from inside the crash handler.

Functions
void	dt_sentry_init (const gboolean have_gui)
void	dt_sentry_shutdown (void)
void	dt_sentry_add_crash_observer (dt_sentry_crash_observer_t observer)
	Register a function to be handed the backtrace when the process crashes.
gboolean	dt_sentry_backtrace_captured (void)
void	dt_sentry_record_module_usage (const char *category, const char *name)
void	dt_sentry_set_processed_image (const struct dt_image_t *img, const char *pipeline)

Typedef Documentation

dt_sentry_crash_observer_t

typedef void(* dt_sentry_crash_observer_t) (const char *backtrace, size_t backtrace_len)

Handed the crash backtrace from inside the crash handler.

Whether sentry's crash handler has already captured a gdb backtrace for the current crash. The local signal handler uses this to avoid running gdb twice. Returns FALSE when built without sentry support.

Parameters

backtrace	NUL-terminated backtrace text, owned by the caller and valid only for the duration of the call.
backtrace_len	its length in bytes.

Warning

Runs in a signal handler, on a process that is already dying. Use only async-signal-safe calls: no allocation, no locks, no conf, nothing that can block or fault on a corrupted heap.

Definition at line 62 of file sentry.h.

Function Documentation

dt_sentry_add_crash_observer()

void dt_sentry_add_crash_observer

(

dt_sentry_crash_observer_t

observer

)

Register a function to be handed the backtrace when the process crashes.

Sentry supplies the text and knows nothing about what any observer does with it; an observer decides for itself whether the crash concerns it. This module therefore carries no knowledge of GPUs, image formats or anything else that might want to look.

The pairing is made by the caller that owns both ends – see dt_init() in darktable.c – so neither this module nor an observer's module has to include the other.

Register during startup, before a crash can occur. At most a handful are supported and extras are ignored, rather than growing a structure a signal handler must walk. Does NOT require dt_sentry_init() to have run.

Parameters

observer

the callback; see the typedef for what it may safely do.

Referenced by dt_init().

dt_sentry_backtrace_captured()

gboolean dt_sentry_backtrace_captured

(

void

)

Definition at line 687 of file sentry.c.

References FALSE.

Referenced by dt_toplevel_exception_handler().

dt_sentry_init()

void dt_sentry_init

(

const gboolean

have_gui

)

Initialize sentry.io crash reporting.

On the very first launch (no consent decision recorded yet) and when a GUI is available, this shows a modal consent dialog explaining what is collected and why, and stores the user's choice. Sentry is only initialized when the user has opted in (conf key "sentry/enabled"). It enriches reports with OS and hardware context and enables crash-free session tracking.

Safe to call when built without sentry support (USE_SENTRY=OFF): it is a no-op.

Parameters

have_gui

whether a GUI is up and a consent dialog may be shown.

Definition at line 679 of file sentry.c.

Referenced by dt_init().

dt_sentry_record_module_usage()

void dt_sentry_record_module_usage	(	const char *	category,
		const char *	name
	)

Record that a module was used during this session, e.g. a view was entered, an iop module was enabled, or a lib panel was opened. Per-module counts are attached to crash reports as the "module_usage" context, so a crash shows which modules were exercised beforehand.

Parameters

category	short kind, e.g. "view", "iop", "lib".
name	module identifier (view module_name, iop op, lib plugin_name).

Must be called from the GUI thread. No-op without sentry, or before init / when the user has not opted in.

Definition at line 692 of file sentry.c.

Referenced by _gui_off_callback(), dt_lib_gui_set_expanded(), and dt_view_manager_switch_by_view().

dt_sentry_set_processed_image()

void dt_sentry_set_processed_image	(	const struct dt_image_t *	img,
		const char *	pipeline
	)

Record the image currently being processed, so crash reports show what was on the pipeline at the time. Only the file extension and image type flags are recorded (no file name or path). Attached as the "processed_image" context.

Cheap to call on every pipeline run: it is a no-op unless the image or pipeline actually changed. Safe to call from any pipeline thread.

Parameters

img	the image on the pipeline (its extension + type flags are read).
pipeline	short label of the pipeline, e.g. "darkroom"/"export".

No-op without sentry, or before init / when the user has not opted in.

Definition at line 696 of file sentry.c.

Referenced by dt_dev_pixelpipe_process().

dt_sentry_shutdown()

void dt_sentry_shutdown

(

void

)

Flush and shut down sentry. Marks the current session as a clean (crash-free) exit and increments the local clean-session counter. No-op if sentry was never initialized.

Definition at line 683 of file sentry.c.

Referenced by dt_cleanup().