feat: offline caching (inproc & breakpad) by jpnurmi · Pull Request #1490 · getsentry/sentry-native

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 WIP: 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 8a17813

#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>

src/sentry_database.c

Subtract file size from accumulated_size when a file is pruned (by age or size). Previously, pruned files' sizes were still counted, causing subsequent valid files to be incorrectly pruned when both cache_max_age and cache_max_size were set. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

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>

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

WIP: feat(crashpad): offline caching #1493

Draft

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>

Revise crashpad_backend_prune_database

b1a4671

sentry bot reviewed Feb 3, 2026

View reviewed changes

src/sentry_database.c Outdated Show resolved Hide resolved

jpnurmi and others added 2 commits February 3, 2026 12:53

Add NULL checks after path allocations in cache handling

2e1c63b

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

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/sentry_database.c Show resolved Hide resolved

src/sentry_database.c Show resolved Hide resolved

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 5 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>

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 wants to merge 34 commits intomasterfrom
jpnurmi/feat/offline-caching

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jpnurmi commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 26, 2026 •

edited

Loading