4.1 System requirements ¶

Telebugs can run on nearly any hardware, including 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 general, if Docker can run on it, Telebugs can too.

Supported platforms ¶

Telebugs is compatible with over 100 programming languages and frameworks through Sentry SDKs, including popular choices like JavaScript (Node.js, React, Angular), Python (Django, Flask), Ruby (Rails), Java (Spring), PHP (Laravel), .NET (ASP.NET Core), and Go. For a complete list of supported platforms, see Supported platforms.

Error throughput ¶

When deciding how powerful your machine needs to be, consider the following table:

Throughput depends on your machine’s CPU and RAM. The table above provides rough estimates of how many errors Telebugs can handle per second and per day, based on the number of CPU cores. These figures are approximate and may vary depending on your setup, application complexity, and error volume.

Throughput is shared across all projects in a Telebugs installation. If you run multiple projects, each one gets a fraction of the total. For example, with two projects, each gets half; with four, each gets a quarter, and so on.

Recommended minimum specs ¶

• RAM: 1 GB
• Disk space: 40 GB
• CPU: 1

Recommended specs for small to medium projects ¶

• RAM: 4 GB
• Disk space: 80 GB
• CPU: 3

Operating system compatibility ¶

• Telebugs is tested on Linux (Ubuntu, Debian, Alpine, Rocky), and should work on any OS that supports Docker.
• macOS

4.2 Installation steps ¶

The whole process takes less than 10 minutes. Here’s how to get started:

1. Choose a server: Select a machine to host Telebugs (cloud or local). I recommend DigitalOcean (setup guide) or Hetzner (setup guide).
2. Point your domain: Update your DNS to link your domain to your server’s IP address. Ensure it’s a direct DNS record (no proxying — Telebugs handles TLS).
3. Connect to your server: Use SSH or your provider’s console to access the server.
4. Run the installation command: Copy the command from your email and run it in your server’s terminal. The installation process may take up to 5 minutes.

   Your personalized installation command will be similar to the following:

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

IMPORTANT: Keep your install command private — don’t share it with anyone or post it online. It’s uniquely linked to your account, and the license is tied to you. Your personal purchase token is included in the email you received after downloading Telebugs.

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.

That’s it! You’re now ready to set up the first user on your new Telebugs installation. Just visit https://YOUR-DOMAIN in your browser to get started. After that, you can begin inviting the rest of your team.

Telebugs will automatically update itself to the latest version every night at 1 AM (based on your server’s local time). You can disable this, or perform other admin tasks — like backing up data, resetting passwords, and more — using the telebugs command. Simply connect to your server and run telebugs to see all available options.

Enjoy error tracking with Telebugs!

P.S. Planning to run multiple Telebugs installations? You’ll need a separate license for each domain.

4.3 Custom TLS certificates ¶

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

• TLS termination with Nginx
• TLS termination with HAProxy

4.4 Kubernetes installation ¶

Telebugs can be installed on a Kubernetes cluster using the official Helm chart. This allows you to deploy Telebugs in a containerized environment, making it easy to manage and scale.

This is not a beginner-friendly option, so it’s recommended only if you already have experience with Kubernetes and Helm. The recommended way to install Telebugs is by following the Installation instructions above.

8.1 Team roles ¶

Telebugs keeps permissions simple yet powerful with a role-based system. This ensures the right people see the right stuff, protecting sensitive data while boosting productivity. There are two straightforward roles:

• Admin: The all-access pass holders. They can tweak settings, manage projects, invite/remove users, and dive into every error report. Perfect for leads or trusted overseers.
• Member: The focused contributors. They view and resolve errors in assigned projects but can’t change configs or handle team stuff. Ideal for devs or testers who just need to fix bugs.

Pro tip: Start small — make new joins members, then promote as trust builds. This keeps your instance tidy and secure.

8.2 Inviting team members ¶

Ready to expand your crew? Inviting is easy and gets everyone on board fast.

1. Head to Team Management > Members.
2. Spot the invite section and click Copy link or Share link to grab the magic URL.
3. Send it via email, Slack, or carrier pigeon — whatever works for your team.

The link’s universal (not user-specific), so share wisely with trusted folks only. If it leaks? No sweat — hit Regenerate to zap the old one and create a fresh link instantly.

Quick tip: Personalize your invite message with a quick note like "Join our Telebugs team to crush those bugs together!" It sets a collaborative tone.

8.3 Joining Telebugs as a team member ¶

Got an invite link? You’re moments away from jumping in! Click it, and you’ll see a friendly prompt:

1. If new, create an account with your details (name, email, password).
2. If existing, just log in.

Post-join, you’ll land in a holding pattern — no projects yet! Ping your admin to get assigned (they’ll toggle you in via access controls). Once in, you’ll see errors and can start resolving.

Heads-up: If you’re granted admin powers later, you’ll unlock full settings access. Until then, enjoy the focused view!

8.4 Promoting or demoting team members ¶

As your team evolves, so do roles. Need to elevate a star performer or dial back access? It’s a simple toggle.

1. Go to Team Management > Members.
2. Find the user and check (promote to admin) or uncheck (demote to member) the box next to their name.
3. Changes save automatically — no extra clicks needed.

Pro tip: Communicate changes upfront to avoid surprises. For example, "Hey team, promoting Alex to admin for better project oversight!"

8.5 Removing team members ¶

Sometimes teams shift — offboarding is quick and clean.

1. Navigate to Team Management > Members.
2. Click the stop sign icon next to the user’s name.
3. Confirm, and they’re out — no more access to Telebugs.

