![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
First checked 2026-09-29. This file was mechanically checked against 8f4638a04e on 2026-09-29 — every file:line citation resolved, every backticked symbol looked up in the tree, every OPEN/planned status claim tested, and every gate or baseline number it quotes compared with tools/check_module_boundaries.sh and tools/include_baseline.txt. No per-claim semantic read was done: a citation that resolves can still describe the wrong thing, so this is a floor, not a verification. Nothing was found wrong by those checks.
Sentry is a hosted error and crash monitoring service. An application links a small client library; when the application crashes (or wants to report an event), the client packages up a description of what happened — a stack trace, the OS and app version, some context — and uploads it to a Sentry project over HTTPS. Maintainers then browse those reports on a web dashboard instead of waiting for users to file (usually incomplete) bug reports. Sentry also aggregates sessions to tell you how often the app runs without crashing ("release health").
Ansel uses Sentry for exactly two things:
It is opt-in: nothing is sent unless the user agrees on first launch, and it can be turned off at any time. No images, file names, or personal data are ever sent.
Note — Sentry is only one of Ansel's two optional data flows. Anonymous usage analytics (which features are used, on which platforms) go to a separate service, PostHog; see Usage analytics (telemetry). The two share a single first-launch consent dialog (one checkbox each) but are otherwise independent and separately toggleable. The user-facing explanation of everything collected lives in the Data privacy page of the user manual.
Project dashboard: https://aurelienpierreeng.sentry.io/projects/ansel/ Crash-free monitor: https://aurelienpierreeng.sentry.io/monitors/1388118/?project=4511598693253200&statsPeriod=24h
We vendor sentry-native as a git submodule at src/external/sentry-native, pinned to a release tag. It is built statically with the inproc backend and linked into libansel. Its HTTP transport reuses the libcurl dependency Ansel already requires on Linux/macOS, and uses WinHTTP on Windows — so no new system dependency.
When USE_SENTRY=OFF the module compiles to no-ops, so the rest of the code never needs #ifdefs.
All of this lives in src/common/sentry.c / sentry.h. The public API is three functions:
| Function | When | What it does |
|---|---|---|
| dt_sentry_init(have_gui) | end of dt_init() | honors sentry/enabled, then sentry_init() |
| dt_sentry_shutdown() | end of dt_cleanup(), just before dt_conf_cleanup() | records the clean session, flushes, sentry_close() |
| dt_sentry_backtrace_captured() | from the signal handler | tells the local gdb fallback to stand down |
Consent is gathered once, by a single dialog shared with usage analytics, implemented in src/gui/privacy_consent.c (dt_privacy_ask_consent()). On the very first launch with a GUI it shows one checkbox per built-in data flow ("Send crash reports" and "Share anonymous usage statistics") plus a link to the user-facing Data privacy page, then writes the per-feature toggles. dt_sentry_init() itself no longer prompts — it only reads sentry/enabled. The toggle also lives in Preferences ▸ Storage ▸ Privacy ("Send anonymous crash reports").
Two configuration keys are involved:
Sentry is initialised only if sentry/enabled is true. In non-GUI tools (CLI) the consent dialog cannot be shown, so Sentry initialises only if the user already opted in during a GUI session.
The inproc backend installs its own SIGSEGV handler. Ansel also has a long-standing local handler in src/common/system_signal_handling.c that forks gdb to write a backtrace file. Signal handlers chain in reverse install order, so Sentry must be installed after the last dt_set_signal_handlers() call, so nothing installed during startup can displace ours. That is why dt_sentry_init() sits at the very end of dt_init(): Sentry runs first on a crash, then chains down into the local handler.
After init we attach environment context (never any user content):
Every event carries a release and an environment, which drive grouping and crash-free metrics:
The compiler/optimization build type (Release/RelWithDebInfo/Debug) is kept separately as the build_type extra — it is orthogonal to the channel.
We enable auto_session_tracking, so Sentry records a session per run and computes its duration and outcome (exited vs. crashed) — this feeds the crash-free rate on the dashboard.
In addition, every event is stamped with session_seconds (a tag + numeric extra) by the before_send/on_crash hooks, computed from darktable.start_wtime. For crashes this is the exact time-to-crash. Clean sessions also update local counters mirrored onto later events: sentry/clean_sessions, sentry/last_session_seconds, sentry/total_session_seconds.
On a crash, the on_crash hook (Linux) forks gdb against the dying process, captures thread apply all bt full, and attaches it to the report as gdb-backtrace.txt. Because gdb resolves symbols locally using the on-disk debug info, this attachment is human-readable even when server-side symbolication is not set up.
To avoid running gdb twice, on_crash sets a flag (dt_sentry_backtrace_captured()); the local handler in system_signal_handling.c checks it and skips its own gdb run when Sentry already captured one. When Sentry is disabled (opted-out users, CLI, CI) the local handler runs as before and writes its /tmp/ansel_bt_*.txt file. (Windows/macOS don't use gdb; there the native Sentry stack trace is the report.)
With the inproc backend, the crash is written to a local database (~/.cache/ansel/sentry-native/) during the crash, and uploaded on the next launch of Ansel (a dying process cannot reliably complete an HTTPS upload). So: crash → reopen Ansel → the report appears. This is normal and is not a bug.
A native crash event from inproc contains raw instruction addresses plus the list of loaded modules — not function names. Sentry turns addresses into function @ file:line server-side, but only if it has the matching debug-information files. If they were never uploaded, the dashboard shows frames as addresses and marks the modules "missing: no debug information could be found".
So readable native stack traces require uploading debug files for the exact binaries you ship. (The gdb-backtrace.txt attachment is the fallback that does not depend on this.)
Symbols are matched to a crash by build-id, which survives stripping. So you upload the debug info from the build tree (which has DWARF) and it matches the stripped, shipped binary.
This is the single source of truth used by both CI and humans. It:
It is intentionally not wired into the build: building via build.sh, the regular PR CI, or plain cmake --build never uploads anything. Uploads happen only when the script is run explicitly.
Only the nightly workflows (which build the artifacts users actually download) upload symbols, as a dedicated step after the build:
Each passes SENTRY_AUTH_TOKEN (a repository secret) into the script. The regular PR CI (ci.yml) and build.sh do not upload.
The Linux nightly additionally installs the Ubuntu dbgsym debug packages for glib2 and gtk3 and scans /usr/lib/debug, so frames in those bundled libraries also resolve. Their build-ids are stable for a given nightly because the AppImage bundles the runner's copies. libc is not bundled (it comes from each user's host), so it cannot be symbolicated centrally — the gdb-backtrace.txt attachment covers it instead. macOS/Windows bundle stripped glib/gtk from Homebrew/MSYS2 with no separate debug info, so only Ansel's own frames resolve there.
In GitHub ▸ Settings ▸ Secrets and variables ▸ Actions, set one secret:
Create one at https://aurelienpierreeng.sentry.io/settings/auth-tokens/.
Tip: run with -d control to see [sentry] crash reporting initialized and confirm the feature is active. The local crash database is at ~/.cache/ansel/sentry-native/; a pending *.envelope there means a captured crash that has not been uploaded yet (it will be, on the next launch).
Established 2026-09-30 against aac2ee1321.
ansel.exe is linked as a GUI-subsystem binary: it owns no console, so everything written to stdout or stderr is discarded unless the caller arranged otherwise. main() (src/apps/ansel/main.c) therefore redirects both into
A plain run does write that file. That matters because for a long time we assumed no log existed on Windows at all, and asked users for -d runs that produced strictly less:
So, to triage a Windows report:
A build without #1493 has neither fix: for those, the log is under LOCALAPPDATA%\Microsoft\Windows\INetCache\ansel\, if Windows has not removed it yet, and a -d run has no output anywhere.
Established 2026-10-16 against 0baeb88ed8.
A crash on Windows writes an ansel_bt_*.txt report through DrMingw (exchndl.dll): the version, the faulting address, one line per frame as module!symbol+offset, then every loaded module with its address range. libansel.dll carries its symbol table, so the frames are named, but there are no line numbers. To find the instruction:
Reading from location FFFFFFFFFFFFFFFF is not a read at -1. The processor raised a general-protection fault, which carries no address, and Windows prints -1 for it. A misaligned movaps/movapd causes one — the case measured on 0baeb88ed8, in iop-notes.md under colorbalancergb — and so does a pointer that is not canonical.
To turn a Sentry issue into a fix without clicking through the web UI, use tools/sentry-fetch-issue.sh. It pulls an issue's latest event (stack trace, tags, device / display / module_usage / processed_image contexts) and downloads its attachments — including the gdb-backtrace.txt Ansel attaches on Linux crashes — into a folder, and prints a readable summary on stdout:
Output (default sentry-issue-<id>/): summary.txt (read first), event.json (full event), issue.json (metadata), and any attachments (gdb-backtrace.txt, …).
Auth/scopes. This reads issue data, so it needs a token with event:read, project:read and org:read — the organization token used for symbol upload (project:releases/project:write) is not sufficient and returns HTTP 403. Create a User Auth Token with those scopes (it can also carry the release/write scopes, so one token serves both scripts) at https://aurelienpierreeng.sentry.io/settings/account/api/auth-tokens/ and put it in .sentry-auth (git-ignored) or SENTRY_AUTH_TOKEN. The region host defaults to https://de.sentry.io to match the project's EU data residency (override with SENTRY_HOST).
The "fix it" loop. Pair the fetch with an AI coding assistant (e.g. Claude Code) for a tight loop:
Triage from CI. .github/workflows/sentry-triage.yml is a manual (workflow_dispatch) wrapper: from the Actions tab, "Run workflow", paste an issue id/URL. It runs the fetch script, attaches the backtrace bundle as an artifact, prints the summary to the run's step summary, and opens a GitHub issue once (deduplicated by a sentry-issue:<id> marker) so the crash lands in the tracker. It only fetches and surfaces — it does not change code or open a PR.
It needs a repository secret SENTRY_READ_TOKEN: a Sentry User Auth Token with event:read + project:read + org:read. This is separate from the SENTRY_AUTH_TOKEN used by the nightly workflows for symbol upload — that one is an organization token with release/write scopes and returns HTTP 403 on issue reads. (A single User Auth Token carrying both sets of scopes could serve both, but keeping them separate scopes each minimally.)
For a more hands-off setup, Sentry's own Seer (AI root-cause / autofix) and the GitHub integration can suggest fixes and open PRs directly from an issue; and an issue alert can auto-create a GitHub issue. Those run server-side and are configured in the Sentry project settings, independently of this script.
| Path | Role |
|---|---|
| src/external/sentry-native | the sentry-native client (git submodule) |
| DefineOptions.cmake | USE_SENTRY, SENTRY_DSN, BUILD_CHANNEL |
| src/config.cmake.h | bakes DT_BUILD_CHANNEL/DT_BUILD_TYPE; declares darktable_commit_hash |
| tools/create_version_c.sh | bakes darktable_commit_hash (full SHA, the Sentry/PostHog release) |
| tools/get_git_version_string.sh | human version string / package name (describe-based) |
| src/external/CMakeLists.txt | builds the submodule (inproc, static) |
| src/CMakeLists.txt | links sentry, defines HAVE_SENTRY / SENTRY_DSN |
| src/common/sentry.c / .h | init/shutdown, context, sessions, on_crash gdb attach |
| src/gui/privacy_consent.c / .h | the shared first-launch consent dialog (crash + analytics) |
| src/common/system_signal_handling.c | local gdb fallback; defers to Sentry when it captured |
| src/darktable.c | calls dt_sentry_init() / dt_sentry_shutdown() |
| data/anselconfig.xml.in / .dtd, tools/generate_prefs.xsl | the sentry/enabled preference |
| tools/sentry-upload-symbols.sh | debug-file (symbol) upload |
| tools/sentry-fetch-issue.sh | pull an issue's backtrace + attachments locally to fix it |
| .github/workflows/sentry-triage.yml | manual CI triage: fetch backtrace, artifact, auto-open a GitHub issue |
| .github/workflows/{lin,mac,win}-nightly.yml | call the upload script with the CI secret |
Found 22f623c0be, 2026-06-25. Verified against 42eca0e8fe, 2026-09-29.
Sentry crash issues: tools/sentry-fetch-issue.sh <issue-id|url> pulls a Sentry issue's backtrace locally (writes summary.txt, event.json, attachments). The region host is https://de.sentry.io (EU data residency) — sentry.io/us.sentry.io give 403/401. Reading issues needs a User Auth Token (not the org token used for symbol upload). See doc/sentry.md for setup details.