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

Introduction

The Telebugs Manual cover

Telebugs is a lightweight, self-hosted error tracking system and a seamless drop-in alternative to Sentry. It collects, groups, and notifies you about errors in your applications. This helps you fix bugs faster while keeping your data private and fully under your control.

Telebugs is fully compatible with existing Sentry SDKs. It works out of the box with popular languages and frameworks, including JavaScript (React, Vue, Angular, Svelte, Astro, Solid), Ruby on Rails, Laravel, Django, Go, .NET, ASP.NET Core, Swift, Spring Boot, and many more.

Unlike cloud-based services with recurring subscriptions and event quotas, Telebugs is a one-time purchase that you install on your own server:

  • No monthly fees or hidden costs
  • Unlimited errors, events, projects, and team members
  • Complete data ownership and privacy with no third-party processing (perfect for GDPR, CCPA, or regulated industries)
  • Simple Docker-based setup in about 5 minutes, with automatic SSL and updates
  • Focused solely on error tracking: detailed reports, breadcrumbs, notifications (email and push), team collaboration with no unnecessary bloat

This manual will guide you through installing Telebugs, setting up projects, integrating SDKs, and mastering its features to make your software more reliable.

Let’s get started. Your errors won’t fix themselves!

Telebugs home | Live demo

Telebugs Philosophy

Telebugs adheres strictly to its guiding principles: simplicity, security, and user control in error tracking. This directly counters the pitfalls of modern SaaS tools, where providers lock basic features behind ever-increasing subscription costs.

At its core, Telebugs is built on a straightforward idea: error tracking should be simple, secure, and fully under your control. This philosophy influences every decision—from design and features to deployment—ensuring the tool empowers developers without unnecessary complexity.

The Pillars of Telebugs

Telebugs rests on five foundational pillars:

I: Less is More

Error tracking does not need complex setups or long learning curves. Telebugs stays minimal on purpose. It is easy to install, easy to use, and easy to maintain. This approach runs through the whole system.

II: Be Boring

Telebugs does not try to impress. It just works reliably every day. Good tools run quietly in the background. You never get excited about running cd to change directories. Telebugs aims for that same quiet reliability.

III: Own Your Data

Big providers scare you with stories about data loss. They say files vanish without constant backups and replication. There is some truth to that. But they blow it out of proportion to keep you locked in. Backups matter, yet they are not as hard or scary as claimed. You can manage them yourself. No sysadmin required.

IV: Freedom to Scale

You do not need Kubernetes for Telebugs, though it works if you want it. Start with the cheapest Hetzner VPS. Upgrade the server as your project grows. Telebugs will not scale forever, but it handles most indie projects, small teams, and medium businesses through their full lifecycle.

V: Finished Software

Telebugs aims to be finished software. It ships complete and stable, without endless new features. Not all tools need constant growth.

Think about the cd command needing a subscription account. That would be ridiculous. Yet many modern tools end up there. They add more and more features, needed or not. Then they gate basic access behind paywalls or guest modes. Telebugs avoids that path. It provides what you need. Nothing more.

How the sausage is made

Telebugs uses proven and reliable technologies. Knowing the stack matters. When you buy Telebugs, you get the full source code. You own it for life. You can modify it any way you like (just don’t share it, since Telebugs is not open source. See the Software License Agreement).

Telebugs builds on these technologies:

  • Ruby on Rails: A Ruby web framework with decades behind it. Simple and boring. No revolution needed here.

  • Turbo: This covers the set of tools that power modern Rails apps out of the box. Thanks to Turbo (and the next item), Telebugs skips JavaScript frameworks entirely. Proven, simple, and easy to maintain.

  • Stimulus: Think of it as jQuery for 2025, but even simpler, since JavaScript has improved a lot.

  • Solid Queue: Handles background jobs, like sending error notifications. This lets Telebugs run without Redis. Fewer dependencies to deal with.

  • SQLite: The real MVP of the stack. A fantastic library that needs no introduction and almost zero administration.

That’s it! Error processing really can be this simple.

So is Telebugs only for Rails devs? No. You never have to touch the code if you don’t want to. You can read it, sure. It’s pure Ruby. Probably the most readable programming syntax out there. It almost feels like English.

Not familiar with Ruby? Pair it with your favorite LLM and tweak away. That said, I don’t expect you to need that. Telebugs ships with everything essential.

Telebugs isn’t here to change the world. It’s here to leave you alone. And that’s exactly the point.

Installation

Telebugs installs in under 5 minutes with a single command. The process stays simple on purpose.

Before diving in, check the prerequisites and system requirements. Then follow the step-by-step guide.

Prerequisites

Telebugs is self-hosted. You need a few things ready before starting.

  1. Your own domain name (for example, example.com or telebugs.example.com).
  2. A machine connected to the internet.
  3. Basic tech skills (you should know how to use SSH and run terminal commands).

New to self-hosting? No problem. The installer takes care of everything. It handles Docker installation, all configuration, and even the TLS certificate. You just run one command. Then sit back and have a cup of tea.

System Requirements

Telebugs can run on almost any hardware. This includes a VPS, cloud server, home server, or even a Raspberry Pi. It supports both AMD64 (also known as x86-64, x64, x86_64, and Intel 64) and ARM64 (also known as AArch64) architectures. In short, if Docker runs on it, Telebugs will too.

Supported Platforms

Telebugs works with over 100 programming languages and frameworks through Sentry SDKs. Popular options include JavaScript (Node.js, React, Angular), Python (Django, Flask), Ruby (Rails), Java (Spring), PHP (Laravel), .NET (ASP.NET Core), and Go. For the full list, see Supported Platforms in the appendix.

Error Throughput

Use this table to estimate what your server can handle.

CPU coresEst. max errors/secondEst. max errors/day
2302,592,000
4605,184,000
812010,368,000
1624020,736,000

These numbers are rough estimates. Actual throughput depends on CPU, RAM, application complexity, and error volume. Throughput is shared across all projects in one Telebugs installation. With two projects, each gets about half. With four projects, each gets about a quarter, and so on.

  • RAM: 1 GB
  • Disk space: 40 GB
  • CPU: 1 core
  • RAM: 4 GB
  • Disk space: 80 GB
  • CPU: 3 cores

Operating System Compatibility

  • Tested on Linux (Ubuntu, Debian, Alpine, Rocky) and any OS that supports Docker.
  • Also works on macOS.

Installation Steps

The whole process takes less than 5 minutes. Here is how to get started.

  1. Choose a server. Pick a machine to host Telebugs (cloud or local). I recommend DigitalOcean (see the DigitalOcean setup guide) or Hetzner (see the Hetzner setup guide).

  2. Point your domain. Update your DNS records so your domain points directly to your server IP. Do not use proxying. Telebugs handles TLS itself.

    Cloudflare DNS configuration example

  3. Connect to your server. Use SSH or your provider console.

  4. Run the installation command. Copy the command from your purchase email and paste it into the server terminal. Installation can take up to 5 minutes.

    Your personal command will look similar to this:

    bash -c "$(curl -fsSL https://auth.telebugs.com/install/a12b-c34d-e56f-g78h)"

    Important: Keep your install command private. Do not share it or post it online. It is tied to your account and license. The purchase token is included in your email.