Gentle reminder: This revokes all access, so archive any needed notes first. It’s reversible by re-inviting, but better to handle gracefully.

8.6 Recovering a team member’s access ¶

Forgotten password got someone locked out? As an admin, you’re the hero.

1. In Team Management > Members, click the user’s name to open their profile.
2. Scroll to Account recovery and copy/share the magic link.
3. Send it their way

Quick win: This bypasses email resets, making recovery lightning-fast. Use it for quick fixes during crunch time!

8.7 Project access ¶

Not all projects are for everyone — assign access to keep things organized.

1. Visit Team Management > Project access.
2. For each user, check boxes next to projects they should join (unchecked means no-go).
3. Saves instantly—users get access right away.

Pro tip: Use this for segmented teams, like devs on backend projects only. Review periodically to keep access current.

8.8 Team notifications ¶

Keep the team alerted without overwhelming inboxes — admins can control the flow.

1. Go to Team Management > Notifications.
2. Check boxes for projects where users should get email pings (unchecked skips them).
3. Focuses on email; other channels (like Slack) are separate.

Fun twist: Tailor this for on-call rotations — enable for critical projects only. Combine with personal settings for ultimate customization.

Next steps ¶

Team assembled? Great! Now check out Project settings to customize per project, or explore Notifications settings for advanced alerts. Remember, a well-managed team turns bug hunting into a group adventure — happy collaborating!

9.1 Profile picture ¶

Your profile picture is your digital handshake — it’s what your team sees next to your name across Telebugs. Make it pop with a photo that screams "you" (or at least makes you recognizable in a team meeting!).

Uploading a profile picture ¶

Want to swap out that generic avatar for something with personality? Here’s how:

1. Click the default profile picture in the Account Settings page.
2. Pick an image file from your device — something clear, ideally square.
3. Hit the Update profile picture button to lock it in.

Pro tip: Choose a high-res image for crisp display. It’ll show up everywhere, from comments to team lists, so make it count!

Deleting a profile picture ¶

Decided to go incognito? No problem. To ditch your profile picture:

1. Click your current picture in Account Settings.
2. Select the option to remove it and confirm with the Update profile picture button.

This reverts you to the default avatar — clean and simple. Perfect if you’re feeling minimalist or just want a reset.

9.2 Security settings ¶

The Security tab is your fortress for keeping your account safe. From API keys to email updates, this is where you tighten the bolts on your Telebugs access. Navigate to Account Settings and click the Security tab to get started.

• Regenerating your API key
• Changing your email address
• Changing your password

Next: Changing your email address, Up: Security settings   [Contents]

9.2.1 Regenerating your API key ¶

Your API key is the golden ticket for interacting with Telebugs programmatically. If it’s compromised (or you just want a fresh one), regenerating is quick and keeps things secure. Here’s the playbook:

1. Head to the API key section in Security settings.
2. Click the Regenerate button — old key’s toast!
3. Use the Copy token button to grab the new key and update your app’s config ASAP.

Quick tip: Store your API key in a secure vault or environment variable, not in your codebase. After regenerating, test your integration to ensure reports are flowing. No reports? Check that new key!

---

Next: Changing your password, Previous: Regenerating your API key, Up: Security settings   [Contents]

9.2.2 Changing your email address ¶

Need to switch the email tied to your account? Maybe you’re moving to a new domain or just want a fresh inbox. It’s straightforward:

1. Scroll to the Email address section in Security settings.
2. Enter your new email and confirm your current password for security.
3. Click Change email to seal the deal.

Heads-up: You’ll likely need to verify the new email via a confirmation link. Keep an eye on your inbox (and spam folder) to complete the switch. This ensures notifications and resets go to the right place.

---

Previous: Changing your email address, Up: Security settings   [Contents]

9.2.3 Changing your password ¶

Keep your account locked tight with a strong password. Updating it regularly (or after a security scare) is a smart move. Here’s how:

1. Navigate to the Password section in Security settings.
2. Enter your current password, then type and confirm your new one.
3. Click Change password to make it official.

Pro tip: Use a unique, complex password (mix letters, numbers, symbols). A password manager can help. Test logging in after the change to confirm it worked. Locked out? Ask your admin for a sign-in link.

---

10.1 Email ¶

To receive error notifications via email, you must first configure global email settings.

Individual projects can disable email notifications in their project settings, and each user can opt out in their profile settings. Once global email notifications are configured, project-level rules determine when you will be notified.

Email notifications are sent to the address associated with your Telebugs account.

If you need notifications sent to a different address, update your email in your profile.

You can choose to receive notifications based on the following conditions:

• Notify when a new error occurs for the first time.
• Notify when an error reoccurs after being resolved.
• Notify when error frequency exceeds a threshold (for example, more than 10 reports in 5 minutes).

Follow these steps to configure email notifications:

1. Open the menu in the top-right corner, click your profile name, and select Notification Configuration.
   
2. In the sidebar on the left, ensure that Email is selected.
   
3. Complete the Email notifications configuration form, then click Save Configuration to apply your settings.
4. Once the form is saved, a green checkmark appears next to Email in the sidebar, indicating that email notifications are configured.
   
5. Click the Send test email button to verify that notifications work.
   
6. A confirmation toast appears, showing that the test email has been sent.
   
7. Check your inbox; you should receive a test email at the address associated with your Telebugs account.
   
8. To disable all email notifications, toggle off Enable email notifications. The sidebar icon will change to a bell with a slash, indicating that email notifications are disabled.
   
   
9. When a real error occurs, you will receive an email according to the rules you configured in project settings. The email includes details such as the error message and a link to the error report in Telebugs.
   

Email notifications 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.

