Migrating from Self-hosted Sentry
Telebugs can import a self-hosted Sentry configuration while preserving the project IDs and public keys used by existing DSNs. After you route the original Sentry hostname to Telebugs, supported SDKs can continue sending errors without changing their DSN configuration.
Availability: Available in Telebugs 2.1.0 and the current CLI installers. Update the CLI and running application before importing.
This is a configuration import. It does not restore a Sentry database, copy historical issues, or automatically change DNS, HTTPS certificates, or your reverse proxy.
Prepare Telebugs
Install Telebugs and complete First Launch, including the administrator account. Run the migration as the account that manages that installation. The CLI must be able to access its Docker container.
For an existing Telebugs installation, make a backup before importing. Existing projects are kept; the importer never merges into or overwrites them.
Use telebugs migrate sentry --help to check that your CLI includes the command.
The command also checks that the running application supports it.
Import from a running Sentry installation
When Sentry and Telebugs use the same local Docker environment, provide the Sentry Compose directory and its original public URL:
telebugs migrate sentry \
--from /opt/sentry/self-hosted \
--source-url https://sentry.example.com
The command exports Sentry’s configuration, validates it, and shows the projects,
active and disabled key counts, and unsupported settings. Type import to apply
the displayed plan. Declining leaves Telebugs unchanged. The command does not
stop or modify Sentry.
To inspect the plan without an import prompt:
telebugs migrate sentry \
--from /opt/sentry/self-hosted \
--source-url https://sentry.example.com \
--dry-run
After reviewing the limitations, automation can add --accept-unsupported to
the import command. That flag explicitly accepts the reported omissions and
skips the prompt; it does not switch traffic.
Automatic export requires Sentry 24.1 or newer and exactly one running web
container in the supplied Compose project. The real migration workflow has been
tested with self-hosted Sentry 25.10.0 and the official Ruby SDK 5.22.1.
Import an existing JSON backup
For Sentry on another host, use an unencrypted partial JSON configuration backup. On a compatible Sentry installation, a global export can be created with:
cd /opt/sentry/self-hosted
umask 077
docker compose exec -T -e SENTRY_LOG_LEVEL=CRITICAL web \
sentry export global --no-prompt --silent - > sentry-configuration.json
Transfer the file securely to the Telebugs host, then run:
telebugs migrate sentry \
--backup ./sentry-configuration.json \
--source-url https://sentry.example.com
Choose either --from or --backup. The same --dry-run and
--accept-unsupported flags work with a backup file. A full database dump,
encrypted archive, or JSON mixed with log output is not accepted. Files must be
no larger than 63 MiB. An organization-scoped backup must include its organization,
projects, and project keys.
Sentry exports can contain passwords, tokens, and integration secrets. Keep the file private. The import report lists categories and counts without printing key values or copying user credentials into Telebugs.
What is preserved
| Sentry configuration | Telebugs behavior |
|---|---|
| Project names | Imported as organization-slug/Project name to distinguish organizations. |
| Project platform | Mapped to the corresponding Telebugs platform. Unset or unmapped platforms use Other and are listed in the report. |
| Original numeric project IDs | Preserved for ingestion URLs, independently of Telebugs’s internal project IDs. |
| Multiple public project keys | Preserved for their original project. Active error-ingestion keys work on the imported route. |
| Disabled keys | Kept disabled. |
| Deployment path prefix | Preserved when included in --source-url, for example https://sentry.example.com/monitoring. |
An organization prefix in a project name is not a permission boundary. Imported projects use Telebugs’s existing administrator access, UTC timezone, and normal new-project notification defaults.
What needs separate attention
The report identifies exported settings and record types that are not imported. These include users and passwords, organization and team membership, notification rules, integrations, rate limits, filters, allowed origins, and Sentry’s data-scrubbing settings. Review access, notifications, and sensitive-data handling in Telebugs before directing production errors to it.
Historical events, issues, comments, assignments, releases, source maps, and external files are not migrated. Keep Sentry available for history you still need. Configure source-map uploads and integrations for Telebugs separately.
Preserving a key does not add support for every Sentry endpoint or product:
| Endpoint or data | Import support |
|---|---|
/api/<project-id>/envelope/ | Supported error envelopes, using the original key and project ID. |
Legacy /store/ ingestion | Not supported by this importer. |
/security/, /minidump/, /unreal/<key>/ | Not supported by this importer. |
/integration/vercel/logs | Not supported by this importer. |
| Tracing, profiling, session replay, and other Sentry products | Not migrated. |
The platform label does not change these limits. Test the actual SDKs and event types your applications send.
Switch traffic without changing DSNs
For a DSN such as https://<key>@sentry.example.com/42, keep the original hostname,
HTTPS certificate, port, and any path prefix available. Route that address to
Telebugs through your DNS and reverse-proxy configuration. The importer does not
perform this infrastructure change.
Trigger an error from an application using its unchanged DSN. Confirm that it appears in the expected Telebugs project and check the backtrace, environment, release, tags, sensitive-data handling, and notifications. Keep Sentry and its data until the cutover is verified.
To return traffic to Sentry, restore the previous routing. Errors already received by Telebugs stay there; they are not copied back to Sentry.
Retries, conflicts, and key rotation
An import is one transaction. Invalid data or a conflicting project name or key refuses the whole import. Existing Telebugs projects and keys are not overwritten. Projects pending deletion or without exported keys are also refused.
Repeating the same imported configuration is safe: it creates no duplicate projects and does not reset keys or settings. Unrelated changes in ignored Sentry records do not prevent a retry. Version 1 imports one configuration per source URL; a later snapshot with changed project names, mapped platforms, or ingestion keys is refused. It is not an ongoing synchronization or a way to append further organization exports from the same source URL.
Regenerating a project’s token in Telebugs revokes all its imported Sentry keys. Repeating the import does not reactivate them. Treat token regeneration as a deliberate change to the applications using those old DSNs.