Add optional Sentry error reporting

[MaikelH]

Problem

Every failure in this tool is currently reported only as a line on stdout. If pg_dump fails, or the S3 upload fails after its one retry, the job logs an error and the container keeps running on schedule. Nobody is told. For a backup tool the consequence is the worst kind: you find out backups were broken at the moment you need one.

We want optional Sentry integration — off unless a DSN is configured, so existing deployments are unaffected.

Where failures happen today

Location	Failure	Current behaviour
backup.go doPostgresBackup	pg_dump exits non-zero	logged with stderr, job aborts
backup.go uploadToS3	upload fails twice	logged, local file retained
backup.go runBackup	local cleanup fails	logged, continues
main.go	config load / client init / scheduler start	logged, os.Exit(1)

The two that matter most are pg_dump failing and the upload failing after retry — both mean no backup exists for that run.

Findings from the SDK (verified against v0.48.0)

The slog handler alone will not give us alerts. github.com/getsentry/sentry-go/slog v0.48.0 emits Sentry Logs, not Issues. Its Option struct has only LogLevel, AttrFromContext, AddSource and ReplaceAttr, and Handle delegates straight to a sentry.Logger. There is no event path.

Note that Sentry's own slog docs show an example using an EventLevel field that does not exist in the released module — don't plan around it. Issues require explicit sentry.CaptureException(err) calls at the failure sites.

os.Exit will silently drop startup errors. The Go SDK's transport is asynchronous, so events are buffered and flushed by a background goroutine. main.go now has three os.Exit(1) calls, and os.Exit does not run deferred functions — a defer sentry.Flush(...) in main would never fire on exactly the error paths we most want reported. Each exit path needs an explicit flush.

Env var mapping needs extending. config/config.go only rewrites the s3_ prefix into a nested key:

if strings.HasPrefix(s, "s3_") {
    return strings.Replace(s, "s3_", "s3.", 1)
}

So a nested sentry: config block would not pick up SENTRY_DSN without changing that function.

Worth considering: cron monitoring, not just error reporting

Error reporting can only tell us about failures that occur. It cannot tell us a backup never ran — a crashed container, an OOM kill, a bad cron expression or a paused scheduler all produce silence, which is indistinguishable from success.

The Go SDK supports Sentry cron monitors via sentry.CaptureCheckIn with sentry.CrontabSchedule(...), and this application already holds exactly the cron string needed in cfg.Schedule. Wrapping runBackup in in-progress/ok/error check-ins would alert on a missed run, which is arguably the more valuable signal for a backup tool.

Open decisions

1. Issues only, or Issues + Logs? Explicit CaptureException is required either way. The slog handler could additionally ship INFO/WARN as Sentry Logs for context, at the cost of log volume and quota.
2. Include cron check-ins? Recommended, but it is a second Sentry product with its own setup and quota.
3. What to configure beyond the DSN — environment, release, sample rate, debug.
4. Release identifier. We tag CalVer (v2026.08.01) but the binary has no version embedded, so Release would need a build-time ldflags var to be meaningful.

Constraints

• Fully optional: no DSN means no Sentry initialization and no behaviour change.
• No secrets in Sentry payloads. PGPASSWORD and the S3 secret must never leave the process; pg_dump stderr in particular should be reviewed before attaching.
• Adds the first non-config runtime dependency to the project.

[MaikelH]

Implementation plan

Three phases, each independently shippable. Phase 1 delivers the actual ask; 2 and 3 are separable and can be dropped without rework.

Guiding decisions

Misconfiguration fails at startup. If a DSN is set but sentry.Init rejects it, exit non-zero rather than logging a warning and carrying on. Silently degrading to "no monitoring" is the worst outcome — you believe you have alerting and you don't. This matches the existing convention for S3 config and the storage class.

No DSN means no initialization at all. Not a disabled client, not a no-op transport — the SDK is never initialized. Existing deployments see zero behaviour change.

Call sites never branch on whether Sentry is on. A Reporter value with an enabled bool whose methods return early keeps if telemetry != nil out of backup.go. This matters because the capture points sit inside error paths that are already the most tangled code in the file.

---

Phase 1 — Error reporting

New config block

sentry:
  dsn: ''                    # empty disables Sentry entirely
  environment: 'production'
  sample_rate: 1.0
  debug: false

config/config.go gains a SentryConfig struct and a Sentry field. Defaults go in the defaults map as sentry.environment / sentry.sample_rate, following the s3.prefix precedent from #2.

The env rewrite must be generalized. Today it hardcodes one prefix:

if strings.HasPrefix(s, "s3_") {
    return strings.Replace(s, "s3_", "s3.", 1)
}

