Turbo Monitor Debug

Monitor and Debug Turbo Pipelines

Monitor pipeline health, view logs, inspect live data, and troubleshoot issues.

Triggers

Invoke this skill when the user:

• Says "check my pipeline", "view logs", or "debug the pipeline"
• Wants to see live data flowing through a pipeline
• Is troubleshooting pipeline errors or issues
• Asks "why isn't my pipeline working?"
• Wants to monitor pipeline health
• Mentions /turbo-monitor-debug

Agent Instructions

When this skill is invoked, follow this interactive workflow:

Step 1: Verify Authentication

Run goldsky project list 2>&1 to check login status.

If output shows projects: User is logged in. Continue to Step 2.

If output contains "Make sure to run 'goldsky login'":

1. Inform the user they need to authenticate
2. Invoke the goldsky-auth-setup skill
3. After successful login, return to this skill to continue

Step 2: Identify the Pipeline

Use AskUserQuestion to ask:

• Question: "Which pipeline do you want to monitor?"
• Options:
  • "I know the pipeline name" (description: "I'll provide the name or YAML file")
  • "Show me my pipelines" (description: "List all pipelines in my project")

If "I know the pipeline name":

Ask for the pipeline name or YAML file path.

If "Show me my pipelines":

Run goldsky turbo list to show existing pipelines.

Ask which pipeline they want to monitor.

Step 3: Determine the Goal

Use AskUserQuestion to ask:

• Question: "What do you want to do?"
• Options:
  • "View live data" (description: "See data flowing through the pipeline in real-time")
  • "Check logs" (description: "View pipeline execution logs")
  • "Debug an issue" (description: "Something isn't working right")
  • "Check overall health" (description: "Quick status check")

Based on their selection, follow the appropriate workflow below.

Workflow: View Live Data

Step 1: Open Live Inspect

goldsky turbo inspect <pipeline-name>

Or with a YAML file:

goldsky turbo inspect <pipeline.yaml>

This opens an interactive TUI (Terminal User Interface) showing live data.

Step 2: Navigate the TUI

Explain the keyboard shortcuts:

Navigation:

Search:

Actions:

Tip: Hold Shift while using the mouse to select and copy text from the TUI.

Step 3: Filter to Specific Nodes

To focus on a specific source or transform:

goldsky turbo inspect <pipeline-name> -n <node-name>

View multiple nodes:

goldsky turbo inspect <pipeline-name> -n source1,transform1

Step 4: Adjust Buffer Size

For more history, increase the buffer:

goldsky turbo inspect <pipeline-name> -b 50000

Default is 10,000 records.

Workflow: Check Logs

Step 1: View Recent Logs

goldsky turbo logs <pipeline-name>

Default shows last 10 lines.

Step 2: Adjust Log Output

Show more lines:

goldsky turbo logs <pipeline-name> --tail 50

Show logs from last hour:

goldsky turbo logs <pipeline-name> --since 3600

Include timestamps:

goldsky turbo logs <pipeline-name> --timestamps

Follow logs in real-time:

goldsky turbo logs <pipeline-name> --follow

Step 3: Analyze Log Output

Look for these patterns:

Healthy indicators:

• Processing messages with block numbers
• Checkpoint updates
• No error messages

Warning indicators:

• Slow processing messages
• Retry attempts
• Connection warnings

Error indicators:

• Error: or ERROR messages
• Stack traces
• Connection failures

Workflow: Debug an Issue

Step 1: Identify the Problem

Use AskUserQuestion to ask:

• Question: "What issue are you experiencing?"
• Options:
  • "No data flowing" (description: "Pipeline seems stuck or empty")
  • "Errors in logs" (description: "Seeing error messages")
  • "Wrong data output" (description: "Data doesn't look right")
  • "Sink not receiving data" (description: "Database/Kafka not getting updates")
  • "Pipeline keeps restarting" (description: "Unstable behavior")

Based on their selection, follow the appropriate debugging steps.

Debugging: No Data Flowing

1. Check pipeline status:

   goldsky turbo list
   

   Verify the pipeline shows as running.

2. Check the source configuration:

   • If start_at: latest, pipeline only processes new data
   • If chain is slow, there may be no new data yet
   • Try start_at: earliest for testing (will process historical data)

