Skip to content

Latest commit

 

History

History
180 lines (137 loc) · 10.6 KB

telemetry.md

File metadata and controls

180 lines (137 loc) · 10.6 KB

Usage analytics (telemetry) with PostHog {#telemetry}

[TOC]

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.

What this is, in one paragraph

Separately from crash reporting ([Sentry](@ref sentry)), Ansel can send anonymous usage analytics so the maintainers can see which features and platforms are actually used and decide where to spend effort. This goes to PostHog, a product-analytics service, in its European Union region (https://eu.i.posthog.com). It is opt-in, separate from crash reporting, and can be turned off at any time. No images, file names, or personal data are ever sent — only counts and coarse system facts, keyed by a random per-installation id.

This page is for maintainers. The user-facing explanation of everything collected and why lives in the Data privacy page of the user manual.

Vocabulary

  • Project API key — a public, write-only ingest key (prefix phc_). It only allows sending events; it cannot read data. Like the Sentry DSN, it is compiled into the binary and is not a secret.
  • Event — one named record (e.g. session_start) with a free-form JSON properties object.
  • distinct_id — PostHog's identity for an event. We use a random per-installation UUID (telemetry/install_id), generated on first run. It is not tied to any account or machine identifier, and lets PostHog group a single installation's events without identifying the user.

The client

There is no third-party SDK. The whole implementation is src/common/telemetry.c / telemetry.h, ~200 lines, built on dependencies Ansel already has:

  • json-glib to serialize event bodies,
  • libcurl to POST them.

Events are sent asynchronously so the UI never blocks on the network: dt_telemetry_capture() serializes the event on the caller's thread and pushes the JSON string onto a GAsyncQueue; a background GThread (_telemetry_worker) pops bodies and POSTs them to {POSTHOG_HOST}/capture/. Network errors are ignored (best-effort). dt_telemetry_shutdown() pushes a stop sentinel, joins the worker (so the last in-flight POST completes), and frees state.

The worker relies on curl_global_init() having already run; it has, because Sentry's transport / curl_tools initialize curl earlier in startup.

Build wiring

  • DefineOptions.cmake declares USE_TELEMETRY (default ON) and POSTHOG_HOST (the EU host).
  • The project API key is hardcoded in src/common/telemetry.c (POSTHOG_API_KEY), the single source of truth — analogous to the baked-in Sentry DSN. Set it to "" there to disable uploads while keeping the code.
  • src/CMakeLists.txt adds the source and defines HAVE_TELEMETRY=1 and POSTHOG_HOST="…".

When USE_TELEMETRY=OFF the module compiles to no-ops, so callers never need #ifdefs.

Runtime behavior

The public API:

Function When What it does
dt_telemetry_init(have_gui) end of dt_init() honors telemetry/enabled, starts the worker, sends session_start
dt_telemetry_shutdown() start of dt_cleanup() sends session_end, drains & joins the worker
dt_telemetry_capture(event, props) anywhere queues a custom event (takes ownership of props)
dt_telemetry_record_module_usage(category, name) GUI thread counts a view/lib/iop use for this session
dt_telemetry_record_file_type(img, pipeline) pipeline threads records the kind of image processed

Consent (opt-in)

Telemetry shares the single first-launch consent dialog with crash reporting (dt_privacy_ask_consent() in src/gui/privacy_consent.c): it has one checkbox per built-in data flow and a link to the user-facing Data privacy page. dt_telemetry_init() itself does not prompt — it only reads the toggle. Keys:

  • telemetry/enabled — user-facing boolean; a confgen key, shown in Preferences ▸ Storage ▸ Privacy ("Share anonymous usage statistics").
  • telemetry/install_id — the random distinct_id (non-confgen; created lazily on first enabled run).
  • privacy/consent_asked — the shared sentinel that records the dialog has been answered (see the [Sentry doc](@ref sentry) for why it must not be a confgen key).

Telemetry initializes only if telemetry/enabled is true and a non-empty POSTHOG_API_KEY was compiled in.

What is collected

Four event types: a per-run start/end pair, plus two discrete "something happened" events.

module_used is sent the first time each module is used in a session (deduped: one event per distinct module per session), with properties category (view/lib/iop) and name. file_opened is sent the first time each file extension is processed in a session, with extension and the type flags raw/ldr/hdr/monochrome/needs_demosaic and pipeline.

These two are the answer to "I crashed-tested and saw no usage data": unlike session_end (below), which is only emitted on a clean exit, discrete events are sent immediately as usage happens, so they survive a later crash. They are also the idiomatic PostHog shape — you count/break-down the events directly (e.g. file_opened broken down by raw, or module_used by name).

session_start carries the machine profile (_telemetry_system_properties()), so every session — healthy or crashing — is represented for population statistics (something Sentry sessions can't give you, since they have a fixed schema):

  • app_version (human version string), commit (full git SHA — the cross-build-consistent release id, mirrors Sentry's release), build_type (CMake build type: Debug/Release/RelWithDebInfo), build_cflags (full C compiler flags baked at configure time — contains -DNDEBUG in Release/RelWithDebInfo, absent in Debug; use this to confirm whether assert() was active in a crashing binary), build_channel (nightly for official builds, self-build otherwise — filter on this to exclude local/dev builds from population stats),
  • os (pretty name), cpu_cores, ram_gb,
  • opencl (bool) and gpu (first OpenCL device name),
  • on Linux/BSD: display_server (x11/wayland), desktop_environment,
  • dpi, ppd, screen_width, screen_height.

session_end (clean exit only) carries the session aggregate (_telemetry_session_end_properties()):

  • session_seconds,
  • module usage as flat numeric properties: mod_view_<name>, mod_lib_<plugin>, mod_iop_<op> → use counts,
  • file types as flat numeric properties: ext_<extension> → count (never names or paths),
  • images_processed, raw_images, nonraw_images, mosaiced_images (distinct image+pipeline combinations seen).

Why flat, not nested? PostHog only filters / breaks down / aggregates on top-level scalar event properties. Nested JSON objects are ingested and visible in a single event's detail, but do not appear as dimensions you can build insights on — so module usage and file types are emitted as flat mod_* / ext_* properties (_flatten_counts()), each character outside [A-Za-z0-9_] replaced by _.

The two record_* functions accumulate into in-memory hash tables / counters guarded by a mutex (_stats_lock), because module usage is recorded on the GUI thread while file types are recorded from pipeline worker threads. record_file_type de-duplicates per image+pipeline, mirroring the crash-context dedup, so darkroom's constant reprocessing of the same image counts once. The same call sites also feed Sentry's crash context — see the table below.

Shared instrumentation points

The usage data is recorded at the same choke points that feed Sentry's crash context, with a telemetry call placed next to each Sentry call:

Site Sentry call Telemetry call
src/views/view.c (view entered) dt_sentry_record_module_usage("view", …) dt_telemetry_record_module_usage("view", …)
src/libs/lib.c (panel expanded) dt_sentry_record_module_usage("lib", …) dt_telemetry_record_module_usage("lib", …)
src/develop/imageop.c (module enabled) dt_sentry_record_module_usage("iop", …) dt_telemetry_record_module_usage("iop", …)
src/develop/pixelpipe_hb.c (pipeline start) dt_sentry_set_processed_image(…) dt_telemetry_record_file_type(…)

The difference in scope: Sentry keeps these as crash context (the state at the moment of a crash), while PostHog receives the per-session aggregate at clean shutdown.

Viewing the data

PostHog project (EU): create insights under Product analytics. Useful breakdowns:

  • session counts over time and by app_version / os / build_type,
  • display_server, desktop_environment, gpu distributions (where to focus QA),
  • count module_used broken down by name to rank which views/panels/modules are used, and file_opened broken down by extension or raw to see the formats people edit — these work even for sessions that crashed,
  • on session_end events (clean exits), sum the mod_* / ext_* properties for full per-session counts.

How to disable it

  • For a build/distribution: configure with -DUSE_TELEMETRY=OFF (no analytics code at all), or set POSTHOG_API_KEY to "" in src/common/telemetry.c (code present, uploads disabled).
  • For a user: untick Preferences ▸ Storage ▸ Privacy ▸ Share anonymous usage statistics, or set telemetry/enabled=FALSE in anselrc. Declining the first-launch dialog has the same effect.

File map

Path Role
DefineOptions.cmake USE_TELEMETRY, POSTHOG_HOST
src/CMakeLists.txt adds the source, defines HAVE_TELEMETRY / POSTHOG_HOST
src/common/telemetry.c / .h init/shutdown, async POST worker, events, per-session aggregates
src/gui/privacy_consent.c / .h shared first-launch consent dialog (crash + analytics)
src/darktable.c calls dt_telemetry_init() / dt_telemetry_shutdown()
src/views/view.c, src/libs/lib.c, src/develop/imageop.c, src/develop/pixelpipe_hb.c the recording call sites
data/anselconfig.xml.in / .dtd, tools/generate_prefs.xsl the telemetry/enabled preference