Debugging & Troubleshooting

Module Overview

Effective debugging and troubleshooting skills are essential for provider development. This module covers systematic approaches to identifying and resolving issues.

What You’ll Learn

Core Concepts

1. Logging Strategies
   • Structured logging
   • Log levels
   • Context propagation
   • Performance considerations
2. Debugging Techniques
   • Debugger setup (Delve)
   • Breakpoint strategies
   • Variable inspection
   • Remote debugging
3. Common Issues
   • State inconsistencies
   • API errors
   • Type mismatches
   • Performance problems
4. Diagnostic Tools
   • Terraform debugging flags
   • Provider logs
   • Network inspection
   • Profiling tools
5. Error Investigation
   • Stack traces
   • Error patterns
   • Root cause analysis
   • Reproduction strategies

Module Structure

Chapter 1: Logging Strategies

Implement effective logging for observability and debugging.

Topics:

• Structured logging with tflog
• Log levels and filtering
• Sensitive data redaction
• Performance considerations

Outcome: Comprehensive logging implementation

Chapter 2: Debugging Techniques

Master debugger usage and debugging workflows.

Topics:

• Delve debugger setup
• VSCode integration
• Breakpoint strategies
• Remote debugging

Outcome: Efficient debugging workflow

Chapter 3: Common Issues

Identify and resolve typical provider problems.

Topics:

• State management issues
• API integration problems
• Type system errors
• Performance bottlenecks

Outcome: Systematic issue resolution

Chapter 4: Troubleshooting Lab

Practice debugging in real-world scenarios.

Topics:

• Debugging exercises
• Issue reproduction
• Root cause analysis
• Fix verification

Outcome: Practical debugging skills

Prerequisites

Before starting this module:

• ✅ Completed Modules 1-14
• ✅ Understanding of Go debugging
• ✅ Familiarity with Terraform internals
• ✅ Development environment set up

Learning Outcomes

After completing this module, you will:

• ✅ Implement structured logging effectively
• ✅ Use debugger efficiently
• ✅ Identify common provider issues
• ✅ Troubleshoot production problems
• ✅ Analyze error patterns
• ✅ Reproduce and fix bugs systematically

Debugging Workflow

Issue Reported
    ↓
Gather Information
├── User configuration
├── Error messages
├── Provider logs
└── Environment details
    ↓
Reproduce Issue
├── Minimal configuration
├── Consistent environment
└── Debug logging enabled
    ↓
Investigate
├── Add logging
├── Use debugger
├── Check documentation
└── Review code
    ↓
Identify Root Cause
├── State problem?
├── API issue?
├── Code bug?
└── Configuration error?
    ↓
Develop Fix
├── Write test
├── Implement solution
├── Verify fix
└── Document
    ↓
Release
├── Update CHANGELOG
├── Tag version
└── Communicate

Key Tools

Logging

# Enable detailed logging
export TF_LOG=TRACE
export TF_LOG_PROVIDER=TRACE
export TF_LOG_PATH=terraform.log

# Provider-specific logging
export CACHECLOUD_LOG_LEVEL=DEBUG

Debugging

# Run with debugger
dlv debug ./main.go -- --debug

# Attach to running process
dlv attach <pid>

Profiling

# CPU profile
go test -cpuprofile=cpu.prof -bench=.
go tool pprof cpu.prof

# Memory profile
go test -memprofile=mem.prof -bench=.
go tool pprof mem.prof

Best Practices

1. Structured Logging

// ✅ Good: Structured with context
tflog.Debug(ctx, "Creating cache", map[string]interface{}{
    "name":      plan.Name.ValueString(),
    "node_type": plan.NodeType.ValueString(),
})

// ❌ Bad: Unstructured string
fmt.Printf("Creating cache %s with type %s\n", name, nodeType)

2. Error Context

// ✅ Good: Wrapped with context
if err != nil {
    return fmt.Errorf("failed to create cache %s: %w", name, err)
}

// ❌ Bad: Lost context
if err != nil {
    return err
}

3. Reproducible Tests

// ✅ Good: Isolated, reproducible
func TestCreateCache(t *testing.T) {
    client := newTestClient()
    cache := testCache("test-name")
    // Test logic
}

// ❌ Bad: Depends on external state
func TestCreateCache(t *testing.T) {
    // Uses production API
}

Common Pitfalls

State Drift

Problem: Terraform state out of sync with reality
Cause: Manual changes, failed operations
Solution: Implement robust Read() logic, state refresh

Type Mismatches

Problem: "cannot unmarshal" errors
Cause: Struct tags mismatch, type conversion errors
Solution: Validate types, use proper conversion

API Rate Limits

Problem: 429 Too Many Requests
Cause: Too many API calls
Solution: Implement retry logic, caching, batching

Memory Leaks

Problem: Growing memory usage
Cause: Unclosed connections, unbounded caches
Solution: Proper cleanup, bounded caches, profiling

Key Takeaways

• ✅ Use structured logging throughout
• ✅ Master debugger for efficiency
• ✅ Understand common issues
• ✅ Reproduce bugs systematically
• ✅ Profile performance problems
• ✅ Document troubleshooting steps
• ✅ Test fixes thoroughly

What’s Next?

Learn structured logging strategies for effective debugging.

Next: Logging Strategies →

---

Previous Module: ← Advanced Topics
Next: Logging Strategies →

Last updated: July 2, 2026