3. Check logs for errors:

   goldsky turbo logs <pipeline-name> --tail 50
   

4. Verify source dataset exists:

   goldsky datasets list | grep <dataset-name>
   

Debugging: Errors in Logs

1. Get detailed logs:

   goldsky turbo logs <pipeline-name> --tail 100 --timestamps
   

2. Common error patterns:

   Error Pattern	Likely Cause	Fix
   connection refused	Database unreachable	Check network/firewall settings
   authentication failed	Wrong credentials	Update secret with correct credentials
   secret not found	Missing secret	Create secret with goldsky-secrets
   SQL syntax error	Invalid transform SQL	Fix SQL in YAML and redeploy
   duplicate key	Primary key collision	Ensure unique primary key in transform

3. If SQL error, validate the pipeline:

   goldsky turbo validate <pipeline.yaml>
   

Debugging: Wrong Data Output

1. Inspect each stage of the pipeline:

   # Check source data
   goldsky turbo inspect <pipeline-name> -n <source-name>
   
   # Check transform output
   goldsky turbo inspect <pipeline-name> -n <transform-name>
   

2. Compare source vs transform:

   goldsky turbo inspect <pipeline-name> -n source1,transform1
   

3. Common issues:

   • SQL WHERE clause too restrictive (filtering out all data)
   • Wrong column names in SQL
   • Type mismatches in transforms

Debugging: Sink Not Receiving Data

1. Verify the sink configuration:

   • Check from field points to correct source/transform
   • Check secret_name matches an existing secret

2. Check secret exists:

   goldsky secret list
   

3. Verify secret credentials:

   goldsky secret reveal <secret-name>
   

   Test the credentials work outside Goldsky (e.g., psql for PostgreSQL).

4. Check logs for sink errors:

   goldsky turbo logs <pipeline-name> --tail 50 | grep -i error
   

Debugging: Pipeline Keeps Restarting

1. Check logs around restart time:

   goldsky turbo logs <pipeline-name> --tail 100 --timestamps
   

2. Common causes:

   • Out of memory (try larger resource_size)
   • Infinite loop in TypeScript transform
   • Database connection pool exhaustion

3. Try increasing resources:

   Update resource_size: m or resource_size: l in YAML and redeploy.

Workflow: Check Overall Health

Step 1: List All Pipelines

goldsky turbo list

Check status column for each pipeline.

Step 2: Quick Log Check

goldsky turbo logs <pipeline-name> --tail 20

Look for recent errors or warnings.

Step 3: Verify Data Flow

goldsky turbo inspect <pipeline-name>

Confirm data is flowing through each node.

Step 4: Provide Health Summary

After checking, provide a summary:

## Pipeline Health Check

**Pipeline:** [name]
**Status:** [running/stopped/error]

**Observations:**
- ✓ Pipeline is running
- ✓ Data flowing through sources
- ✓ Transforms processing correctly
- ✓ Sinks receiving data

**OR**

- ⚠ [Issue found - description]
- Action: [Recommended fix]

Prerequisites

• Goldsky CLI installed
• Turbo CLI extension installed
• Logged in (goldsky login)
• At least one deployed pipeline

Quick Reference

Live Inspect TUI Shortcuts

Auto-Reconnection

The TUI automatically reconnects when the pipeline is updated, paused, resumed, or temporarily unavailable. It displays "Reconnecting..." and preserves previously received data. The TUI has a 30-minute timeout — if the pipeline remains unreachable for 30 minutes, it closes automatically.

Error Pattern Reference

Detailed error patterns and solutions are in the data/ folder.

Data location: data/ (relative to this skill's directory)

Log Analysis Script

Use the helper script to quickly analyze pipeline logs:

./scripts/analyze-logs.sh <pipeline-name>
./scripts/analyze-logs.sh <pipeline-name> --tail 100

The script checks for common error patterns and reports findings with recommendations.

Common Issues Quick Reference

Troubleshooting

Related Skills

• /goldsky-auth-setup - Invoke this if user is not logged in
• /goldsky-secrets - Invoke this if credentials need to be updated
• /turbo-pipelines - Deploy new pipelines or modify configuration
• /turbo-lifecycle - List or delete pipelines