When you run this command, it will automatically install Docker on your server (assuming you’re using Linux, which is standard for most cloud environments). It will then download the latest version of the Telebugs app as a Docker container. During setup, you’ll be prompted to enter your domain name so we can generate a TLS certificate for you.

Successful Telebugs installation

That is it. Visit https://YOUR-DOMAIN in your browser to create the first user. After that, you can invite your team.

Telebugs updates itself automatically every night at 1 AM (server local time). You can disable updates or run other admin tasks (backups, password resets, etc.) with the telebugs command. Connect to your server and run telebugs to see all options.

💡 Want multiple Telebugs installations? You need a separate license for each domain.

Custom TLS Certificates

Telebugs automatically creates and installs a Let’s Encrypt TLS certificate for you. If you already have your own certificate, you can use it instead.

TLS Termination with Nginx

Nginx is the recommended way to use a custom certificate. It works as a reverse proxy and handles TLS termination.

During the telebugs setup command, leave the domain prompt empty and press Enter. This runs Telebugs on http://localhost:5555 without TLS.

  1. Install Nginx.

    apt-get update
apt-get install nginx

  2. Create a config file at /etc/nginx/sites-available/telebugs.

    server {
   listen 443 ssl;
   server_name <YOUR_DOMAIN>;

   ssl_certificate /path/to/your/fullchain.pem;
   ssl_certificate_key /path/to/your/privkey.pem;

   location / {
       proxy_pass http://localhost:5555;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
   }
 }

 server {
   listen 80;
   server_name <YOUR_DOMAIN>;
   return 301 https://$host$request_uri;
 }

  3. Enable the config.

    ln -s /etc/nginx/sites-available/telebugs /etc/nginx/sites-enabled/

  4. Test and restart Nginx.

    nginx -t
systemctl restart nginx

Nginx now handles your certificate and forwards traffic securely to Telebugs.

TLS Termination with HAProxy

HAProxy is another solid option for custom certificates.

Leave the domain prompt empty during setup, just like with Nginx.

  1. Install HAProxy.

    apt-get update
apt-get install haproxy

  2. Add this to /etc/haproxy/haproxy.cfg.

    frontend https_frontend
  bind *:443 ssl crt /path/to/your/certificate.pem
  mode http
  option httplog
  default_backend telebugs_backend

backend telebugs_backend
  mode http
  server telebugs_server localhost:5555 check
  option http-server-close
  http-request set-header X-Forwarded-Proto https
  http-request set-header X-Forwarded-For %[src]
  http-request set-header X-Forwarded-Host %[req.hdr(Host)]
  http-request set-header X-Real-IP %[src]

    Note: The certificate.pem file must contain both the certificate and private key concatenated.

    For Let’s Encrypt:

    cat fullchain.pem privkey.pem > /etc/ssl/private/certificate.pem

  3. Test and restart HAProxy.

    haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl restart haproxy

HAProxy now handles your certificate and forwards traffic to Telebugs.

Kubernetes Installation

You can install Telebugs on Kubernetes using the official Helm chart.

This option is not beginner-friendly. Use it only if you already know Kubernetes and Helm. For most users, follow the standard installation steps.

First Launch

When you first visit your new Telebugs domain, you land on the setup screen. Here you create the initial admin account and get started right away.

Create Your First User

The setup form is straightforward. It asks for:

  • Profile picture (optional). Shows up across the dashboard and to your teammates.
  • Full name. Anything you want.
  • Email address. Does not need to match your purchase email. Use whatever you prefer.
  • Password. Pick something strong. Telebugs trusts you to choose wisely. No forced rules.

Click Create your account. That is it. You are now logged in and ready to use Telebugs.

Fun Fact

The name field autocompletes with “Grace Hopper” as a small tribute.

Grace Hopper was a pioneering computer scientist and U.S. Navy rear admiral. In 1947, her team found an actual moth stuck in a relay causing a computer malfunction. They taped it into the log book and noted they had “debugged” the machine. This is the origin of the term “bug” in computing.

With Telebugs you carry on the tradition of finding and fixing bugs (without the physical moths).

Creating Your Project

Projects are the core way to organize errors in Telebugs. Each project keeps errors from a specific app, language, or environment separate. Every project gets its own unique token that your code uses to send errors.

This section covers recommended setup and organization tips.

How to Organize Projects

Treat projects like folders for errors. Group them logically.

Common approaches (mix them as needed):

  • By language or framework. One project for Ruby errors, another for JavaScript. Backend and frontend stay cleanly separated.
  • By subsystem. Split web requests, background jobs, or cron tasks if you want separate notifications or access.
  • By environment. Keep staging separate from production. Use clear names like “App-Prod” and “App-Staging”.
  • Custom setup. Put everything in one project or split by team. Telebugs does not enforce rules. Use what works for you.

Grouping with Apps

If you have multiple related projects (most commonly a backend and a frontend), you can group them under one app. This keeps the dashboard tidy and makes navigation faster.

See the Apps section for details.

Example Project Setup

Take a simple blog built with Ruby on Rails and some JavaScript on the frontend.

  • Backend project

    Name: Blog or blog.example.com Purpose: Catch server-side Ruby/Rails errors.

  • Frontend project

    Name: Blog (JavaScript) or blog.js Purpose: Catch client-side errors.

This split lets you assign different team members, set separate alerts, and spot patterns faster.

Creating a Project

Click New Project in the top-right of the dashboard.

Fill in:

  • A clear project name.
  • The reporting timezone (defaults to your browser; change to server or team timezone if needed).
  • The platform (sets the icon and tailors the integration guide).

Copy the token after creation and add it to your code.

Sending Your First Error Report

You have a project. Now connect your app so Telebugs can start catching errors automatically.

Telebugs uses compatible Sentry SDKs. This means you follow the official Sentry integration guide for your platform, but point it at your Telebugs DSN.

Find Your Setup Instructions

Open your project in the dashboard. If no errors have arrived yet, Telebugs shows tailored SDK instructions right there. They include your exact DSN and link to the official Sentry docs for the platform you selected.

The DSN is the unique URL that routes errors to this project. It looks like:

https://[email protected]/123

Copy it carefully.

Install the SDK

Add the Sentry SDK to your app. The process is the same as for Sentry itself.

Example for Ruby on Rails:

  1. Add to your Gemfile:

    gem "sentry-rails"

  2. Run:

    bundle install

  3. Initialize it (usually in config/initializers/sentry.rb):

    Sentry.init do |config|
  config.dsn = "https://[email protected]/123"
end

  4. Restart your app.

For JavaScript, Python, PHP, Go, etc., follow the official Sentry guide for your platform. Just replace the DSN with yours from Telebugs.

Test the Connection

Trigger a test error in your code. Examples:

  • Ruby: raise "Test error from Telebugs"
  • JavaScript: Sentry.captureException(new Error("Test"))

The error should appear in your Telebugs project within seconds.

If nothing shows up:

  • Double-check the DSN (copy-paste again).
  • Make sure the SDK initializes early in your app lifecycle.
  • Restart or redeploy the app.
  • Confirm your server can reach the internet (no firewall block).

Feature Notes

Telebugs focuses on core error tracking. It works perfectly with:

  • Error reports
  • Breadcrumbs
  • Contexts
  • Tags
  • User information

Advanced Sentry features (Performance Tracing, Session Replay, Profiling) are not supported. Disable them in your SDK config if they are on by default (e.g., set traces_sample_rate = 0.0).