10.2 Push notifications ¶

Once you save these settings, Telebugs will send notification emails according to the project-level rules you configured earlier. To receive error notifications via push notifications, you must first configure global push notification settings. Individual projects can disable push notifications in their project settings, and each user can opt out in their profile settings. Once global push notifications are configured, project-level rules determine when you will be notified. Push notifications are sent to devices where you have allowed notifications for Telebugs. This can include desktop browsers (like Chrome or Firefox) and mobile devices with the Telebugs Progressive Web App (PWA) installed. To enable notifications, you’ll need to grant permission on each device you use — typically through a browser prompt or your device’s notification settings.

Note: For mobile devices, installing the Telebugs PWA can enhance the notification experience. For a quick guide on installing the PWA, See Installing Telebugs as a Progressive Web App (PWA).

You can choose to receive notifications based on the following conditions:

• Notify when a new error occurs for the first time.
• Notify when an error reoccurs after being resolved.
• Notify when error frequency exceeds a threshold (for example, more than 10 reports in 5 minutes).

Note: Push notifications require your permission to be sent. You may be prompted to allow notifications when you configure them or when you visit your Telebugs instance.

Follow these steps to configure push notifications:

1. Open the menu in the top-right corner, click your profile name, and select Notification Configuration.
   
2. In the sidebar on the left, select Push.
   
3. Complete the Push notifications configuration form, then click Save Configuration to apply your settings.
4. Once the form is saved, a green checkmark appears next to Push in the sidebar, indicating that push notifications are configured.
   
5. Click the Send test push notification button to verify that notifications work.
   
6. If prompted, allow push notifications in your browser or device.
   
7. A confirmation toast appears, showing that the test push notification has been sent.
8. Check your device; you should receive a test push notification.
   
9. To disable all push notifications, toggle off Enable push notifications. The sidebar icon will change to a bell with a slash, indicating that push notifications are disabled.
   
   
10. When a real error occurs, you will receive a push notification according to the rules you configured in project settings. The notification includes details such as the error message, a link to the error report in Telebugs, and the project name.
    

Push notifications configuration form ¶

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

• VAPID subject: Enter the VAPID subject, which is used to identify the application server sending push notifications. This is typically a URL or an email address associated with your Telebugs instance (for example, https://telebugs.example.com or mailto:[email protected]). This field is required.

Once you save these settings, Telebugs will send push notifications according to the project-level rules you configured earlier.

• Installing Telebugs as a Progressive Web App (PWA)

Up: Push notifications   [Contents]

10.2.1 Installing Telebugs as a Progressive Web App (PWA) ¶

Telebugs can be installed as a Progressive Web App (PWA) on your mobile device. A PWA is a web application that provides a native app-like experience, including the ability to receive push notifications more reliably. Installing Telebugs as a PWA is optional but recommended for users who want to receive push notifications on their mobile devices.

Benefits of installing Telebugs as a PWA ¶

• Improved performance and faster load times.
• Ability to receive push notifications even when the browser is not actively open.
• A more seamless, app-like experience on your mobile device.

Installation Instructions ¶

For Android devices:

You can install the Telebugs PWA on Android using one of the following methods:

Method 1: Using the browser menu ¶

1. Open the Telebugs web app in the Chrome browser.
2. Tap the menu button (three dots) in the top-right corner of the browser.
3. Select "Add to Home screen" from the menu.
4. Confirm the installation by tapping "Add" or "Install."

Method 2: Using the automatic install prompt ¶

When you visit the Telebugs web app in Chrome on Android, you may see an "Install" button at the bottom of the screen. This is an automatic prompt from the browser to install the PWA.

1. Open the Telebugs web app in the Chrome browser.
2. If the "Install" button appears at the bottom of the screen, tap it.
3. Confirm the installation by tapping "Install" in the dialog that appears.

For iOS devices:

1. Open the Telebugs web app in the Safari browser.
2. Tap the share button (a square with an arrow pointing upwards) at the bottom of the screen.
3. Scroll down the share menu and select "Add to Home Screen".
4. Confirm the installation by tapping "Add".

Optional: Installing on Desktop (Chrome) ¶

If you prefer to have Telebugs as a standalone application on your desktop, you can install it as a PWA using Chrome. This is not required for receiving push notifications on desktop, as they work directly in the browser once notifications are allowed.

1. Open Telebugs in Chrome on your desktop.
2. Click the plus icon (+) in the address bar or go to the Chrome menu (three dots) and select "Install Telebugs."
3. Confirm the installation by clicking "Install."

Note: The exact steps may vary slightly depending on your device and browser version. If you encounter issues during installation, ensure that your browser is up to date and that you have granted the necessary permissions for notifications.

---

10.3 Webhooks ¶

Webhooks in Telebugs enable real-time notifications to be sent to external services whenever specific events occur, such as a new error being reported, an error reoccurring, or the error frequency exceeding a set threshold. This feature allows integration with tools like Slack, Discord, or any custom endpoint that accepts HTTP POST requests. Once webhooks are configured globally, individual projects can opt to use them or disable them via project settings. After setup, project-level rules dictate when notifications are sent to the configured webhook URLs.

You can configure webhooks to trigger under these conditions:

• Notify when a new error occurs for the first time.
• Notify when an error reoccurs after being resolved.
• Notify when error frequency exceeds a threshold (for example, more than 10 reports in 5 minutes).

Follow these steps to configure webhook notifications:

1. Open the menu in the top-right corner, click your profile name, and select Notification Configuration.
   
2. In the sidebar on the left, select Webhooks.
   
3. Click the Create Configuration button to begin adding a new webhook.
   
4. Complete the Add a new webhook form with details such as the webhook URL, name, template type, and template body, then click Save webhook to apply your settings.
   
5. Once saved, the webhook appears in the Configured webhooks section.
   
6. To verify the webhook, click the Test button next to it in the list. This sends a test payload to the specified URL.
   
7. To edit a webhook, click its name in the Configured webhooks section.
   
8. A popup appears, allowing you to modify the name and template body.
   
9. You can edit webhook URL and template body directly in the popup. Close the popup to save changes.
   
10. When a real error occurs, Telebugs sends a notification to the webhook URL based on the project settings, including details like the error message and a link to the error report.

Add a new webhook form ¶

The Add a new webhook form defines the settings for each webhook. Complete the fields as follows:

• Webhook URL: Enter the URL where notifications will be sent. This must be a publicly accessible endpoint capable of handling POST requests. This field is required.
• Name: Provide an optional name to identify the webhook later, such as a channel name (e.g., "#monitoring") or a description.
• Template: Select the payload template type from the dropdown: Slack, Discord, or Custom. Predefined templates auto-fill the template body, while "Custom" allows manual payload creation. This field is required.
• Template body: Define the JSON payload sent to the webhook URL. For predefined templates, this field pre-populates with a default structure. For custom templates, enter your own JSON using allowed interpolation keys. This field is required.

Webhook template body placeholders ¶

In the template body, use placeholders like {{key}} to insert dynamic values. The following keys are available:

• project_name: The project name (e.g., "Backend", "example.com").
• trigger: The event triggering the notification (e.g., "error", "reoccurrence", "error frequency exceeded").
• subject: A brief error description (e.g., "NoMethodError in ScoresController#create").
• culprit: The code location of the error (e.g., "ScoresController#create").
• location: The error’s location (e.g., file path or module).
• error_type: The error type (e.g., "NoMethodError", "Exception").
• error_message: The detailed error message (e.g., "undefined method ‘+’ for nil").
• project_url: The project’s URL in Telebugs (e.g., "https://tests.telebugs.com/projects/7").
• view_url: The URL to the error report (e.g., "https://tests.telebugs.com/errors/107").

Click the Help button next to the template body field for links to resources on webhooks, Slack, and Discord integration.

• Slack
• Discord
• Custom webhooks

{
  "username": "Telebugs",
  "attachments": [
    {
      "fallback": "{{project_name}}: {{trigger}} - {{error_type}}: {{error_message}}",
      "pretext": "*{{trigger}}* from <{{project_url}}|{{project_name}}>",
      "color": "#D00000",
      "fields": [
        {
          "title": "{{error_type}}{{culprit}}",
          "value": "{{error_message}}",
          "short": false
        },
        {
          "title": "Location",
          "value": "{{location}}",
          "short": false
        }
      ],
      "actions": [
        {
          "type": "button",
          "text": "View",
          "url": "{{view_url}}"
        }
      ]
    }
  ]
}

{
  "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}}"
        }
      ]
    }
  ]
}

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