Replace with a loop over []string{"s3_", "sentry_"} so SENTRY_DSN reaches sentry.dsn. Without this the whole block is silently unreachable from the environment — which is how the S3 prefix bug in #2 happened, so it deserves a test rather than a manual check.

New telemetry package

A small package alongside config/ and storage/:

type Reporter struct{ enabled bool }

func New(cfg Config, release string) (*Reporter, error)  // no DSN -> disabled, nil error
func (r *Reporter) CaptureError(err error, tags map[string]string)
func (r *Reporter) Flush(timeout time.Duration)

New wraps sentry.Init with Dsn, Environment, SampleRate, Debug, Release, and AttachStacktrace: true.

Secret scrubbing via BeforeSend

Register a BeforeSend hook that redacts the configured Postgres password and S3 secret key from any outgoing event, when those values are non-empty. pg_dump receives its password through PGPASSWORD so it should not echo it, but "should not" is not a guarantee worth betting a credential on, and postgres_extra_opts is operator-supplied and could contain anything.

Capture points

Site	Tags	Rationale
doPostgresBackup failure	stage=pg_dump	no backup produced
uploadToS3 after retry	stage=s3_upload + bucket/key	backup exists locally only
runBackup cleanup failure	stage=cleanup	disk fills silently over time
main.go × 3 exit paths	stage=startup	service is not running at all

Flush — the part that is easy to get wrong

The transport is asynchronous, and os.Exit does not run deferred functions. A defer sentry.Flush() in main would never fire on any of the three startup error paths, which are precisely the ones worth reporting. Each os.Exit(1) needs an explicit Flush(2*time.Second) immediately before it, plus one on the graceful shutdown path in Start.

A flush at the end of each runBackup is also worth adding. It costs nothing on a daily schedule and bounds how long an event can sit unsent.

Release identifier

Release is what makes Sentry able to say "this started failing in v2026.08.01", and the binary currently carries no version. Add var version = "dev" in main, set at build time with -ldflags "-X main.version=$VERSION", threaded through a Dockerfile ARG and the tag name in .github/workflows/build.yml. Small, but it has to be done at build time so it cannot be retrofitted later without another release.

Tests

The Sentry DSN is a URL, so an httptest server can stand in for Sentry and assert what actually gets transmitted — the same approach already used for the S3 tests.

• disabled reporter performs no network I/O and does not panic
• an invalid DSN fails New rather than degrading silently
• a captured error reaches the fake Sentry endpoint with the expected tags
• BeforeSend scrubbing removes a known password from the payload
• SENTRY_DSN maps to sentry.dsn through the env provider

---

Phase 2 — Cron check-ins

This is the phase that catches "the backup never ran", which error reporting structurally cannot.

sentry.CaptureCheckIn wraps runBackup with in-progress on entry and ok/error on exit, using MonitorConfig{Schedule: sentry.CrontabSchedule(...)}.

The blocker is schedule translation. robfig/cron accepts descriptors that Sentry's crontab parser does not, and cfg.Schedule defaults to @daily. Needs a mapping:

robfig	Sentry
@daily / @midnight	0 0 * * *
@hourly	0 * * * *
@weekly	0 0 * * 0
@monthly	0 0 1 * *
@yearly / @annually	0 0 1 1 *
@every 6h	IntervalSchedule(6, MonitorScheduleUnitHour)
anything else	pass through as crontab

Table-driven test over exactly that mapping. Gated behind a sentry.monitor_slug setting so it stays opt-in independently of error reporting.

---

Phase 3 — Sentry Logs (optional)

Add github.com/getsentry/sentry-go/slog as a second handler so INFO/WARN records land in Sentry as Logs for context around an Issue.

Deliberately last, and genuinely optional. As established in the issue, this handler emits only Logs in v0.48.0 — it contributes nothing to alerting, costs quota, and duplicates what container log aggregation already does. Worth it only if you want the surrounding narrative attached to an incident in one place.

Implementation note: slog.New takes a single handler, so this needs a fan-out handler forwarding to both the existing JSON handler and the Sentry one. That is a small amount of custom code, not a library call.

---

Commit sequence

1. Add optional Sentry error reporting — config, telemetry package, capture sites, flush
2. Embed the build version for Sentry release tracking — ldflags, Dockerfile, workflow
3. Document Sentry configuration — README, config.yaml.example
4. (phase 2) Report backup runs as Sentry cron check-ins

Verification

Unit tests as above, then a real DSN end to end: force a pg_dump failure with bad credentials and confirm the Issue arrives with the right tags and release, and that no secrets appear in the payload. The sentry:sentry-instrument skill is available and can cross-check the wiring at implementation time.

Answers still needed

1. Phase 2 in or out?
2. Phase 3 in or out? (recommendation: out for now)
3. Default environment — production, or leave empty and require it to be set?