Debugging

Teabar provides comprehensive debugging tools to help you identify and resolve issues in your environments. This guide covers debugging techniques from basic log inspection to advanced distributed tracing.

Debug Mode

Enable debug mode for verbose output:

# Enable for single command
TEABAR_DEBUG=1 teabar env create my-env

# Enable globally
teabar config set debug true

# Set debug level (1-3)
teabar config set debug.level 2

Debug levels:

• Level 1: Basic debug info (API calls, timing)
• Level 2: Detailed debug info (request/response bodies)
• Level 3: Verbose debug info (internal state, stack traces)

Log Analysis

Viewing Logs

# View recent logs
teabar logs my-env

# Follow logs in real-time
teabar logs my-env --follow

# View specific component logs
teabar logs my-env --component api

# View logs from specific time range
teabar logs my-env --since "2024-01-15 10:00:00" --until "2024-01-15 11:00:00"

# Filter by log level
teabar logs my-env --level error
teabar logs my-env --level warn,error

# Search logs
teabar logs my-env --grep "connection refused"

Log Formats

teabar logs my-env

2024-01-15 10:30:01 [api] INFO  Server started on port 8080
2024-01-15 10:30:02 [api] INFO  Connected to database
2024-01-15 10:30:15 [api] WARN  Slow query detected (2.3s)
2024-01-15 10:30:45 [api] ERROR Connection timeout to redis

Log Aggregation

Aggregate logs from multiple environments:

# Logs from all environments in a project
teabar logs --project frontend

# Logs matching a pattern
teabar logs --env "feature-*" --grep "error"

# Export logs
teabar logs my-env --since 24h --output logs.txt

Interactive Debugging

Shell Access

# Open shell in environment
teabar exec my-env -- /bin/bash

# Open shell in specific component
teabar exec my-env --component api -- /bin/sh

# Run single command
teabar exec my-env -- ps aux

# Run with specific user
teabar exec my-env --user root -- cat /etc/passwd

Process Inspection

# List running processes
teabar exec my-env -- ps aux

# View process tree
teabar exec my-env -- pstree -p

# Check open files
teabar exec my-env -- lsof -p <pid>

# View network connections
teabar exec my-env -- netstat -tulpn

File System Inspection

# List files
teabar exec my-env -- ls -la /app

# View file contents
teabar exec my-env -- cat /app/config.json

# Check disk usage
teabar exec my-env -- df -h

# Find large files
teabar exec my-env -- find /app -size +100M

Metrics Analysis

Real-Time Metrics

# Stream metrics
teabar metrics stream my-env

# Watch specific metrics
teabar metrics stream my-env --metrics cpu_usage,memory_percent

# Compare with baseline
teabar metrics compare my-env --baseline "24h ago"

Historical Analysis

# View metric history
teabar metrics history my-env --metric cpu_usage --since 7d

# Export for analysis
teabar metrics export my-env --since 7d --format csv --output metrics.csv

# Generate report
teabar metrics report my-env --since 7d --output report.html

Anomaly Detection

# Check for anomalies
teabar metrics anomalies my-env

# View anomaly details
teabar metrics anomalies my-env --verbose

Output:

Detected Anomalies (last 24h)

1. CPU Spike at 2024-01-15 14:32:00
   Normal range: 20-45%
   Observed: 98%
   Duration: 3 minutes
   Correlation: Deployment deploy_abc123

2. Memory Growth at 2024-01-15 10:00:00
   Normal range: 1.2-1.5 GB
   Observed: Steady increase to 3.2 GB
   Duration: 4 hours
   Correlation: Possible memory leak

Network Debugging

Connectivity Tests

# Test internal connectivity
teabar network test my-env --target database

# Test external connectivity
teabar network test my-env --target https://api.example.com

# DNS resolution test
teabar exec my-env -- nslookup database

Traffic Inspection

# View active connections
teabar network connections my-env

# Monitor traffic
teabar network traffic my-env --follow

# Capture packets (requires admin)
teabar network capture my-env --duration 60s --output capture.pcap

Port Forwarding for Debug

# Forward local port to environment
teabar port-forward my-env 8080:8080

# Forward multiple ports
teabar port-forward my-env 8080:8080 5432:5432

# Access debug endpoints
curl http://localhost:8080/debug/pprof/

Application Profiling

CPU Profiling

# Capture CPU profile
teabar profile my-env --type cpu --duration 30s

# View profile
teabar profile view profile_abc123

# Download for local analysis
teabar profile download profile_abc123 --output cpu.prof
go tool pprof cpu.prof

Memory Profiling

# Capture heap profile
teabar profile my-env --type heap

# View memory allocations
teabar profile view profile_def456 --top 20

# Compare profiles
teabar profile diff profile_abc123 profile_def456

Trace Collection

# Collect execution trace
teabar trace my-env --duration 10s

# View trace
teabar trace view trace_xyz789

# Export trace
teabar trace export trace_xyz789 --format jaeger --output trace.json

Distributed Tracing

Enable Tracing

# teabar.yaml
tracing:
  enabled: true
  provider: jaeger  # or zipkin, datadog
  sample_rate: 0.1  # Sample 10% of requests
  
  # Provider-specific config
  jaeger:
    endpoint: https://jaeger.example.com
    service_name: my-app

View Traces

# List recent traces
teabar traces list my-env --since 1h

# View trace details
teabar traces show trace_abc123

# Search traces
teabar traces search my-env --operation "POST /api/users" --min-duration 1s

Trace Analysis

# Find slow traces
teabar traces slow my-env --threshold 2s

# Find error traces
teabar traces errors my-env --since 1h

# Analyze latency breakdown
teabar traces analyze trace_abc123

Diagnostic Bundle

Generate a comprehensive diagnostic bundle for support:

# Generate bundle
teabar diagnose my-env --output diagnostic.zip

Bundle includes:

• Environment configuration
• Recent logs (last 24h)
• Metrics snapshots
• Health check results
• Network configuration
• Resource usage history
• Event timeline

Debugging Checklist

Use this checklist when debugging issues:

1. Gather Information

teabar env status my-env --verbose
teabar health my-env --verbose
teabar logs my-env --since 1h --level error

2. Check Resources

teabar metrics show my-env
teabar exec my-env -- df -h
teabar exec my-env -- free -m

3. Verify Connectivity

teabar network test my-env --all
teabar exec my-env -- curl -I http://localhost:8080/health

4. Review Recent Changes

teabar activity --env my-env --since 24h
teabar deploy history --env my-env

5. Compare with Working State

teabar checkpoint list --env my-env
teabar metrics compare my-env --baseline "yesterday"

Debug Tools Reference

Best Practices

1. Start with logs - Most issues are visible in application logs
2. Check metrics - Resource exhaustion is a common root cause
3. Reproduce consistently - Identify the exact steps to trigger the issue
4. Isolate components - Test each component independently
5. Document findings - Keep notes on what you’ve tried and discovered
6. Use checkpoints - Save state before making debug changes