11.1 Project overview ¶

Your projects live in a clean, glanceable index view — perfect for getting the big picture. Head to the main dashboard (or click "Projects" in the nav) to see them all laid out in a responsive grid. Each project card packs a punch:

• Platform icon: A quick visual cue for the tech stack (e.g., Ruby on Rails, PHP, JavaScript).
• Project name: Click to enter the project’s error dashboard.
• Sparkline chart: A mini-graph showing recent error trends (24h).
• Dropdown menu: Tap the three dots for quick actions like editing settings.

If you’re flying solo with one project, this view keeps it simple. Got a fleet? The grid scales beautifully on desktop or mobile.

Pro tip: Use the "New Project" button at the top-right to spin up more — Telebugs makes it effortless to segment your monitoring.

11.2 Individual project view ¶

Click into a project, and you’re in the command center: a dynamic dashboard tailored for deep dives into your errors. This is where the real action happens — spotting patterns, resolving issues, and keeping your app humming.

Key features at a glance:

• Project picker: Dropdown in the top-left to switch projects or jump to settings. Super handy for multi-project users.
• Releases link: Quick access to your project’s release history.
• Search bar: Hunt for specific errors by message, type, or details. Results update live as you type.
• Date range selector: Filter errors by time (today, last week, etc.) with a pager for navigation.
• Stats overview: At-a-glance metrics like total reports, reoccurred vs. new errors.
• Interactive chart: Visualizes error volume over time — zoom in on spikes for clues.
• Error list: Each unique error is grouped, showing type, message, timestamp, and report count. Click for details.
• Filters: Toggle between all, resolved, or unresolved errors; sort by last seen or count.

If your project is error-free (lucky you!), you’ll see SDK setup instructions instead. Once reports flow in, the dashboard auto-refreshes with real data — no manual reloads needed.

Quick tip: Use the search and filters to triage fast — focus on unresolved high-volume errors first. The chart is your trend-spotter; watch for patterns tied to deploys or traffic surges.

11.3 Project settings ¶

Welcome to the nerve center of your Telebugs project! Project settings are where you fine-tune how Telebugs works for you, from basic details like names and timezones to security tokens, team access, notifications, and even those high-stakes "danger zone" actions. Think of this as your project’s control panel: customize it wisely to keep everything running smoothly.

To get started, go to your project dashboard, click the three dots on the project card, and select Settings:

If you’re inside a project, click the project name in the top-left corner and select Project Settings from the dropdown menu.

In this guide, I’ll walk you through each tab in the project settings, explaining what you can do and why it matters. Whether you’re a project owner or an admin, these settings help you tailor Telebugs to your team’s needs.

