TL;DR: There is a new backup/restore interface in 23.9.1, but this is incompatible with backup JSON generated by prior versions. Therefore, before upgrading to this version, we recommend doing a full-volume docker backup in lieu of the backup/restore scripts as described here.

We’ve made a couple of significant changes in this release.

Migration to Metrics Backend

The metrics and generic-metrics backend have been enabled for self-hosted. This has been enabled on SaaS for a while now, and we’re happy to bring this feature to self-hosted customers. Many of our new features are now being built on this new backend, and it’ll be much more powerful as time goes on.

As of 23.9.1, release health sessions will now be writing to the metrics backend. In a few months, we will cutover completely to the metrics backend and remove the existing sessions infrastructure. We expect users to be able to smoothly upgrade after staying on this version of self-hosted for the amount of time specified by their SENTRY_EVENT_RETENTION_DAYS.

Improved Backup/Restore

The backup/restore scripts have been completely overhauled. The old scripts were under-tested and bug-prone, making it unlikely that data exported by them could be successfully restored on another instance. We’ve made some major changes to both the content of the exported JSON, and the interfaces that produce and consume it.

What’s Stayed the Same

You can still export all of the core, low-volume models of your Sentry instance for migration and data-processing purposes using the backup.sh script, and re-import them into another (clean!) database using the restore.sh script. Full-volume “snapshot” backups should still be done by taking a full docker backup of all sentry- prefixed volumes, as described in our docs.

What’s Changed

The format of the backup JSON has changed slightly, making it incompatible with older versions. Because of this, we strongly encourage users to do a full-volume docker backup before migrating. Going forward, the format will only be guaranteed up to the next major version. For instance, exports on self-hosted version 23.9._ will be importable on 23.9._ or 23.10._, but no higher).

Restores are now non-destructive of data by default: whereas previous restores assumed a clean database, or otherwise updated colliding data in place, new restores are strictly INSERT-only. In cases where INSERTing new data is not possible, like for global singleton options, existing values are re-used. The --overwrite_configs flag on the sentry import CLI command is provided to permit overwriting this singleton config data if the importing user so desires.

There is now a new, more powerful interface for creating more granular imports/exports. This interface can be accessed by using the export and import commands of sentry CLI tool in your docker-compose instance. Exports are no longer filtered by model, which was brittle and often left out necessary dependencies, making restoring from exports filtered in this way impossible. Instead, exports are grouped into coherent buckets of related content, called “scopes”. There are now three such export “scopes”:

• User: exports data associated with Sentry users only, like their emails, permissions, and login credentials. Exports in this scope can be filtered by username. Exports in this scope can be created using the sentry export users ... CLI command.
• Organization: exports data owned by a set of Sentry organizations, and the users that are members of that set. Exports in this scope can be filtered by organization slug. Exports in this scope can be created using the sentry export organizations ... CLI command.
• Global: exports all exportable data. Exports in this scope can be created using the sentry export global ... CLI command. This is equivalent to running backup.sh.

So, for example, to export the users alice and bob for use on another Sentry instance, one might invoke the CLI command docker compose run -v $(pwd)/sentry:/sentry-data/backup --rm -T -e web export users /sentry-data/backup/some_users.json --filter_usernames “alice,bob”.

All of the above CLI commands have companion sentry import variants for imported and filtering in data from a backup generated by sentry export.

Future releases will add more scopes to this interface, and will expand the set of models included for export.

Various other fixes & improvements

• fix: e2e test jq bug (#2410) by @azaslavsky
• feat(backup): Support new backup script (#2407) by @azaslavsky
• Decrease frequency of e2e tests (#2383) by @hubertdeng123
• Reduce logs coming from clickhouse (#2382) by @hubertdeng123
• Increase frequency of e2e test runs (#2375) by @hubertdeng123
• Remove nginx content-disposition hack for safari (#2381) by @hubertdeng123
• Attempt to fix integration test flakiness (#2372) by @hubertdeng123
• change health check for kafka service (#2371) by @johnatannvmd
• Add metrics and generic metrics backend (#2355) by @hubertdeng123
• Bump self-hosted e2e action commit sha (#2369) by @hubertdeng123