That is it! Your app is now reporting to Telebugs.

Team Management

Team management lets you invite collaborators, assign roles, control project access, and manage notifications.

Start by clicking your profile icon in the top-right and selecting Team Management.

Team Roles

Telebugs uses two roles:

  • Admin: Full access. Can manage settings, projects, users, and see all errors.
  • Member: Limited access. Can view and resolve errors in assigned projects only.

Start new users as members. Promote later as needed.

Inviting Team Members

Go to Team Management > Members.

Copy the invite link and share it with trusted people.

The link works for anyone, so keep it private. Regenerate if needed.

Joining as a Team Member

Click the invite link.

Create an account or log in.

You start with no project access. Ask an admin to assign projects.

Promoting or Demoting Members

In Members, check the box next to a user to make them admin (or uncheck to demote).

Changes save automatically.

Removing Team Members

In Members, click the remove icon next to the user and confirm.

You can re-invite later if needed.

Recovering Access

In Members, click the user’s name.

Copy the recovery link from Account recovery and send it to them.

Project Access

Go to Team Management > Project access.

Check projects each user can access.

Changes apply immediately.

Team Notifications

Go to Team Management > Notifications.

Check projects where users get email alerts.

This is for email only. Other integrations (like Slack) are separate.

Next Steps

Customize project settings or notifications next.

Account Settings

Account settings let you update your profile, manage security, and control notifications.

Click your profile icon in the top-right and select Account Settings.

The page includes a sidebar navigation with sections such as General, Security, Sessions, and Notifications.

General

The General section contains settings for your profile, name, and local development preferences.

Profile Picture

Your profile picture shows next to your name in the dashboard and team views.

To upload or change it:

  1. In the Your profile picture card, click the preview area (shows your current picture or the default user icon).
  2. Select a new image file from your device.
  3. The preview updates immediately.
  4. Click Update profile picture.

To remove it and revert to the default icon:

  1. Hover over (or click) the preview area – a trash icon overlay will appear if a custom picture is set.
  2. Click the trash icon to clear the picture.
  3. Click Update profile picture to confirm.

Changing Your Name

Your name appears in team lists and notes.

To change it:

  1. In the Your name card, enter your new full name in the text field.
  2. Click Change name.

There are no restrictions on length or characters.

Preferred Local Editor

Choose your preferred text editor for “Open in Editor” links in error backtraces. This allows you to quickly open source files locally from Telebugs.

To set it:

  1. In the Preferred local editor card, select your editor from the Local editor dropdown.
    • Options include None (disable local open) and supported editors (e.g., VS Code, RubyMine, etc.).
  2. Click Update editor preference.

Local Source Code Paths (per project)

Configure the local path to each project’s source code on your machine. This enables “Open in Editor” links for errors from production/deployed environments when a preferred editor is selected.

To configure paths:

  1. In the Local source code paths (per project) card, find your projects listed.
  2. For each project, enter the full local filesystem path to its source code in the text field.
    • A placeholder example is provided (e.g., /Users/username/projects/project-name).
  3. Click Update local paths at the bottom of the card.

If you are not a member of any projects yet, a message “You are not a member of any projects yet.” will be shown instead of the form.

Security Settings

Go to the Security tab for API keys, email, and password.

Regenerate API Key

Your API key lets you interact with Telebugs programmatically.

In Security, click Regenerate to get a new one.

Copy the new key and update your integrations immediately.

Change Email Address

Enter your new email and current password, then click Change email.

Verify the new email via the confirmation link sent to it.

Change Password

Enter your current password, new password, and confirmation.

Click Change password.

Log In on Another Device

Generate a sign-in link for quick access on new devices.

Go to the Sessions tab, then copy the link from Log in on another device.

The link expires after 4 hours. Do not share it.

Notification Preferences

Control which projects send you email notifications.

Go to the Notifications tab, then toggle checkboxes for each project.

Changes save automatically.

Appearance

The Appearance settings allow you to customize the look and feel of the Telebugs user interface to match your preferences. You can access these settings by clicking your avatar in the top-right corner and clicking the Appearance button.

Important: These settings are global and apply to all users on your Telebugs instance. Changes made here will affect the interface appearance for everyone.

The dialog provides three independent customization options:

Width

Controls the maximum width of the main dashboard and content areas.

  • Standard (default)

    Limits the content width for better readability on larger screens. The interface uses comfortable margins on the sides.

  • Wide

    Expands the dashboard to use the full available width of the browser window. Ideal if you prefer seeing more information at once (e.g., longer stack traces or wider tables).

Font

Changes the primary font used throughout the entire Telebugs interface. Telebugs uses modern system fonts by default for a clean, native look.

  • Default

    Uses the standard system sans-serif font stack (e.g., -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, etc.) for all text in the interface.

  • Monospace

    Switches the entire interface to use a monospace font globally (e.g., similar to Consolas, Menlo, or DejaVu Sans Mono). This applies to all UI text, including menus, tables, and dashboards—not just code areas.

Theme

Controls the color scheme of the entire application.

  • Follow system (default)

    Automatically switches between light and dark mode based on your operating system’s appearance setting.

  • Light Forces the interface to use the light theme regardless of system preference.

  • Dark Forces the interface to use the dark theme regardless of system preference.

Notifications

Telebugs supports email, push notifications, and webhooks for real-time alerts on errors.

Configure global settings in your profile > Notification Configuration.

Conditions for alerts (apply to all channels):

  • New error occurs.
  • Error reoccurs after resolution.
  • Frequency exceeds threshold (e.g., >10 in 5 minutes).

Projects can disable channels individually (see Project Settings). Users can opt out per project in their profile.

See sub-sections for setup.

Email

Emails go to your account email.

To configure:

  1. Go to Notification Configuration > Email.
  2. Fill the form and save.
  3. Test with Send test email.
  4. Disable with the toggle.

Configuration Form

The Email notifications configuration form defines global settings that all projects inherit. Complete the fields as follows:

  • Provider: Select your email provider from the dropdown. Telebugs supplies preset configurations for common providers (Gmail, Outlook, etc.). Choose Custom SMTP to enter your own server settings manually.
  • Outgoing (SMTP) server: Enter the SMTP server address used to send emails (for example, smtp.gmail.com for Gmail). This field is required.
  • Port: Specify the port number for the SMTP server. Typically 587 (TLS) or 465 (SSL). This field is required.
  • Username: Enter the username for your SMTP server—usually your email address or the username provided by your email service. Leave blank if authentication is not required. Required if your provider requires login.
  • Password: Enter the password for your SMTP account. Leave blank if authentication is not required. Required if your provider requires login.
  • Domain: The HELO domain used by the SMTP server (for example, example.com). This field is required.
  • From address: The email address that appears as the sender of notification emails. Commonly, a no-reply address. Optional.
  • Encryption: Select the encryption method for the SMTP connection: None, SSL, or TLS. This field is required.
  • Authentication: Specify if SMTP authentication is required: None, Login, or Plain. If you choose an option other than None, you must provide a username and password. This field is required.

Push Notifications

Push notifications deliver real-time alerts to your desktop browser or mobile device.

Set up global push settings first. Projects can disable them individually, and users can opt out per project in their profile.

Notifications go to devices where you have granted permission (browser prompt or device settings).

You can receive alerts for:

  • A new error occurring for the first time.
  • An error reoccurring after being resolved.
  • Error frequency exceeding a threshold (e.g., more than 10 reports in 5 minutes).