11.4 General settings ¶

Start here to set the foundation. The General tab is all about the basics that make your project feel like home. Updating these won’t mess with your data — it’s purely for clarity and convenience.

• Project name: Give your project a memorable name, like "AwesomeApp Backend" instead of a generic one. This helps when you have multiple projects. Just type in the new name and hit "Rename." Pro tip: Keep it descriptive so your team knows at a glance what it’s for.
• Project timezone: Errors don’t respect time zones, but your team does! Set this to match where most of your users or developers are. It affects how dates and times appear in reports (e.g., "today’s errors"). Search or select from the dropdown, then click "Change timezone." If you’re global, consider UTC for neutrality.
• Project platform: This picks the right icon and tailors SDK setup guides to your tech stack (e.g., Ruby, JavaScript). It’s cosmetic but super helpful for quick reference. Choose from the list and save — your installation instructions will update automatically.

These tweaks make your dashboard more intuitive. For example, if you’re debugging late-night issues, the right timezone can save you from mental math headaches!

11.5 Token settings ¶

Security first! Tokens are the keys to your project’s door — they let your app send error reports without exposing everything. If something feels off (like unexpected reports), regenerate and update your code pronto.

• Project token: This is the secret code your SDK uses. View it here, copy it for setup, or regenerate if compromised (old one stops working immediately). Always store it securely in environment variables, not hardcoded.
• Data Source Name (DSN): The full URL for sending errors (includes your token). Share sparingly — it’s like a mailing address with a key attached. Copy it directly into your SDK config.

Quick guide: After regenerating, test your setup by triggering a sample error. No reports? Double-check the new token in your app.

11.6 Access control ¶

Collaboration is key, but so is control. This tab lets you decide who sees what in your project. It’s perfect for teams where not everyone needs full access.

View your team list and toggle checkboxes to grant or revoke project access. Admins can do everything; members can view reports but not change settings.

Step-by-step:

1. Spot a user in the list.
2. Check the box to add them (or uncheck to remove).
3. Changes save automatically — notify them if needed.

For broader team management, jump to Team management to handle roles and invites. This keeps sensitive projects locked down while fostering teamwork.

11.7 Notifications settings ¶

Stay in the loop without the noise. Notifications ensure you’re alerted to issues that matter, via your preferred channels.

• Notification channels: Pick from Email, Push, or Webhook. Enable one (toggle on), configure if needed (e.g., webhook URL), and test. Start with Push — it’s straightforward.
• Rules: Set conditions like "notify on new errors" or "high-severity only." Rules activate once a channel is on. Experiment: Create a rule for critical errors to ping your team instantly.
• Recipients: Choose who gets pinged. Toggle per user — great for on-call rotations.

Pro tip: Combine channels for redundancy (email + push). Test by simulating an error and checking if alerts fire. Fine-tune to avoid alert fatigue!

11.8 Danger zone ¶

Proceed with caution — this is where irreversible actions live. Use these for cleanup or resets, but always back up if possible.

• Project stats: Quick overview of usage (disk space, reports). Refresh for latest — handy before purging to gauge impact.
• Partial purge: Strip details from old reports but keep stats. Ideal for slimming down without losing history insights.
• Purge attachments: Clear out files from notes. Text stays; media goes. Useful if storage is ballooning.
• Full purge: Wipe all error data clean. Project shell remains for fresh starts.
• Delete project: Nuke everything. Confirm twice — once gone, it’s gone forever.

Before clicking, ask: "Do I need this data?" For audits, export first. These tools keep your instance lean, but wield them wisely!

12.1 Releases overview ¶

In your project dashboard (see Individual project view), spot the "Releases (N)" link top-right. It shows the count and jumps you to the list. Releases here are tied to source maps, so if you’re using minification, this is key for actionable stack traces.

Pro tip: Set releases during deploys to ensure source maps match versions accurately.

12.2 Viewing releases ¶

The releases index is a simple chronological list. Each entry shows:

• Version: Your tag (e.g., "v1.2.3").
• Timestamp: Creation time.
• ID: A unique identifier for the release.
• Artifacts: Attached source maps or other files.

Quick tip: Check here post-deploy to verify source maps uploaded correctly.

12.3 Creating releases ¶

Creating a release is easy, either manually, via SDK/API for automation, or using the Sentry CLI. In the UI:

1. From the releases index, click New Release.
2. Add version and upload source maps if needed.
3. Save — it’s ready for error mapping.

Via SDK (example in JS):

Telebugs.setRelease('v1.2.3');
// Then upload source maps separately if required

Via Sentry CLI: Set the environment variables as described in Uploading source maps, then run:

sentry-cli releases new <version>

Focus on including source maps; that’s the core value for now.

Quick tip: Integrate with your build process for automatic release creation and sourcemap uploads.

12.4 Release details ¶

Click a release in the list to view its details. This page shows specifics for that version, including any attached artifacts like source maps.

Key actions:

• View attached artifact: Inspect linked source maps for verification.
• Delete attached artifact: Remove source maps if no longer needed or if they were uploaded incorrectly. This won’t delete the release itself, just the mapping.
• Delete release: Remove the release if obsolete — but use caution, as it unlinks source maps and may affect error unminification.

Pro tip: Before deleting, ensure no active errors rely on that version’s mapping. Always test post-deletion.

13.1 Understanding source maps ¶

Source maps are files generated during the build process that associate minified or transpiled code with its original source. They are particularly useful for JavaScript and TypeScript applications using bundlers such as Webpack, Rollup, or Vite, where production code is optimized for size and performance. Without source maps, error stack traces reference the minified code, complicating issue identification. When uploaded to Telebugs and linked to a release, source maps allow automatic unminification, displaying errors with references to the original file, line, and code context.

