Skip to content
Telebugs Telebugs Self-hosted error tracking without the Sentry stack telebugs.com

Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The Telebugs Manual

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 configurationTelebugs behavior
Project namesImported as organization-slug/Project name to distinguish organizations.
Project platformMapped to the corresponding Telebugs platform. Unset or unmapped platforms use Other and are listed in the report.
Original numeric project IDsPreserved for ingestion URLs, independently of Telebugs’s internal project IDs.
Multiple public project keysPreserved for their original project. Active error-ingestion keys work on the imported route.
Disabled keysKept disabled.
Deployment path prefixPreserved 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 dataImport support
/api/<project-id>/envelope/Supported error envelopes, using the original key and project ID.
Legacy /store/ ingestionNot supported by this importer.
/security/, /minidump/, /unreal/<key>/Not supported by this importer.
/integration/vercel/logsNot supported by this importer.
Tracing, profiling, session replay, and other Sentry productsNot 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.