For the best mobile experience, install Telebugs as a Progressive Web App (PWA). See the PWA installation section below.

Configuring Push Notifications

  1. Click your profile in the top-right and select Notification Configuration.
  2. Choose Push in the sidebar.
  3. Fill the form and click Save Configuration. A green checkmark appears next to Push when configured.
  4. Click Send test push notification to verify.
  5. If prompted, allow notifications in your browser or device. A confirmation shows the test was sent – check your device.
  6. To disable globally, toggle off Enable push notifications. The icon changes to a crossed-out bell.

Real errors will trigger push notifications based on project rules, including the error message, project name, and a direct link.

Push Configuration Form

  • VAPID subject (required): A contact URL or email for your instance, e.g., https://telebugs.example.com or mailto:[email protected].

Installing Telebugs as a Progressive Web App (PWA)

Installing as a PWA gives a native-app feel and more reliable push notifications on mobile. It is optional but recommended.

Benefits

  • Faster loading.
  • Push notifications even when the browser is closed.
  • Full-screen, app-like experience.

Android (Chrome)

  • Open Telebugs in Chrome.
  • Tap the three-dot menu > Add to Home screen. Or tap the automatic Install prompt at the bottom if it appears.
  • Confirm Add or Install.

iOS (Safari)

  • Open Telebugs in Safari.
  • Tap the Share icon (square with upward arrow).
  • Scroll and select Add to Home Screen.
  • Tap Add.

Desktop (Chrome) – Optional

  • Open Telebugs in Chrome.
  • Click the + icon in the address bar or menu > Install Telebugs.
  • Confirm Install.

Note: Steps may vary slightly by browser version. Keep your browser updated and allow notifications when prompted.

Webhooks

Send POST to services like Slack or Discord.

To configure:

  1. Go to Notification Configuration > Webhooks.
  2. Click Create Configuration.
  3. Fill form and save.
  4. Test with Test.
  5. Edit by clicking the name.

Add Webhook Form

  • URL: Public endpoint.
  • Name: Optional.
  • Template: Slack, Discord, Custom.
  • Body: JSON with placeholders.

Placeholders

PlaceholderDescriptionExample
{{project_name}}The name of the project where the error occurred.Backend, example.com
{{trigger}}The event that caused the notification or error alert."error", "reoccurrence", "error frequency exceeded"
{{subject}}A short description of the error or affected part of the code.NoMethodError in ScoresController#create, Error in Thread.java
{{culprit}}The specific method, function, or code location responsible for the error.ScoresController#create
{{location}}The file or line number where the error originated.app/controllers/scores_controller.rb:42
{{error_type}}The class or type of the error.NoMethodError, Error, Exception
{{error_message}}The detailed message associated with the error.undefined method '+' for nil, division by zero
{{project_url}}A link to the project’s dashboard in Telebugs.https://telebugs.example.com/projects/7
{{view_url}}A link to view the specific error instance in Telebugs.https://telebugs.example.com/errors/107

Slack Setup

In Slack: Channel > Integrations > Incoming Webhooks > Add to Slack > Copy URL.

In Telebugs: Use Slack template, paste URL.

Example payload:

{
  "username": "Telebugs",
  "text": "{{project_name}}: {{trigger}} - {{error_type}}: {{error_message}}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*{{trigger}}* from <{{project_url}}|{{project_name}}>\n\n*{{error_type}}{{culprit}}*\n{{error_message}}\n\n*Location*\n{{location}}"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "View"
          },
          "url": "{{view_url}}"
        }
      ]
    }
  ]
}

Discord Setup

In Discord: Server Settings > Integrations > Create Webhook > Copy URL.

In Telebugs: Use Discord template, paste URL.

Example payload:

{
  "content": "**{{trigger}}** from [{{project_name}}]({{project_url}})\n[View error]({{view_url}})",
  "embeds": [
    {
      "color": 16711680,
      "fields": [
        {
          "name": "{{error_type}}{{culprit}}",
          "value": "{{error_message}}"
        },
        {
          "name": "Location",
          "value": "{{location}}"
        }
      ]
    }
  ]
}

Microsoft Teams Setup

Microsoft Teams supports rich notifications via Incoming Webhooks using Adaptive Cards.

Create Webhook in Teams

  1. In Microsoft Teams, go to the channel where you want notifications.
  2. Click More options (•••) next to the channel name.
  3. Select Manage channel > Edit.
  4. Search for Incoming Webhook and select Add (or Configure if already added).
  5. Enter a name (e.g., “Telebugs”) and optionally upload an image.
  6. Click Create.
  7. Copy the generated webhook URL and click Done.

In Telebugs: Use Teams template, paste URL.

Example payload:

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
          {
            "type": "TextBlock",
            "text": "**{{trigger}}** from [{{project_name}}]({{project_url}})",
            "wrap": true,
            "size": "Medium",
            "weight": "Bolder"
          },
          {
            "type": "TextBlock",
            "text": "**{{error_type}}{{culprit}}**",
            "wrap": true,
            "spacing": "Small"
          },
          {
            "type": "TextBlock",
            "text": "{{error_message}}",
            "wrap": true,
            "spacing": "None"
          },
          {
            "type": "TextBlock",
            "text": "**Location**",
            "wrap": true,
            "spacing": "Medium"
          },
          {
            "type": "TextBlock",
            "text": "{{location}}",
            "wrap": true,
            "spacing": "None"
          }
        ],
        "actions": [
          {
            "type": "Action.OpenUrl",
            "title": "View Error",
            "url": "{{view_url}}"
          }
        ]
      }
    }
  ]
}

This payload creates a formatted card with bold trigger/project, error details, location, and a View Error button.

Custom Webhooks

Use Custom template. Build your JSON with placeholders.

Example:

{
  "project_name": "{{project_name}}",
  "trigger": "{{trigger}}",
  "subject": "{{subject}}",
  "culprit": "{{culprit}}",
  "location": "{{location}}",
  "error_type": "{{error_type}}",
  "error_message": "{{error_message}}",
  "view_url": "{{view_url}}"
}

Projects

Projects organize error tracking for specific apps or services. Each has its own reports, settings, and access controls.

This section covers viewing projects, dashboards, pinning, and settings.

Project Overview

View all projects in the main dashboard or by clicking “Projects” in navigation.

Each project card shows:

  • Platform icon (e.g., Ruby, JavaScript).
  • Name (click to open).
  • Sparkline of recent errors (24 hours).
  • Dropdown for actions like settings.

Use New Project in top-right to add more.

Individual Project View

Click a project to open its dashboard for analyzing errors.

Key elements:

  • Project picker dropdown: Switch projects or access settings.
  • Releases link: View release history.
  • Search bar: Find errors by message, type, or details (live updates).
  • Date range selector: Filter by time (e.g., today, last week) with pager.
  • Stats overview: Total reports, new vs. reoccurred.
  • Interactive chart: Error volume over time; zoom on spikes.
  • Error list: Grouped unique errors with type, message, timestamp, and count. Click for details.
  • Filters: All, resolved, unresolved; sort by last seen or count.

If no errors, dashboard shows SDK setup instructions. Refreshes automatically as reports arrive.

Use search and filters to triage high-volume unresolved errors. Chart helps spot deploy or traffic patterns.

Pinning Projects