To generate source maps, enable the appropriate option in your bundler configuration (e.g., set sourceMap: true).

13.2 Integrating source maps with releases ¶

In Telebugs, source maps are associated with specific releases (see Releases) to ensure they align with the corresponding application version. This linkage allows Telebugs to apply the correct maps when processing error reports. Access releases via the "Releases (N)" link in the project dashboard (see Individual project view).

Create a release manually, via SDK, or using the Sentry CLI before uploading source maps (see Creating releases).

13.3 Uploading source maps ¶

Upload source maps to an existing release either manually through the user interface or automatically using the Sentry CLI tool, which is compatible with Telebugs.

• Manual upload: Navigate to the release details (see Release details), select Attach artifacts (or drag and drop), and upload the .map files. Multiple files can be uploaded simultaneously.
• Automated upload: Obtain an API key from account settings (see Regenerating your API key). The API key starts with tlbgs_.

  Before running the commands, set the following environment variables:

  export SENTRY_URL=<your-telebugs-url>
  export SENTRY_AUTH_TOKEN=tlbgs_<your-api-key>
  export SENTRY_PROJECT=<your-project-id>
  export SENTRY_ORG=<any-value> # This is not used but required for compatibility
  

  Execute the following commands:

  sentry-cli sourcemaps upload --release=<version> ./path/to/maps
  

  For builds requiring injection of source map references:

  sentry-cli sourcemaps inject ./build
  sentry-cli sourcemaps upload --release=<version> ./build
  

Upon upload, Telebugs applies the maps to incoming error reports, resolving minified traces without further configuration. To verify, trigger a test error and review the resolved stack trace in the report.

13.4 Managing source maps ¶

Source maps appear as artifacts in the release details page (see Release details). From there, download individual maps for inspection or delete the entire release to remove associated maps. Deletion affects unminification for errors linked to that release, so confirm no active dependencies exist beforehand.

For organization, use descriptive release versions. Apply data retention policies as needed to manage storage (see Data retention), exporting essential data prior to deletion.

14.1 Error report structure ¶

Error reports in Telebugs are composed of multiple sections, each offering specific insights into the error event. This structure mirrors Sentry’s event payload model, which includes required fields like event ID and timestamp, as well as optional interfaces for richer context. The following subsections detail each component.

• Report details
• Backtrace
• HTTP Request
• Tags
• Breadcrumbs
• Contexts
• Dependencies
• SDK
• Affected user
• Additional data

Next: Backtrace, Up: Error report structure   [Contents]

14.1.1 Report details ¶

The Report details section offers a high-level overview to quickly assess the error’s impact and origin, including:

• Error message: The specific message associated with the error, often the primary description of what went wrong.
• When: A human-readable timestamp indicating when the error occurred relative to now (e.g., "5 minutes ago").
• Occurred at: The exact timestamp of the error, formatted in the project’s timezone.
• Handled: Whether the error was handled (caught and reported manually) or uncaught (e.g., an unhandled exception).
• Severity: The severity level of the error (e.g., fatal, error, warning, info, debug), which helps prioritize issues.
• Server name: The name or identifier of the server where the error occurred, useful for distributed systems.
• Environment: The application environment (e.g., production, staging, development)

---

Next: HTTP Request, Previous: Report details, Up: Error report structure   [Contents]

14.1.2 Backtrace ¶

The Backtrace section displays the backtrace leading to the error, which is crucial for pinpointing the exact location in code where the issue arose. Each frame includes:

• Filename: The file where the code executed.
• Function: The method or function name.
• Line number: The specific line in the file, with optional column number.

Code snippets from the relevant lines are shown, with the error line highlighted in orange for emphasis. If source maps are applied (for minified code), both original and minified views are available. Frames can be expanded to show pre- and post-context lines of code.

This corresponds to Sentry’s exception or threads interface, which captures the call stack. It supports features like "in-app" frames to distinguish application code from dependencies.

To verify, expand frames and check if the highlighted line matches the error description.

---

Next: Tags, Previous: Backtrace, Up: Error report structure   [Contents]

14.1.3 HTTP Request ¶

For web applications, the HTTP Request section captures request details, providing context about the network interaction that led to the error:

• Method: HTTP method (e.g., GET, POST).
• URL: The requested URL, including query parameters if present.
• Request headers: All headers sent with the request, such as User-Agent or Content-Type.
• Request env: Additional environment variables, like remote address or server protocol.
• Request data: Any body data, such as form parameters or JSON payload (if captured).

This section maps to Sentry’s request interface, which helps reproduce errors by showing the exact request state. It’s particularly useful for debugging API or web-related issues.

---

Next: Breadcrumbs, Previous: HTTP Request, Up: Error report structure   [Contents]

14.1.4 Tags ¶

Tags are key-value pairs providing additional context, such as request IDs, custom labels, or system metrics (e.g., "browser: Chrome", "os: Windows"). In Telebugs, tags appear in a table format and can be used for filtering and searching error reports. This aligns with Sentry’s tags interface, enabling categorization and quick querying across events.

Add tags via the SDK to enhance searchability, e.g., Telebugs.setTag('user_role', 'admin').

---

Next: Contexts, Previous: Tags, Up: Error report structure   [Contents]

14.1.5 Breadcrumbs ¶

Breadcrumbs are chronological events leading up to the error, forming a timeline of actions. Each breadcrumb includes:

• Timestamp: When the event occurred.
• Category: Type of breadcrumb (e.g., console, http, navigation).
• Message: Descriptive text.
• Data: Additional payload, such as URL for HTTP requests.
• Level: Severity, if applicable.

Breadcrumbs can be expanded to view detailed data in JSON format. This section corresponds to Sentry’s breadcrumbs interface, which records events like log statements, UI interactions, or network calls, aiding in reconstructing the error sequence.

Configure the SDK to automatically capture breadcrumbs for better diagnostic trails.

---

Next: Dependencies, Previous: Breadcrumbs, Up: Error report structure   [Contents]

14.1.6 Contexts ¶

Contexts provide environmental information about the runtime and system:

• OS: Operating system details, including name and version.
• Runtime: Runtime environment (e.g., Node.js version, Python interpreter).
• Trace: Tracing information like trace ID and span ID for distributed tracing.
• Device: Hardware details, such as model or battery level.
• Browser: Browser-specific data, if applicable.

Displayed in a table, this maps to Sentry’s contexts interface, offering multi-faceted context (e.g., app, device, GPU) to understand the error’s surroundings.

---

Next: SDK, Previous: Contexts, Up: Error report structure   [Contents]

14.1.7 Dependencies ¶

The Dependencies section lists all loaded modules or packages with their versions (e.g., "express: 4.17.1"). This corresponds to Sentry’s modules attribute, helping identify if a specific library version is causing issues.

Review this for potential compatibility problems or outdated libraries.

---

Next: Affected user, Previous: Dependencies, Up: Error report structure   [Contents]

14.1.8 SDK ¶

The SDK section identifies the Sentry SDK used, including name (e.g., "sentry-javascript") and version. This aligns with Sentry’s sdk interface, which includes details like integrations and packages, ensuring compatibility and tracing SDK-related anomalies.

---

Next: Additional data, Previous: SDK, Up: Error report structure   [Contents]

14.1.9 Affected user ¶

The Affected user section captures information about the user impacted by the error:

• User ID: Unique identifier.
• Username: Display name.
• Email: Contact email.
• IP address: User’s IP.
• Geo location: City, region, country (derived from IP).

Additional user data can be included in an extra data subsection. This maps to Sentry’s user interface, aiding in user-specific debugging and personalization.

Set user context via the SDK, e.g., Telebugs.setUser({ id: '123', email: '[email protected]' }).

---

Previous: Affected user, Up: Error report structure   [Contents]

14.1.10 Additional data ¶

The Additional data section holds arbitrary key-value pairs for custom metadata (e.g., session variables or debug info). This corresponds to Sentry’s extra interface, allowing flexible extension of event data.

Use this for application-specific details not covered by other sections.

---

14.2 Grouping rules ¶

Grouping rules determine how similar errors are grouped together in Telebugs. This helps reduce noise and makes it easier to focus on unique issues. Telebugs uses a fingerprinting mechanism similar to Sentry’s, where events with matching fingerprints (e.g., based on backtrace or custom rules) are aggregated into a single issue.

In Telebugs, the grouping process starts by checking for a custom fingerprint provided via the SDK. If present, it computes the fingerprint by hashing the custom value (or joined array values separated by "|"). If no custom fingerprint is set, Telebugs generates a default fingerprint by hashing a "group string" derived from the event data in this order of priority:

• Backtrace (stack trace): If a stack trace is available in exceptions or threads, the group string is built from relevant frames, preferring "in-app" frames (application code) over system frames. For each frame, it concatenates the filename, function name, and line number. This ensures errors with similar application code paths are grouped, ignoring unrelated differences.
• Exception: If no stack trace exists but exception data is present, the group string combines the exception type (e.g., "TypeError") and value (e.g., "Cannot read property ’x’ of undefined").
• Message: As a fallback, it uses the log entry message or formatted message, grouping based on the error description.

This hierarchical approach mirrors Sentry’s default strategies, focusing on stack traces for precision, falling back to exceptions or messages when needed. For example, two exceptions with identical application stack traces but different system frames would share the same fingerprint and group together.

Grouping details, accessible via a square stack icon in error reports, show the fingerprint (e.g., a hash like 7bcb86ee6ce64c0a8d0f37fde2ff18c), method (e.g., "backtrace"), specific frames, message, and merged errors.

• Custom fingerprinting
• Manual group merging
• Grouping details visibility

begin
  # Some code that might fail
rescue StandardError => e
  Sentry.capture_exception(e, fingerprint: ["payment-failure"])
end

begin
  # Some code that might fail
rescue StandardError => e
  action = "checkout"  # From app context
  Sentry.capture_exception(e, fingerprint: ["error", action])
end

Next: Grouping details visibility, Previous: Custom fingerprinting, Up: Grouping rules   [Contents]

14.2.2 Manual group merging ¶

Telebugs allows manual group merging to combine similar errors that end up in separate groups due to minor differences, keeping error tracking organized. Once merged, future reports matching either original group are directed to the new combined group. This action is irreversible, so users are advised to double-check the URLs before confirming.

Steps for manual group merging:

1. Navigate to the error group you want to keep as the main one.
2. Click the Merge button.
3. A dialog opens with the text "Merge errors dialog".
4. Enter the URLs of the error groups you want to merge into the main group.
5. Press Merge Errors to confirm.

For instance, if there are two groups for Database Connection Failed — one with a timeout message and another with a retry failure — they can be merged into a single group for easier management.

---

Previous: Manual group merging, Up: Grouping rules   [Contents]

14.2.3 Grouping details visibility ¶

Telebugs adds grouping details to error reports, enabling users to see why an error was grouped in a particular way, including the fingerprint used. This feature enhances transparency and helps verify or adjust grouping logic.

