Enable the Sentry offline cache by default, keeping 50 reports

[karlspace]

Problem

Neither of the library's two Sentry entry points configures an offline cache:

• the Sentry.NLog target in Logging/BGLoggerConfiguration.cs (around line 613, used through BGLogger.Configuration.ErrorTracking)
• SentrySdk.Init in ErrorTracking/BGErrorTracking.cs:64

Without CacheDirectoryPath, the Sentry SDK sends straight over HTTP (decompiled Sentry.Internal.SdkComposer.CreateTransport, Sentry 6.6.0). A report that cannot be sent is lost: the station was offline, the endpoint was unreachable, or the process ended before the in-memory queue was flushed. That includes the crash report, which is sent from a process that is about to end.

With a cache directory, the SDK writes every envelope to disk before sending it. Whatever was not sent goes out after a network failure or on the next start.

Proposal

Enable the offline cache by default in both entry points:

• CacheDirectoryPath: a folder inside the application's data folder, e.g. %ProgramData%\<App>\ErrorReports. The SDK creates a subfolder per DSN.
• MaxCacheItems = 50 by default. The SDK default is 30, and when the limit is reached it deletes the oldest envelope whatever its level. A station that is offline for a while would otherwise lose an early crash to the warnings that follow. 50 keeps that window reasonable without an unbounded folder.
• InitCacheFlushTimeout = TimeSpan.Zero, so application start never waits for the cache to be sent.
• Make all three configurable on BGLoggerConfiguration and BGErrorTrackingConfiguration. Passing null or an empty value for the directory disables the cache.
• Do not let a folder that cannot be created break the SDK start. CachingTransport.Initialize does not catch a failed CreateDirectory, and Sentry.NLog then swallows it, so reporting silently stays off.

Depends on

#132: in single-file applications the application data folder currently collapses to %ProgramData%, so the cache folder should be derived only after that is fixed, or together with it.

Context

bgIndustrialAutomation Client currently sets this itself, by reflection on the protected TargetErrorTracking before switching error tracking on (MaxCacheItems = 100, cache under its settings folder). A library default would let applications drop that workaround.

[karlspace]

Thanks for the clear proposal. The point about the SDK dropping the oldest envelope whatever its level was the right argument for 50 over 30.

Implemented in 735bce6. It builds on the folder fixes from #132 (155e7c7) and #135 (afdb837), so the cache lands in the application's own folder on single-file builds and on Linux too.

Aspect	Behavior
Entry points	BGErrorTracking.Init and BGLogger.Configuration.ErrorTracking both go through one internal helper (ErrorTrackingCache.Apply)
CacheDirectoryPath	<ExecutionAutomaticApplicationDataFolder>/ErrorReports (e.g. %ProgramData%\<App>\ErrorReports; the SDK adds a subfolder per DSN)
MaxCacheItems	50
InitCacheFlushTimeout	TimeSpan.Zero, so application start never waits
Configuration	BGErrorTrackingConfiguration.CacheDirectoryPath / MaxCacheItems / InitCacheFlushTimeout; BGLoggerConfiguration.SentryCacheDirectoryPath / SentryMaxCacheItems / SentryInitCacheFlushTimeout. null or empty disables the cache. Set these before enabling.
Folder cannot be created	Cache disabled with a logged warning (BGLogger.Warn), and reports are still sent online. The SDK start is not broken and reporting is not silently off.
Tests	ErrorTrackingCacheTests: enabled/created, disabled for null/empty/whitespace, uncreatable folder (below an existing file) does not throw, defaults on both configurations

Verified with an unreachable DSN (127.0.0.1:9). Both entry points left the unsent report on disk:

[BGErrorTracking] ErrorReports\Sentry\<dsn-hash>\__processing\…envelope (6259 bytes)
[BGLogger/NLog]   ErrorReports\Sentry\<dsn-hash>\__processing\…envelope (9233 bytes)

Sentry 6.10.0 (merged in the same push) keeps all three option names unchanged. bgIndustrialAutomation Client can now drop its reflection workaround on TargetErrorTracking and set BGLogger.Configuration.SentryMaxCacheItems = 100 instead, if it wants to keep 100.

[github-actions]

🎉 This issue has been resolved in version 3.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