feat: offline caching (inproc & breakpad) #1490

jpnurmi · 2026-01-23T13:26:32Z

Summary

Adds offline caching support for the inproc and breakpad backends, allowing envelopes to be persisted locally for debugging and offline scenarios. When enabled, envelopes are retained in a cache/ subdirectory within the database path, regardless of whether the send succeeds or fails.

On startup, the cache is pruned based on the configured limits (max items, age, size), removing entries from oldest to newest until constraints are satisfied. The pruning algorithm is based on Crashpad's prune_crash_reports.cc.

API

New options:

sentry_options_set_cache_keep(opts, int enabled) - Enables/disables offline caching
sentry_options_set_cache_max_items(opts, size_t items) - Maximum number of cache entries (default: 30)
sentry_options_set_cache_max_size(opts, size_t bytes) - Maximum cache directory size (no default max size)
sentry_options_set_cache_max_age(opts, time_t seconds) - Maximum age for cache entries (no default max age)

Usage

sentry_options_set_cache_keep(options, true);
sentry_options_set_cache_max_items(options, 10);              // 10 items
sentry_options_set_cache_max_size(options, 8 * 1024 * 1024);  // 8 MB
sentry_options_set_cache_max_age(options, 30 * 24 * 60 * 60); // 30 days

Comparison

Option	Native	Cocoa/iOS	Java/Android
Enable/disable	`cache_keep` (default: off)	Always on	Always on
Max items	`cache_max_items` (30)	`maxCacheItems` (30)	`maxCacheItems` (30)
Max size	`cache_max_size` (0)	-	-
Max age	`cache_max_age` (0)	- (90 days, hardcoded)	-

Limitations

Crashpad backend: Not yet supported - coming separately in feat(crashpad): offline caching #1493
HTTP retry: Not implemented in this PR

Test Plan

Unit tests for age-based and size-based cache pruning logic (test_cache.c)
Integration tests for end-to-end caching behavior (test_integration_cache.py)

Co-authored-by: @JoshuaMoelans
Closes: #1461

Before "revert separate caching folder implementation" #1461

Cast cache_max_age to time_t to avoid implicit signedness conversion between uint64_t and time_t. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add explicit static_cast<time_t>() for cache_max_age to fix -Wsign-conversion warning on Windows with clang-cl. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

#1490

github-actions · 2026-01-26T09:34:12Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 96a8cd7

#1490

For consistency with time-related operations throughout the codebase. This adds a time.h dependency to the public header, but it's a lightweight standard C header available since C89. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ine-caching

src/sentry_database.c

src/backends/sentry_backend_crashpad.cpp

src/sentry_database.c

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move size accumulation into else branch so age-pruned files don't count toward size limit. Remove the size subtraction on prune which caused bin-packing behavior (keeping older smaller files while removing newer larger ones). Add test for size-based pruning order. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Check CreateFileW return value before calling SetFileTime/CloseHandle - Change TEST_CHECK to TEST_ASSERT since mtime setup is a precondition Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cache_dir is NULL when cache_keep is false, and sentry__path_free handles NULL safely. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

src/backends/sentry_backend_crashpad.cpp

Crashpad's AgePruneCondition and DatabaseSizePruneCondition only accept days and KB respectively, causing precision loss for sub-day ages and sub-KB sizes. Replace them with MaxAgePruneCondition (seconds) and MaxSizePruneCondition (bytes) that handle zero as "no limit" internally. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ine-caching

Re-order cache_max_items before max_size/max_age for visibility as the most relevant default limit. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…disabled When cache_keep is false, the crashpad database should be pruned with the original upstream defaults (2 days, 8 MB) rather than the cache_max options which default to 0 (disabled). This preserves the existing pruning behavior for users who have not opted into offline caching. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

include/sentry.h

mujacica · 2026-02-09T09:49:53Z

src/backends/sentry_backend_crashpad.cpp

-    data->db->CleanDatabase(60 * 60 * 24 * 2);
+    // large. When offline caching is enabled, the cache_max_* options are
+    // used instead.
+    time_t max_age = 2 * 24 * 60 * 60; // 2 days


Maybe extracting these constants somewhere would make sense (instead of keeping them as crashpad-only defaults in a function)?

These are just some legacy defaults that were used by the crashpad backend before offline caching was introduced. These defaults are specific to the crashpad backend and are not used anywhere else. The idea is to retain full backwards compatibility by using the old legacy defaults unless the user opts in for offline caching. I updated the comments - I hope it's clear now :)

…ine-caching

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/backends/sentry_backend_crashpad.cpp

Avoid short-circuit evaluation skipping stateful conditions by combining MaxItemsPruneCondition, MaxSizePruneCondition, and MaxAgePruneCondition into a single CachePruneCondition that evaluates all checks unconditionally. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ine-caching

jpnurmi · 2026-02-11T13:09:03Z

Hey @JoshuaMoelans, we decided to merge these two

Don't hesitate to drop comments when you're back, and I'll follow up if there's anything.

JoshuaMoelans and others added 16 commits January 23, 2026 14:21

