Documentation

Getting Started with Outrig

Outrig is a debugging tool for Go programs, providing logs, goroutine monitoring, watches, and more, all with minimal setup.

How It Works

Outrig consists of two components:

SDK: A lightweight Go package that integrates into your application. It provides hooks for capturing logs, goroutine state, runtime metrics, and more.
Server: A local process running separately on your machine. It collects data from the SDK and presents it via a web UI.

Why Separate Components?

Minimal SDK footprint: Keeps your application lightweight—no embedded UI or unnecessary dependencies.
Persistent data storage: View and compare logs and metrics even after your app exits or across multiple runs.
Improved security: Your app doesn't expose any ports or require a built-in web server.
Optimized performance: The SDK remains dormant if the Outrig server isn't active, adding virtually zero overhead. For complete removal of SDK traces, Outrig supports build flags and environment variables to fully disable itself.

Installing the Outrig Server

Outrig is distributed as a single binary with no external dependencies and supports MacOS and Linux (x86_64 and ARM64).

MacOS

Install via Homebrew:

brew install outrigdev/outrig/outrig

Linux

Install directly without root privileges:

curl -sf https://outrig.run/install.sh | sh

This will install the Outrig server to ~/.local/bin.

Manual Downloads

Alternatively, you can download .deb, .rpm, or .tar.gz packages directly from our GitHub releases page.

Running the Outrig Server

To start the Outrig server, run the following command in your terminal:

outrig server

To stop the server, use Ctrl+C in the terminal where the server is running. Note that future versions include launchctrl/systemd support to run the server as a background service.

Adding the SDK

To add the Outrig SDK to your Go application, you need to import the github.com/outrigdev/outrig package. This package provides the necessary functions and types to interact with the Outrig server.

Here's a simple example of how to use the Outrig SDK in your Go application. This uses the default Outrig config which will enable log capture, goroutine monitoring, and runtime stats collection (e.g. memory usage, CPU usage, and basic application info).

package main

// Step 1: Import the Outrig package
import "github.com/outrigdev/outrig"

func main() {
    // Step 2: Initialize Outrig (set your application name)
    outrig.Init("app-name", nil)

    // Step 3: Optionally signal graceful shutdown
    defer outrig.AppDone()
    
    // Your application code here...
}

For advanced configuration and usage, see the Go Docs and Config Struct definition.

Adding watches

Watches enable real-time monitoring of values in your Go application. Outrig provides several methods for adding Watches. They are collected automatically every second (except for the TrackValue which is pushed).

Push Values

Push values directly from your code:

outrig.TrackValue("name", val)

Poll Values

Automatically poll values via a provided function:

outrig.WatchFunc("name", func() *ValueType { return value })

Thread-Safe Watching

Watch values with mutex protection:

outrig.WatchSync("name", &lock, val)

Atomic Values

Directly watch atomic values:

outrig.WatchAtomic("name", &atomicVal)

Searching

Outrig provides powerful, typeahead search capabilities that update results instantly as you type, enabling quick filtering of logs, watches, and goroutines.

Advanced Search Operators

Exact Match: Use double quotes for exact phrase matching or to search for special characters.
```
"timeout error"
```
Case-Sensitive Match: Use single quotes for case-sensitive matching.
```
'TimeoutError'
```
Fuzzy Search: Prefix a token with ~ for approximate matches.
```
~errror ~toc
```
Regular Expressions: Use / for regexp searches (use c/regexp/ for case-sensitive)
```
/timeout.*error/ c/CaSe SENsitive/
```
Exclude Results: Prefix any term (raw, quoted, fuzzy, regexp) with - to exclude entries.
```
-debug -"status: 200" -/[A-Z][0-9]+/
```
Tags: Search for tags (e.g., #bug, #feature) using #. Because Outrig is a type-ahead search it finds all tags that start with the provided tag. So #foo will match #foobar, #foo, and #foobarbaz. To force an exact match use #tag/ (with a trailing slash).
```
#foobar
```
Field-specific Searches: Target specific fields using $.
- Logs: msg, source, linenum
- Goroutines: goid, name, stack, state
- Watches: name, type, val
```
$source:main.go $goid:1234 $type:string
```
Grouping: Use parentheses () to group search terms.
```
(error | panic) -debug
```
Combined Searches: Combine searches using | (OR) and spaces (AND).
```
timeout | $source:db.go -debug
```

The search is designed with type-ahead semantics in mind. So, incomplete quotes, parentheses, and other operators will work.