Pin projects to keep them at the top of the dashboard for quick access.

To pin/unpin:

  1. Click three dots on the card.
  2. Select Pin project or Unpin project.

Pinned projects show a pin icon and stay at the top, even in apps.

Notes:

  • Independent of app pinning.
  • Multiple pins allowed; ordered by pin time.

Pin critical or active projects to streamline workflow.

Project Settings

Access via three dots on card > Settings, or inside project > project name dropdown > Project Settings.

General Settings

  • Name: Update for clarity, e.g., “AwesomeApp Backend”. Click Rename.
  • Timezone: Set to match team or servers (affects dates in reports). Search/select, Change timezone. Use UTC for global teams.
  • Platform: Choose for icon and tailored SDK guides. Save changes.

These make the dashboard more intuitive without affecting data.

Token Settings

Tokens allow your app to send reports securely.

  • Project token: View/copy/regenerate if compromised (invalidates old one).
  • DSN: Full URL with token. Copy for SDK config.

Store in env vars, not code. Test after regenerate with a sample error.

Access Control

Control who sees the project.

View team list and toggle checkboxes for access.

Admins: full control; members: view/resolve only.

Changes save automatically. See Team Management for roles/invites.

Use for segmented teams, e.g., backend devs on backend projects.

Notifications Settings

Enable alerts via preferred channels without overload.

  • Channels: Toggle Email, Push, Webhooks. Configure/test each.
  • Rules: Set for new errors, reoccurrences, frequency thresholds.
  • Recipients: Toggle per user for targeted alerts, e.g., on-call.

Combine channels for redundancy. Test with simulated errors to avoid fatigue.

Danger Zone

Irreversible actions; back up first.

  • Stats: Disk space, report count.
  • Partial purge: Remove details from old reports, keep stats.
  • Purge attachments: Clear files from notes (text remains).
  • Full purge: Wipe all error data (project structure stays).
  • Delete project: Remove entirely; double-confirm.

Use for cleanup, but export data if needed for audits (see Data Retention).

Apps

Apps group related projects together in the dashboard. This keeps things organized and makes navigation faster.

The typical setup is one app for your product that contains both backend and frontend projects. For example, group your Rails project and JavaScript project under a single “My Blog” app.

App cards appear at the top of the projects dashboard. Each card shows the app name, project count, and combined recent error activity.

Managing Apps

  • Create: Click New App on the projects dashboard. Give it a name and select the projects to include.
  • Edit: Open the app or use the three-dot menu on the card. Change the name or projects.
  • Pin: Use the three-dot menu to pin important apps to the top.
  • Delete: Open the app and click Delete app. Confirm the action.

Key Points

  • A project can belong to only one app.
  • App names must be unique.
  • Deleting an app does not delete projects or errors. Projects simply become standalone again.
  • Organize however you want. No strict rules.

All Errors

The All Errors view provides a global, cross-project overview of all error groups in your Telebugs instance. It lists every grouped error (issue) that you have access to, sorted by the most recently seen.

This is one of the main entry points to Telebugs and is especially useful when managing multiple projects or when you want to see the overall health of your entire system at a glance.

Note: Only errors from projects you are a member of are shown.

Key Features

Filtering

You can narrow down the list using the filter controls at the top of the page (all times are in UTC):

  • Project: Select a specific project or leave as “All” to see errors across all your projects.
  • From / To: Date-time range picker to show only errors whose first or last occurrence falls within the specified window. Defaults to the full range of available data.
  • Reset link: Quickly clear all filters.

Status Tabs

Segmented control to switch between:

  • unresolved – Active errors that have not been resolved (default view).
  • resolved – Errors that have been marked as resolved.
  • all – Both unresolved and resolved errors.

Sorting and Pagination

  • Errors are sorted by last seen time (most recent first).
  • Infinite-style cursor-based pagination with Previous / Next arrows.
  • Loads 50 errors per page.

Error List

The list displays error groups in either a responsive table (desktop) or compact cards (mobile).

Each row/card shows:

  • Project name – Link to the project’s overview.
  • Error icon – A generated bug illustration or the first screenshot/image from the error reports.
    • Badges overlay the icon if the error has an owner, is muted/snoozed, or is resolved.
    • Hovering the icon reveals a popover with details about ownership, mute status, and resolution.
  • Error type and culprit – e.g., TypeError in app/controllers/users_controller.rb.
  • Error message – Truncated preview, clickable to open the full error group detail.
  • Reports count – Number of individual error reports in the group, with a link to view all reports.
  • Seen times –
    • “Last seen” (e.g., “5 minutes ago”) – primary sort key.
    • “First seen” (e.g., “3 days old”).
    • Hovering reveals exact UTC timestamps in a popover.

This dashboard is ideal for triaging new or recurring issues across your entire deployment, spotting widespread problems, or monitoring overall error volume.

All Reports

The All Reports view provides a global, cross-project list of every individual error report received by your Telebugs instance. Unlike the All Errors view (which shows grouped issues), this page displays raw, ungrouped reports in chronological order.

This view is particularly useful for:

  • Investigating very recent errors in real time.
  • Auditing exact occurrences without grouping logic interference.
  • Debugging timing-specific issues or spotting patterns in rapid bursts of reports.

Note: Only reports from projects you are a member of are shown.

Key Features

Filtering

Filter controls at the top of the page (all times are in UTC):

  • Project: Select a specific project or leave as “All” to see reports across all your projects.
  • From / To: Date-time range picker to restrict reports to those that occurred within the specified window. Defaults to the full range of available data.
  • Reset link: Quickly clear all filters.

Sorting and Pagination

  • Reports are sorted by occurred at time (most recent first).
  • Cursor-based pagination with Previous / Next arrows.
  • Loads 50 reports per page.

Report List

The list displays individual reports in either a responsive table (desktop) or compact cards (mobile).

Each row/card shows:

  • Project name – Link to the project’s overview.
  • Report summary – Clickable link showing the report subject (bold) followed by a truncated error message. Clicking opens the full individual report detail.
  • Status – Icons indicating the current state of the associated error group:
    • Owner (user icon or profile picture)
    • Muted or snoozed (bell icons)
    • Resolved (check icon)
    • Hovering the icons reveals a popover with detailed ownership, mute/snooze, and resolution information.
  • Occurred at – Relative time (e.g., “5 minutes ago”).
    • Hovering reveals the exact UTC timestamp in a popover.

This dashboard complements the All Errors view by letting you drill into the raw stream of incoming reports, making it ideal for monitoring live traffic or troubleshooting issues that may not yet be grouped effectively.

Releases

Releases in Telebugs let you tag versions of your app, primarily to attach source maps. This enables unminifying stack traces in error reports and makes debugging easier by mapping minified code back to original sources.

Currently, releases focus solely on source map support. There are no additional features yet.

This chapter covers the essentials. You will learn how to view releases, create them, and manage details such as artifacts and deletion.

Releases Overview

In the project dashboard (see Individual Project View), look for the Releases (N) link in the top-right corner. The number shows how many releases exist. Clicking it takes you to the full list.

Releases are directly tied to source maps. If you minify your code, accurate releases are essential for readable stack traces in errors.

Pro tip: Create releases as part of your deploy pipeline to ensure source maps align perfectly with each version.

Viewing Releases

