Documentation

GoRoutines Viewer

The GoRoutines tab shows all active goroutines in your application with their stack traces, states, and timing information. Instead of parsing walls of text from runtime dumps or pprof, you get a structured view where you can search, filter by state, and see condensed stack traces that focus on your code rather than runtime internals. Click any function or file reference to jump directly to that code in your editor. When you integrate the Outrig SDK, goroutines gain meaningful names like "web-worker-pool" instead of just "Goroutine 42", making it much simpler to track down deadlocks, spot leaks, or understand what each goroutine is actually doing. Everything updates with a single refresh—no need to add debug endpoints or dump stack traces to files.

Getting Started

When you select the GoRoutines tab for a running application, the viewer automatically loads and displays all active goroutines. Each goroutine shows its current state, stack trace, and timing information, giving you immediate insight into what your concurrent code is doing.

Core Features

Goroutine Snapshot Monitoring

The GoRoutines Viewer captures point-in-time snapshots of your application's goroutines, providing:

  • Current Snapshot: Shows the current state of all goroutines at the time of capture
  • Manual Refresh: Click the refresh button to capture a new snapshot when needed
  • State Tracking: Monitor goroutine states like "running", "chan receive", "IO wait", etc.
  • Timing Information: See when each goroutine started relative to your application launch
  • Stack Traces: Full stack traces showing exactly what each goroutine is executing

The snapshot approach prevents the constant movement that would make goroutines difficult to analyze if they updated in real-time.

Goroutine Information Display

Each goroutine entry shows comprehensive information:

Header Information

  • Name and ID: Custom goroutine names (if provided) plus the goroutine ID
  • Start Time: When the goroutine was created, shown as an offset from app start (e.g., "+2.5s")
  • Current State: The goroutine's current state with duration (e.g., "chan receive (2 minutes)")
  • Tags: Custom tags assigned to the goroutine (displayed with # prefix)

Goroutine Naming

By default, goroutines are identified only by their numeric ID (e.g., "Goroutine 42"). However, when using the Outrig SDK, you can assign meaningful names to your goroutines:

// Using the Outrig SDK to create named goroutines
outrig.Go("worker-pool-1").WithTags("worker").Run(func() {
    // Goroutine code...
})

outrig.Go("database-connection-handler").Run(func() {
    // Database handling code...
})

Named goroutines appear as "worker-pool-1 (42)" instead of just "Goroutine 42", making it much easier to:

  • Identify Purpose: Understand what each goroutine is responsible for
  • Search Effectively: Find specific goroutines by name rather than ID
  • Debug Issues: Quickly locate problematic goroutines in your application
  • Monitor Patterns: Track groups of related goroutines

Stack Trace Modes

The viewer offers three different stack trace display modes:

Raw Mode: Shows the complete, unfiltered stack trace exactly as Go generates it

  • Full function names and file paths
  • All frames including system and library code
  • Clickable file:line references for navigation

Simplified Mode: Shows a cleaned-up view focusing on your application code

  • Collapses system and library frames into summary lines
  • Highlights important frames with visual indicators
  • Function names become clickable links to source code
  • Package names are simplified for readability

Simplified with Files Mode: Like simplified mode but shows file paths separately

  • Important frames show both function and file information
  • File paths are clickable links
  • Maintains the collapsed view for non-essential frames

Powerful Search and Filtering

Text Search

The search bar provides instant filtering across all goroutine information:

# Search by goroutine name
worker

# Search by state
"chan receive"

# Search in stack traces
database.Query

# Use field-specific searches
$state:running
$name:worker
$goid:42

The search supports all of Outrig's advanced operators including regex, fuzzy matching, and exclusions.

State Filtering

Filter goroutines by their current state using clickable tags:

  • Show All: Display all goroutines regardless of state
  • State Tags: Click individual states like "running", "sleep", "chan receive" to filter
  • Multiple States: Select multiple states to see goroutines in any of those states
  • State Counts: Each state tag shows how many goroutines are currently in that state

System Goroutine Toggle

Control visibility of internal Outrig SDK goroutines:

  • #outrig Toggle: Show or hide goroutines created by the Outrig SDK itself
  • Clean View: Hide system goroutines to focus on your application code
  • Debug Mode: Show system goroutines when debugging SDK integration issues

Stack Trace Analysis

Intelligent Frame Collapsing

In simplified modes, the viewer intelligently groups stack frames:

  • Important Frames: Your application code and key library entry points are always visible
  • Collapsed Sections: System and library code is grouped into expandable sections
  • Smart Grouping: Shows package flow through collapsed sections (e.g., "... // 5 frames - net → http → myapp")
  • Click to Expand: Click any collapsed section to see the full frames

Code Navigation

Stack traces provide direct links to your source code:

  • File Links: Click file:line references to open in your editor
  • Function Links: In simplified mode, function names link directly to their definition
  • Hover Information: Hover over simplified functions to see file location

Created By Information

For goroutines created by other goroutines, the viewer shows:

  • Parent Goroutine: Which goroutine created this one
  • Creation Stack: The stack trace of where the goroutine was created
  • Creation Context: Understand the flow that led to goroutine creation

Advanced Features

Search History and Tips

  • Search History: Access previous searches with arrow keys in the search bar
  • Search Tips: Click the ? button for interactive search operator reference
  • Field-Specific Search: Target specific goroutine fields like $state:, $name:, $goid:

Performance Optimization

  • Efficient Loading: Only loads visible goroutines for smooth performance
  • Smart Refresh: Refresh button reloads current goroutine state
  • Responsive UI: Virtual scrolling handles large numbers of goroutines

Copy and Export

  • Stack Trace Copy: Copy button on each goroutine copies the full raw stack trace
  • Clipboard Integration: Easy sharing of stack traces for debugging discussions

Navigation and Controls

Keyboard Shortcuts

  • PageUp / PageDown - Scroll through goroutines list
  • ↑ / ↓ in search bar - Open search history
  • Enter in search bar - Save current search to history
  • Escape - Clear search or close search history

Display Controls

  • Stack Trace Mode Toggle: Switch between raw, simplified, and simplified with files modes
  • Refresh Button: Reload current goroutine state from the application
  • State Filters: Click state tags to filter by goroutine state
  • System Toggle: Show/hide internal Outrig goroutines

Understanding Goroutine States

The GoRoutines Viewer displays various goroutine states that help you understand what your concurrent code is doing:

Common States

  • running: Goroutine is actively executing
  • runnable: Ready to run but waiting for CPU time
  • chan receive: Waiting to receive from a channel
  • chan send: Waiting to send to a channel
  • sleep: Sleeping (time.Sleep)
  • select: Waiting in a select statement
  • IO wait: Waiting for I/O operation to complete
  • sync.Mutex: Waiting to acquire a mutex
  • sync.Cond: Waiting on a condition variable

State Duration

When available, states show how long the goroutine has been in that state:

  • chan receive (2 minutes) - Waiting on channel for 2 minutes
  • sleep (1 hour) - Sleeping for 1 hour
  • running - Currently executing (no duration shown)

Duration is reported by the Go runtime and shows minutes as the minimum unit, scaling up to hours or days for long-running states.

Debugging Workflows

Finding Stuck Goroutines

  1. Look for goroutines with long state durations
  2. Search for specific states: $state:"chan receive"
  3. Examine stack traces to understand what they're waiting for
  4. Use simplified mode to focus on your application code

Analyzing Goroutine Leaks

  1. Monitor the total goroutine count over time
  2. Filter by specific states to find accumulating goroutines
  3. Look for goroutines that never change state
  4. Examine creation patterns in "created by" information

Performance Investigation

  1. Search for goroutines in performance-critical code paths
  2. Look for unexpected blocking states in hot paths
  3. Use state filtering to find goroutines waiting on I/O or locks
  4. Analyze stack traces to understand call patterns

Concurrency Debugging

  1. Search for specific function names or packages
  2. Use state filters to see goroutines waiting on channels or mutexes
  3. Examine "created by" information to understand goroutine spawning patterns
  4. Look for goroutines stuck in unexpected states

Tips for Effective Analysis

Using Search Effectively

  • Start broad with function or package names
  • Narrow down with state filters
  • Use exclusions to filter out noise: -#outrig
  • Combine searches: database $state:running

Stack Trace Modes

  • Use Raw mode when searching (automatically enabled) to see search matches
  • Use Simplified mode for general analysis and code navigation
  • Use Simplified with Files when you need to see exact file locations

State Monitoring

  • Watch state counts to understand application behavior patterns
  • Look for unexpected state distributions
  • Monitor state durations to identify performance issues
  • Use state filtering to focus on specific types of activity

The GoRoutines Viewer provides deep insight into your application's concurrent behavior, making it easier to understand, debug, and optimize your Go programs' goroutine usage.