Telebugs Investigation

Telebugs Error Investigation

Systematic approach to investigating production errors reported in Telebugs.

REQUIRED: Use the telebugs skill for tool loading, data fetching, and response parsing.

Phase 1: Data Retrieval

Follow the telebugs skill to:

1. Load deferred MCP tools
2. Extract group_id from the URL
3. Fetch error group + latest report in parallel
4. Parse the large report response (error details, stack traces, breadcrumbs, metadata)

Phase 2: Pattern Recognition

After extracting all data, analyze:

• Occurrence count: from error group's occurrences, first_seen, last_seen
• Team notes: error group notes often contain prior investigation context or merged group history
• Temporal patterns: frequency trends, time of day patterns
• Deployment correlation: compare release hash with recent commits
• Breadcrumb sequence: what database operations or job events led to the error?
• Breadcrumb timing gaps: large time gaps (10-20s+) between timestamps indicate blocking operations (DNS timeout, HTTP timeout, slow query) that are often the actual root cause
• Related errors: check for siblings in the same time window

mcp__telebugs__list_error_groups(project_id, status: "open", limit: 10)
mcp__telebugs__search_errors(query: "keyword")

Phase 3: Root Cause Analysis

• Read source code from every in-project stack trace frame. Never propose fixes without reading the actual code first.
• Check the full exception chain — stack_traces contains multiple exceptions; the top one is often a wrapper, the cause is in later exceptions.
• Trace the call chain beyond the stack trace — the stack trace shows where the error was raised, but trace backward from the culprit (job class) through service layers to find the triggering call.
• Identify contributing factors: DNS timeouts, race conditions, unique constraint violations, API failures, etc.
• Determine regression scope: compare release commit hash with git log to identify when the error was introduced.

Phase 4: Solution Development

• Provide specific code fixes with before/after examples
• Include defensive programming patterns to prevent recurrence
• Distinguish immediate hotfix vs. comprehensive solution
• Recommend testing strategies to validate fixes
• Identify other code paths that may have the same vulnerability

Phase 5: Deliverables

Always present findings in this structure:

1. Executive Summary (2-3 sentences) What broke, why it broke, and business impact

2. Technical Analysis

   • Exact root cause with file path and line number
   • Full exception chain explanation
   • Contributing factors and conditions
   • Breadcrumb timeline leading to the error

3. Immediate Action Plan

   • Code changes (before/after, copy-paste ready)
   • New test cases covering the fix
   • Validation steps to confirm the fix works

4. Long-term Improvements

   • Architectural changes to prevent recurrence
   • Monitoring and alerting improvements

5. Risk Assessment

   • Potential side effects of proposed fixes
   • Other areas that might be affected

6. Dashboard Link Always include the Telebugs URL: https://<your-telebugs-host>/errors/{group_id}

Common Investigation Mistakes