The releases page shows a chronological list of all releases. Each entry includes:

  • Version: Your custom tag (for example, v1.2.3).
  • Timestamp: When the release was created.
  • ID: A unique internal identifier.
  • Artifacts: The count or list of attached files, typically source maps.

Quick tip: Verify this page after a deploy to confirm that your source maps uploaded successfully.

Creating Releases

You can create releases manually in the UI, via the SDK or API for automation, or by using the Sentry CLI. Compatible commands work in a similar way.

In the UI

  1. On the releases list page, click New Release.
  2. Enter the version tag.
  3. Upload source maps or other artifacts if needed.
  4. Save. The release is now active for error mapping.

Via SDK (JavaScript example)

Telebugs.setRelease("v1.2.3");
// Upload source maps separately if required

Via CLI

Set up environment variables as described in the source map upload section, then run:

sentry-cli releases new <version>

The main value comes from attaching source maps.

Quick tip: Automate release creation and source map uploads in your CI/CD pipeline.

Release Details

Click any release in the list to open its detail page. Here you will see version-specific information and attached artifacts, such as source maps.

Available actions include:

  • View artifact: Open and inspect an attached file. This is useful for verification.
  • Delete artifact: Remove a specific file, for example one uploaded incorrectly. This does not delete the release itself. It only removes the mapping.
  • Delete release: Permanently remove the entire release. Use this with caution. It unlinks all artifacts and can break unminification for errors from that version.

Pro tip: Create releases as part of your deploy pipeline to ensure source maps align perfectly with each version (see Source Maps).

Source Maps

Source maps allow Telebugs to resolve minified JavaScript and TypeScript stack traces back to the original source code. This makes errors from production builds readable, showing the real files, line numbers, and context instead of the bundled/minified versions.

This chapter covers generating source maps, uploading them to Telebugs, and associating them with releases.

Understanding Source Maps

Source maps are files created by bundlers (Webpack, Vite, Rollup, etc.) that map minified or transpiled code back to the original source files.

Without source maps, stack traces point to the minified bundle, making debugging difficult. When properly uploaded and linked to a release in Telebugs, errors automatically show the original code.

To generate them, enable source map output in your bundler configuration (e.g., devtool: 'source-map' in Webpack or sourcemap: true in Vite).

Integrating Source Maps with Releases

Source maps in Telebugs must be attached to a specific release so they apply only to errors from that version.

Access releases from the project dashboard via the Releases (N) link in the top-right (see Individual Project View).

Always create the release first (see Releases), then upload source maps to it.

Uploading Source Maps

You can upload source maps manually in the UI or automatically with the Sentry CLI (fully compatible with Telebugs).

Manual Upload

  1. Open the desired release in the releases list.
  2. Click Attach artifacts (or drag and drop files).
  3. Select your .map files and upload. Multiple files are supported.

  1. Get your personal API key from Account Settings. It starts with tlbgs_.

  2. Set these environment variables:

    export SENTRY_URL=https://your-telebugs-instance.com
export SENTRY_AUTH_TOKEN=tlbgs_your-api-key-here
export SENTRY_PROJECT=your-project-id
export SENTRY_ORG=unused # Required for compatibility, value doesn't matter

  3. Upload source maps:

    sentry-cli sourcemaps upload --release=v1.2.3 ./path/to/maps

  4. If your build doesn’t already reference the source maps, inject the references first:

    sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload --release=v1.2.3 ./dist

After upload, new error reports from that version will automatically use the maps for unminification.

Quick tip: Test by triggering an error in production and checking if the stack trace shows original source files.

Managing Source Maps

Uploaded source maps appear as artifacts on the release details page (see Release Details).

From there you can:

  • View or download individual artifacts for verification.
  • Delete specific artifacts if uploaded incorrectly.
  • Delete the entire release to remove all associated maps (caution: this breaks unminification for past errors from that version).

Pro tip: Use meaningful version tags and clean up old releases when they are no longer needed for active debugging.

Error Reports

Telebugs collects rich error reports using compatible Sentry SDKs. Each report contains stack traces, request data, breadcrumbs, tags, and more to help you diagnose problems quickly.

Similar errors are automatically grouped into issues to reduce noise.

Teams can add notes (with attachments) to discuss and track resolution (see Notes and Collaboration).

See the following sections for details.

Error Report Structure

An individual error report page in Telebugs is divided into sections that provide layered context about the error.

Report Details

High-level overview:

  • Error message: The main description of what went wrong.
  • When: Relative time (e.g., “5 minutes ago”).
  • Occurred at: Exact timestamp in the project’s timezone.
  • Handled: Whether the error was caught and reported manually or unhandled.
  • Severity: Level such as error, warning, or info.
  • Server name: Host where the error occurred.
  • Environment: Production, staging, etc.

Backtrace

The stack trace showing where the error originated.

Each frame lists:

  • Filename
  • Function/method name
  • Line (and column) number

Code context is shown around the error line (highlighted). Frames can be expanded for more lines.

If source maps are attached to the release, minified traces resolve to original source files.

Quick tip: Focus on “in-app” frames (your code) and ignore library frames when investigating.

HTTP Request

For web-related errors, details of the triggering request:

  • Method and full URL
  • Headers
  • Environment variables (e.g., remote IP)
  • Body data (form fields, JSON, etc.)

Useful for reproducing API or page errors.

Tags

Key-value pairs for extra context (e.g., browser: Chrome 128, feature: checkout).

Tags are searchable and great for filtering in the dashboard.

Add them via the SDK: Telebugs.setTag('key', 'value').

A timeline of events leading up to the error (console logs, navigation, HTTP calls, etc.).

Each breadcrumb shows timestamp, category, message, and data. Expand for full details.

Enable automatic breadcrumbs in your SDK for richer trails.

Contexts

Environmental details:

  • OS name and version
  • Runtime (e.g., Node.js, Python)
  • Device or browser info

Helps identify platform-specific issues.

Dependencies

List of loaded packages/modules with versions (e.g., express: 4.18.2).

Check here for known vulnerable or incompatible versions.

SDK

Shows which Sentry SDK sent the report and its version.

Affected User

User information (if set via SDK):

  • ID, username, email
  • IP address and approximate geo location

Set with Telebugs.setUser({ id: '123', email: '[email protected]' }).

Additional Data

Custom key-value data sent with the report.

Use for anything not covered elsewhere.

Viewing Raw Data (View as)

On any individual error report page, you can access alternative representations of the report data using the View as dropdown.

Available formats:

  • Structured (default)

    The standard Telebugs interface with organized sections (Backtrace, Request, Tags, etc.).

  • JSON

    The complete raw event payload as pretty-printed JSON. Useful for copying data, debugging SDK integration, or programmatic processing.

  • XML

    The event payload rendered in XML format (for compatibility with certain tools or legacy systems).

  • Markdown

    A clean, human-readable Markdown summary of the report, including the error message, formatted stack trace (in code blocks), key contexts, tags, and other details. Ideal for pasting into tickets, pull requests, or chat.

Selecting a format instantly opens it in the same tab at a new URL, for example:

  • https://your-instance.example.com/errors/2003/reports/982768.json
  • https://your-instance.example.com/errors/2003/reports/982768.xml
  • https://your-instance.example.com/errors/2003/reports/982768.markdown

These URLs can be shared directly — anyone with access to the project will see the report in the chosen format.

Tip: Bookmark or share the direct .json, .xml, or .markdown URL when you need to reference the raw or formatted version outside of Telebugs.