Import offline caching POC (#1461)

536c4a1

Before "revert separate caching folder implementation" #1461

breakpad: delete .dmp

5742eda

Flatten cache/

6c75ccf

Add tests

8f3ffd5

Respect has_breakpad

3410b6c

SENTRY_TRANSPORT=none

799d219

Fix set_file_mtime on Windows

3c40494

Present cache_max_age in seconds

a37ac86

Present max_cache_size in bytes

20815bd

Tweak docs & signatures

ef96547

Fix warning

e96d9d4

Fix test_unit::cache_max_age

93aefb2

Fix sign conversion warning on Windows

f4936d5

Cast cache_max_age to time_t to avoid implicit signedness conversion between uint64_t and time_t. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add changelog entry for offline caching feature

7eddee4

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Fix sign conversion warning in CleanDatabase call

8d40ec1

Add explicit static_cast<time_t>() for cache_max_age to fix -Wsign-conversion warning on Windows with clang-cl. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Clarify test_integration_cache

b28663f

jpnurmi pushed a commit that referenced this pull request Jan 26, 2026

feat: offline caching + tests for inproc & breakpad (#1490)

0fbf22c

#1490

jpnurmi changed the title ~~WIP: offline caching + tests for inproc & breakpad~~ feat: offline caching (inproc & breakpad) Jan 26, 2026

jpnurmi mentioned this pull request Jan 26, 2026

feat(crashpad): offline caching #1493

Open

jpnurmi pushed a commit that referenced this pull request Jan 26, 2026

feat: offline caching + tests for inproc & breakpad (#1490)

87cb944

#1490

jpnurmi pushed a commit that referenced this pull request Jan 26, 2026

feat: offline caching + tests for inproc & breakpad (#1490)

df20439

#1490

jpnurmi pushed a commit that referenced this pull request Jan 26, 2026

feat: offline caching (inproc & breakpad) (#1490)

06eee53

jpnurmi and others added 3 commits January 27, 2026 13:57

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/offl…

7bc7856

…ine-caching

Update CHANGELOG.md

9e09bd0

jpnurmi marked this pull request as ready for review February 3, 2026 11:02

sentry bot reviewed Feb 3, 2026

View reviewed changes

src/sentry_database.c Show resolved Hide resolved

cursor bot reviewed Feb 3, 2026

View reviewed changes

src/backends/sentry_backend_crashpad.cpp Show resolved Hide resolved

src/sentry_database.c Outdated Show resolved Hide resolved

Log warning when envelope caching fails

747edb1

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi and others added 2 commits February 3, 2026 13:13

Add NULL check after path clone in sentry__cleanup_cache

e0cb46e

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi requested review from JoshuaMoelans and mujacica February 3, 2026 14:16

jpnurmi pushed a commit that referenced this pull request Feb 4, 2026

feat: offline caching (inproc & breakpad) (#1490)

3057ae8

jpnurmi and others added 2 commits February 4, 2026 10:29

Add INVALID_HANDLE_VALUE check and use TEST_ASSERT for set_file_mtime

e30846f

- Check CreateFileW return value before calling SetFileTime/CloseHandle - Change TEST_CHECK to TEST_ASSERT since mtime setup is a precondition Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Remove redundant conditional around sentry__path_free

1d565d6

cache_dir is NULL when cache_keep is false, and sentry__path_free handles NULL safely. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi pushed a commit that referenced this pull request Feb 4, 2026

feat: offline caching (inproc & breakpad) (#1490)

5cb8afa

cursor bot reviewed Feb 4, 2026

View reviewed changes

src/backends/sentry_backend_crashpad.cpp Outdated Show resolved Hide resolved

jpnurmi and others added 2 commits February 4, 2026 11:31

Fix size_t conversion warning on 32-bit Windows

f0e5075

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi pushed a commit that referenced this pull request Feb 4, 2026

feat: offline caching (inproc & breakpad) (#1490)

9964555

jpnurmi and others added 6 commits February 4, 2026 16:50

Add cache_max_items option for Android & Cocoa compat

25da5e1

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'master' into jpnurmi/feat/offline-caching

fc0f6cc

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/offl…

57cb740

…ine-caching

Update CHANGELOG.md

fd3c257

Default cache max size/age to 0 (disabled)

8a17813

Re-order cache_max_items before max_size/max_age for visibility as the most relevant default limit. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi pushed a commit that referenced this pull request Feb 9, 2026

feat: offline caching (inproc & breakpad) (#1490)

9e8e6d9

jpnurmi mentioned this pull request Feb 9, 2026

feat: add sentry__path_rename() #1508

Merged

mujacica approved these changes Feb 9, 2026

View reviewed changes

jpnurmi and others added 3 commits February 9, 2026 12:37

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/offl…

6a80d77

…ine-caching

docs: mention default value in sentry_options_set_cache_keep

dd0ef77

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: clarify crashpad database pruning defaults

bbfb4d2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry bot reviewed Feb 9, 2026

View reviewed changes

src/backends/sentry_backend_crashpad.cpp Outdated Show resolved Hide resolved

jpnurmi and others added 2 commits February 9, 2026 14:41

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/offl…

96a8cd7

…ine-caching

jpnurmi merged commit b5c53dd into master Feb 11, 2026
45 checks passed

jpnurmi deleted the jpnurmi/feat/offline-caching branch February 11, 2026 13:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: offline caching (inproc & breakpad) #1490

feat: offline caching (inproc & breakpad) #1490

jpnurmi commented Jan 23, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Uh oh!

mujacica Feb 9, 2026

Uh oh!

jpnurmi Feb 9, 2026

Uh oh!

Uh oh!

jpnurmi commented Feb 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

feat: offline caching (inproc & breakpad) #1490

feat: offline caching (inproc & breakpad) #1490

Conversation

jpnurmi commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

API

Usage

Comparison

Limitations

Related

Test Plan

Uh oh!

github-actions bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mujacica Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

jpnurmi Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jpnurmi commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jpnurmi commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 26, 2026 •

edited

Loading

jpnurmi commented Feb 11, 2026 •

edited

Loading