When viewing an error report, a new button resembling a "square stack" is available. Clicking this button reveals the grouping details, which include:

• Fingerprint: A unique MD5 hash identifier for the error group, e.g., 7bcb86ee6ce64c0a8d0f37fde2ff18c.
• Method: The grouping method used, such as “custom” (for SDK-provided fingerprints), “backtrace” (stack trace-based), “exception” (type and value), or “message” (error message).
• Frames: For backtrace method, lists specific stack frames used for grouping, including filename, function, and line number—focusing on in-app frames if available.
• Message: For message method, the error message that determined the grouping.
• Merged errors: Details of other groups merged into this one, including their fingerprints.

This visibility helps pinpoint grouping issues, debug why certain errors are separated (e.g., due to differing stack frames or messages), and ensures accurate error organization. If the default grouping doesn’t suit your needs, use custom fingerprints or manual merging to refine it.

---

14.3 Notes ¶

Notes in Telebugs allow team members to annotate error reports with additional context, explanations, or updates, fostering collaboration and helping track the resolution process. Notes are visible to all project members and appear in a chronological feed within the error group’s details. This section covers how to create, view, and manage notes, including attachments for richer documentation.

• Viewing notes
• Adding notes
• Managing notes

Next: Adding notes, Up: Notes   [Contents]

14.3.1 Viewing notes ¶

Access notes by navigating to an error group’s page and selecting the Notes tab or section. The feed displays each note with:

• User information: The author’s profile picture (or a default avatar), name (linked to their profile if active), and a timestamp (e.g., "5 minutes ago" with a tooltip for the exact UTC time).
• Content: The note’s text, rendered in a monospace font for code snippets or logs, with automatic linkification for URLs.
• Attachments: If included, a grid of thumbnails for images or icons for other files (e.g., videos, documents), with links to download or view. File names and sizes are shown below each item.
• Delete option: Authors can delete their own notes via a trash icon, with a confirmation prompt.

Notes from inactive users are still visible but without profile links. The feed is sorted oldest to newest, making it easy to follow discussions over time.

For example, a note might include a screenshot of the error in production, a code diff for a potential fix, or a link to a related ticket in your issue tracker.

Fun fact: The first attachment of an error is used as the error’s main image in the dashboard, providing a quick visual reference.

---

Next: Managing notes, Previous: Viewing notes, Up: Notes   [Contents]

14.3.2 Adding notes ¶

To add a note:

1. In the error group’s page, scroll to the Add a new note section at the bottom of the notes feed.
2. Enter your content in the text area (plain text, supports code blocks or lists via formatting).
3. Optionally attach files:
   • Click Attach files to open a file picker (supports multiple files).
   • Or drag-and-drop files onto the page — an overlay appears prompting to Drop any file here to add it to your note.
   • Supported file types include images (displayed as previews), videos, documents, etc. A list of attached files with names and sizes appears below the text area.
   • Remove attachments before submitting if needed.
4. Click Add note to submit.

Attachments are uploaded directly (with progress indicators if large) and can be up to reasonable sizes; however, for storage management, project admins can purge all note attachments via the project’s danger zone settings, triggering a background job.

This feature is ideal for collaborative debugging — e.g., one developer adds a reproduction step, another attaches a log file, and a third notes the fix deployment.

---

15.1 Error retention policy ¶

The error retention policy controls the lifecycle of error reports and associated data (e.g., backtraces, breadcrumbs, tags). Enable it to automatically remove old or excess data, preventing database bloat. Policies include time-based (deleting reports older than a set period) and disk-based (purging when usage exceeds limits) options.

• Enabling error retention
• Time-based cleanup
• Disk-based cleanup

Next: Time-based cleanup, Up: Error retention policy   [Contents]

15.1.1 Enabling error retention ¶

Access the policy via the "Data Retention" section in settings. Toggle "Enable automatic error cleanup" to activate. Once enabled, configure sub-options for time- or disk-based rules. The UI shows the next cleanup time (e.g., "in 12 hours") and requires saving changes to apply.

---

Previous: Time-based cleanup, Up: Error retention policy   [Contents]

15.1.3 Disk-based cleanup ¶

Disk-based cleanup activates when the database file exceeds a limit, purging oldest reports first (full purge only). Limits can be:

• Absolute: Fixed size in GB (e.g., 10 GB).
• Percentage: Of total disk size (e.g., 35%).

The system estimates excess by average report size, then deletes until under the limit. This runs alongside time-based if both enabled.

Monitor via disk stats: total size, free space, database usage (size and percentage), and report count.

---

15.2 Artifact retention policy ¶

Artifacts (e.g., source maps uploaded with releases) have separate retention to manage storage independently. Policies mirror errors but focus on releases without recent reports.

• Enabling artifact retention
• Time-based artifact cleanup
• Disk-based artifact cleanup
• Purge on new release

Next: Time-based artifact cleanup, Up: Artifact retention policy   [Contents]

15.2.1 Enabling artifact retention ¶

Toggle "Enable automatic artifact cleanup" in settings. Configure time- or disk-based rules, plus an option to purge on new release uploads.

---

15.3 Monitoring and maintenance ¶

View real-time stats in the Data Retention dashboard: total/free disk, database/artifact sizes, percentages, and counts. Cache refreshes automatically post-cleanup.

For optimization, a VACUUM job reclaims space if sufficient free disk exists (database size + 10% buffer). Run via cron nightly.

Purged data is irreversible; export critical reports beforehand. Use partial purges for errors to retain analytics value. For projects, admins can purge all data or attachments via danger zone, triggering dedicated jobs.