Grouping and Fingerprinting

Telebugs automatically groups similar error reports into a single issue to reduce noise and help you focus on unique problems.

Grouping uses a fingerprint hash derived from the error data.

Default Grouping Rules

By default, Telebugs prioritizes:

  1. Stack trace (in-app frames: filename + function + line)
  2. Exception type and message
  3. Fallback to error message

This ensures errors from the same code path group together even if minor details (like user input) differ.

Custom Fingerprinting

Override default grouping by setting a fingerprint when reporting the error.

Ruby example (group all payment failures together):

rescue StandardError => e
  Sentry.capture_exception(e, fingerprint: ["payment-failure"])
end

Dynamic example:

action = current_action  # e.g., "checkout"
Sentry.capture_exception(e, fingerprint: ["error", action])

All matching fingerprints land in the same issue.

Manual Merging

If similar errors end up in separate groups:

  1. Open the target (main) error group.
  2. Click Merge.
  3. Paste the URLs of the groups to merge in.
  4. Confirm.

Future reports matching either original group go to the combined one. This action is irreversible.

Grouping Details

On any error report, click the square-stack icon to view:

  • Fingerprint hash
  • Method used (backtrace, exception, message, custom)
  • Specific frames or message that determined grouping
  • Any merged groups

Useful for understanding or debugging unexpected grouping behavior.

Notes and Collaboration

Notes let team members comment on an error group, share context, attach files, and track progress toward resolution.

Viewing Notes

In the error group page, open the Notes section.

Each note shows:

  • Author avatar/name and timestamp
  • Text content (links are auto-detected)
  • Attached files (images as thumbnails, others with icons and download links)

The first attachment on the group becomes the issue’s thumbnail in the dashboard list.

Adding Notes

  1. Scroll to Add a new note at the bottom.
  2. Write your comment.
  3. Attach files via Attach files or drag-and-drop (multiple supported).
  4. Click Add note.

Progress is shown for large uploads.

Managing Notes

  • Notes cannot be edited after posting (delete and repost if needed).
  • Only the author can delete their own note.
  • Admins can purge all attachments project-wide from Project Settings > Danger Zone (irreversible, runs in background).

Pro tip: Use notes for reproduction steps, links to PRs or tickets, screenshots, log files, or “fixed in deploy X” updates.

Owning Errors

Owning an error (also called “claiming” or “assigning ownership”) lets a team member publicly indicate they are responsible for investigating or fixing a specific error group. It is a lightweight triage tool that helps coordinate work across the team.

How Ownership Works

  • Ownership is assigned to a single user per error group.
  • Any team member with access to the project can claim an unowned error.
  • Only the current owner can unclaim (release) it.
  • When ownership changes, Telebugs automatically adds a system note to the error group:
    • “Ownership taken by [User Name].”
    • “Ownership released by [User Name].”
  • The owner’s name (or profile picture) appears as a badge overlay on the error icon in:
    • All Errors dashboard
    • All Reports view
    • Individual project dashboards
    • The individual error group detail page
  • Hovering the owner badge shows a popover with the owner’s name (and link to their profile if applicable).

Ownership does not currently affect:

  • Notifications (they are still sent according to project/notification rules)
  • Permissions (any member can still view, comment, resolve, mute, etc.)

It is purely a visual and organizational signal.

How to Own or Unclaim an Error

Ownership controls are available on the individual error group detail page (the page you reach by clicking an error in All Errors, a project dashboard, etc.).

On desktop / wider screens

The Own it or Unclaim button appears in the header actions area (usually near Resolve and Mute buttons).

On mobile / narrow screens

The buttons are shown prominently below the error header:

  • If unowned: a button labeled Own it with a hand-raised icon.
  • If you are the owner: a button labeled Unclaim with an X icon.

Clicking Own it immediately claims the error for you. Clicking Unclaim immediately releases ownership.

No confirmation dialog is required — the action is fast and reversible.

Best Practices

  • Claim an error when you start actively working on it.
  • Unclaim it if you hand it off to someone else or stop working on it.
  • Use ownership together with notes to communicate status (“I’m debugging this now”, “Waiting on backend team”, etc.).

This simple ownership system helps avoid duplicated effort and makes it easy to see at a glance who is handling each issue.

Muting and Snoozing

Muting (also called “snoozing” for temporary periods) allows you to silence notifications for a specific error group. This is useful when:

  • An error is known and low-priority.
  • You’re waiting on a third-party fix.
  • The error is noisy but not urgent.

When an error group is muted, no notifications (email, push, or webhook) will be sent for new reports in that group, regardless of your notification rules.

Types of Muting

There are two forms:

  • Temporary Snooze – Silence notifications for a fixed duration. Available durations:

    • 1 hour
    • 4 hours
    • 8 hours
    • 1 day
    • 3 days
    • After the time expires, notifications automatically resume.

  • Permanent Mute (“Forever”) – Silence notifications indefinitely until manually unmuted.

How Muting Works

  • Muting applies to the entire error group.
  • Any team member with access to the project can mute or unmute.
  • When an error is muted or unmuted, Telebugs automatically adds a system note:
    • “Error muted by [User Name].”
    • “Error unmuted by [User Name].”
  • A badge appears on the error icon in all views (All Errors, All Reports, project dashboards, group detail) showing:
    • Bell-snooze icon for temporary snooze
    • Bell-slash icon for permanent mute
  • Hovering the badge reveals a popover with who muted it and (for snoozes) when it will resume.

How to Mute or Unmute an Error

Controls are available on the individual error group detail page.

On desktop / wider screens

The Mute… button appears in the header actions (next to Own it / Resolve). Clicking it opens a dropdown with duration options, including Forever.

On mobile / narrow screens

A prominent Mute… button is shown below the error header. Tapping it opens a bottom sheet menu with the same duration options.

Unmuting / Unsnoozing

If the error is currently muted:

  • The button changes to Unmute (permanent mute) or Unsnooze (temporary).
  • Clicking/tapping it immediately removes the mute and resumes notifications.

Important Notes

  • Muting only affects notifications — new reports are still recorded, grouped, and visible in dashboards.
  • Resolved errors can still be muted (useful for preventing notifications if they regress; see Owning Errors for related triage).
  • If a muted error receives new reports after being resolved, it will automatically become unresolved (as with any error), but notifications will remain suppressed until unmuted.

Use muting responsibly to reduce noise while keeping full visibility into your error stream.

Data Retention

Data retention in Telebugs helps you control how long error reports and artifacts (like source maps) are kept. Automatic policies clean up old data based on time or disk usage, keeping storage manageable and supporting compliance needs.

Cleanup jobs run nightly at 2 AM server time. You can also trigger manual purges immediately.

This chapter covers error and artifact retention policies, purge types, and monitoring disk usage.

Error Retention Policy

Error retention controls how long reports and their details (backtraces, breadcrumbs, tags, notes, etc.) are stored.

Enable automatic cleanup to prevent unlimited growth.

Enabling Error Retention

Go to Settings > Data Retention.

Toggle Enable automatic error cleanup and save. The UI shows when the next cleanup will run.

Time-Based Cleanup

Delete reports older than a set number of days.

Choose:

  • Full purge: Removes everything (including notes and attachments). Historical details are lost.
  • Partial purge: Keeps basic metadata for graphs and counts, but deletes heavy details like stack traces and contexts.

Example: A 90-day partial purge keeps stats for reports older than 90 days but removes the full payloads.

Disk-Based Cleanup

Triggers when the database file grows too large (full purge only, oldest reports first).

Set limit as:

  • Absolute size (e.g., 10 GB)
  • Percentage of total disk (e.g., 35%)

Runs alongside time-based rules if both are enabled.

Artifact Retention Policy

Artifacts (mainly source maps attached to releases) have separate retention rules.

Enabling Artifact Retention

In Settings > Data Retention, toggle Enable automatic artifact cleanup.

Time-Based Artifact Cleanup

Deletes artifacts from releases older than the set period, but only if no recent error reports reference them.

Disk-Based Artifact Cleanup

Triggers when total artifact storage exceeds the limit (absolute GB or percentage).

Deletes from oldest inactive releases first.

Purge on New Release

Optional: When uploading a new release, automatically delete artifacts from excess old releases (keep only the newest N, e.g., 20).

Oldest inactive releases are removed first.

Monitoring and Maintenance

The Data Retention section shows live stats:

  • Total and free disk space
  • Database size and percentage used
  • Artifact size and count
  • Total report count

Stats refresh automatically after cleanups.

Telebugs runs a nightly VACUUM job to reclaim unused space when there’s enough free disk (database size + 10% buffer).

Important: All automatic and manual purges are irreversible. Export critical data if needed before cleanup.

For quick cleanup, use the Danger Zone in project settings to purge all error data or note attachments manually.

Service Messages

Service Messages guide admins through important maintenance tasks (like database optimization or post-update cleanup) directly in the dashboard. No command-line access is required.

Pending messages show as a red badge on your profile picture in the top-right corner (visible only to admins). Once all messages are addressed, the badge disappears for everyone.

Accessing Service Messages

  1. Click your profile picture in the top-right.
  2. Look for the Service Messages entry in the dropdown (highlighted with the red badge if pending).

The index page lists all messages in a simple table with titles and statuses. Click a title for details.

Message Statuses

Each message has one of these statuses:

  • Needs action (gray): Requires admin input.
  • In progress (orange): Background job running.
  • Completed (green): Finished successfully.
  • Failed (red): Something went wrong.

Viewing a Message

The detail page shows:

  • Title and Description (what the task does and why it matters)
  • Status with color tag
  • First read by (admin and timestamp)
  • Started by and Started at
  • Completed at (if finished)
  • Error message (if failed)

If the status is Needs action or Failed, a Run Action button appears at the bottom.

Clicking Run Action automatically marks the message as read and clears your badge (the badge is shared across all admins).

Running an Action

Only admins can start actions, and only when the status allows it.

After clicking Run Action:

  • Status changes to In progress.
  • The task runs asynchronously in the background.
  • A notice warns it may take time (e.g., up to an hour for large datasets).

Refresh the page to see updates. When finished, the status becomes Completed or Failed, with timestamps and any error details.

Quick tip: Address service messages promptly after upgrades to keep your instance running smoothly.

Appendix

The following sections contain reference material you may find useful in your Telebugs journey.

Software License Agreement

Copyright © 2025, Kyrylo Silin PE.

Permission is hereby granted to any person purchasing or receiving a copy of Telebugs, its source code and associated documentation files (the “Software”), to install and use a single instance and modify a single version of the Software as provided. This does not include the rights to publish, distribute, sublicense, and/or sell copies of the Software, source code or products derived from it.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The user of the software represents and warrants that they will at all times comply with applicable law in their download and use of the Software.

telebugs command reference

Install and manage your Telebugs instance.

To run the telebugs command, connect to your server using SSH or your cloud provider’s web-based terminal.

Usage

  • telebugs — Displays the main menu with available commands.

Manage passwords

  • password — Manage passwords.

Manage automatic updates

  • auto-update — Manage automatic updates.

Manage application data

  • data — Manage application data.

Additional commands

  • help — Displays help information for the telebugs command.
  • setup — Runs the initial setup process for Telebugs.
  • start — Start Telebugs.
  • stop — Stop Telebugs.
  • status — Displays the current status of the Telebugs instance.
  • update — Update Telebugs to the latest version.

Flags

  • -h, --help — Displays help information for the telebugs command.

Use telebugs [command] --help to see detailed help for a specific command.

Supported platforms

Telebugs supports error tracking for a wide range of programming languages, frameworks, and platforms through compatibility with Sentry SDKs. By configuring the appropriate Sentry SDK with your Telebugs DSN, you can send error reports from your application to your Telebugs instance.

Below is an exhaustive list of supported platforms, organized by category, with links to setup instructions from Sentry’s official documentation.

Mobile platforms

Game engines

Other languages and frameworks

This list reflects all platforms we currently support. For the most up-to-date information or additional setup details, refer to:

https://docs.sentry.io/platforms/

Installing on DigitalOcean

Using Digital Ocean to host Telebugs is a great choice. It’s affordable and easy to set up.

After signing up for a Digital Ocean account, follow these steps. It should take about 5 minutes.

  1. In your Digital Ocean account, go to Create > Droplets and pick a plan for your server.

    Creating a new Digital Ocean droplet

    You need at least 2GB RAM and 1 CPU.

    Regular CPU with a regular SSD

  2. Set a password to connect to your server.

    Choosing authentication method

  3. Leave the other settings as they are and click Create Droplet. Wait a few minutes for it to be ready, then click it.

    List of droplets for the Telebugs project

  4. Copy the ipv4 address. You’ll use it to link your domain to this server.

    IP v4 address copying

    Go to your domain provider’s site (like GoDaddy, namecheap, or Cloudflare). Log in, find the domain management section, and add an A record with the IP you copied. It should look like this:

    A record configuration

    Ensure that proxying is disabled.

  5. Back in Digital Ocean, find your Droplet and open the Console to access your server.

    Droplet console link

  6. Check the confirmation email we sent you for the install command. Paste it into the command line.

    Telebugs installation script

  7. When prompted, type your domain name (the same one you used for the A record). The system will finish the setup. After a few minutes, you’ll see this:

    Telebugs installation complete

  8. All set! Open the URL in your browser and create your Telebugs account.

Installing on Hetzner

Hosting Writebook on Hetzner is a smart pick. It’s budget-friendly and simple to set up if you’re comfortable with some basic tech steps.

After signing up for a Hetzner account, follow these steps. It should take about 5 minutes.

  1. In your Hetzner account, click + Create Server and pick a plan.

    Creating a new Hetzner server

    You need at least 2GB RAM and 1 CPU.

    CPU type selection

  2. Keep the default settings and click Create and Buy now. Your server will be ready in a few minutes.

  3. Once it’s ready, copy the Public IP address. This links your domain to the server.

    Public IP of a server

  4. Go to your domain provider’s site (like GoDaddy, namecheap, or Cloudflare). Log in, find the domain management section, and add an A record with the IP you copied. It should look like this:

    A record configuration

    Ensure that proxying is disabled.

  5. Back in Hetzner, open the Console to connect to your server.

    The Console option

  6. Check the confirmation email we sent you for the install command. Paste it into the command line.

    Telebugs installation script

  7. When prompted, type your domain name (the same one you used for the A record). The system will finish the setup. After a few minutes, you’ll see this:

    Telebugs installation complete

  8. All set! Open the URL in your browser and create your Telebugs account.