Advanced Configuration

The Quick Start guide uses the simple autoinit approach with default settings. For more control over Outrig's behavior, you can either create a config file (recommended) or manually initialize Outrig in your code. This is useful for suppressing output in production, changing the monitor port location, disabling specific SDK features, or conditionally initializing Outrig only in development environments.

Config File (outrig.json)

You can create an outrig.json file in your project root to configure Outrig without modifying your Go code. Simply place the file alongside your go.mod file, and Outrig will automatically find and use it.

Outrig starts with sensible defaults for all settings, so you only need to specify the options you want to change from the defaults.

Example outrig.json

Here's a minimal config that just enables quiet mode and sets a custom app name:

{
  "quiet": true,
  "appname": "my-application"
}

Or disable specific collectors:

{
  "collectors": {
    "logs": {
      "enabled": false
    },
    "runtimestats": {
      "enabled": false
    }
  }
}

Advanced Config File Options

For more complex scenarios, you can:

• Use the OUTRIG_CONFIGFILE environment variable to specify a custom config file path
• Outrig will automatically search up the directory tree, stopping at project boundaries (.git or go.mod files)

export OUTRIG_CONFIGFILE="/path/to/custom-outrig.json"

Manual Initialization

Instead of using the autoinit import, you can manually configure and initialize the Outrig Golang SDK:

import "github.com/outrigdev/outrig"

func main() {
    cfg := outrig.DefaultConfig()
    outrig.Init("your-app-name", cfg)
    // rest of your code
}

Configuration Options

The Config struct provides several options to customize Outrig's behavior. For the complete API reference, see the Go documentation.

Basic Configuration

type Config struct {
	Quiet bool `json:"quiet"` // If true, suppresses init, connect, and disconnect messages

	// AppName is the name of the application
	AppName string `json:"appname"`

	// DomainSocketPath is the path to the Unix domain socket. If "" => use default.
	// If "-" => disable domain socket.
	DomainSocketPath string `json:"domainsocketpath"`

	// TcpAddr is the TCP address to connect to the Outrig server.  If "" => use default.
	// If "-" => disable TCP connection. Domain socket will be tried first (except on Windows where domain sockets are not supported).)
	TcpAddr string `json:"tcpaddr"`

	// By default the SDK will probe host.docker.internal:5005 to see if the Outrig monitor is running on the host machine
	// We do an initial DNS lookup at startup and only try this host/port if the DNS lookup succeeds.
	// Setting this to true will disable the initial probe.
	DisableDockerProbe bool `json:"disabledockerprobe"`

	// ModuleName is the name of the Go module. If not specified, it will be determined
	// from the go.mod file.
	ModuleName string `json:"modulename"`

	// If true, try to synchronously connect to the server on Init
	ConnectOnInit bool `json:"connectoninit"`

	// Collector configurations
	Collectors CollectorConfig `json:"collectors"`

	// RunMode configuration
	RunMode RunModeConfig `json:"runmode,omitempty"`
}

Collector Configuration

The Collectors field in the main config uses the CollectorConfig struct to organize all monitoring features:

type CollectorConfig struct {
	Logs         LogProcessorConfig `json:"logs"`
	RuntimeStats RuntimeStatsConfig `json:"runtimestats"`
	Watch        WatchConfig        `json:"watch"`
	Goroutine    GoRoutineConfig    `json:"goroutine"`

	Plugins map[string]any `json:"-"`
}

Log Processor Configuration

Control how Outrig captures and processes logs from your application:

type LogProcessorConfig struct {
	// Enabled indicates whether the log processor is enabled
	Enabled    bool `json:"enabled"`
	WrapStdout bool `json:"wrapstdout"`
	WrapStderr bool `json:"wrapstderr"`
	// OutrigPath is the full path to the outrig executable (including the executable name)
	// If empty, the system will look for "outrig" in the PATH
	OutrigPath string `json:"outrigpath"`
	// AdditionalArgs are additional arguments to pass to the outrig command
	// These are inserted before the "capturelogs" argument
	AdditionalArgs []string `json:"additionalargs"`
}

Watch Configuration

Configure the variable watching functionality:

type WatchConfig struct {
	// Enabled indicates whether the watch collector is enabled
	Enabled bool `json:"enabled"`
}

GoRoutine Configuration

Control goroutine monitoring:

type GoRoutineConfig struct {
	// Enabled indicates whether the goroutine collector is enabled
	Enabled bool `json:"enabled"`
}

Runtime Stats Configuration

Configure runtime statistics collection:

type RuntimeStatsConfig struct {
	// Enabled indicates whether the runtime stats collector is enabled
	Enabled bool `json:"enabled"`
}

RunMode Configuration

Run mode refers to options that apply when running outrig run. So they are applied at build time.

type RunModeConfig struct {
	// SDKReplacePath specifies an absolute path to replace the outrig SDK import.
	// This must be an absolute path to a local outrig SDK directory.
	SDKReplacePath string `json:"sdkreplacepath,omitempty"`

	// TransformPkgs specifies a list of additional package patterns to transform
	TransformPkgs []string `json:"transformpkgs,omitempty"`
}

Example Configurations

Development Mode Only

Only initialize Outrig when your own application is running in development mode:

func main() {
    // Only enable Outrig when YOUR application is in development mode
	// change this condition to match how you determine development mode
    if os.Getenv("ENV") == "development" {
        cfg := outrig.DefaultConfig()
        cfg.ConnectOnInit = true
        cfg.Quiet = false
        outrig.Init("my-app", cfg)
    }
    
    // your application code
}

Remote Connection

Connect to Outrig running on a remote machine:

func main() {
    cfg := outrig.DefaultConfig()
    cfg.TcpAddr = "192.168.1.100:5005"  // Remote Outrig server
    cfg.DomainSocketPath = "-"          // Disable local socket
    
    outrig.Init("my-app", cfg)
    // your application code
}

Environment Variables

Outrig supports several environment variables that can override configuration settings (this can be useful in production or containerized environments):

OUTRIG_DISABLED

Completely disables Outrig initialization when set to any non-empty value (can be useful in environments where you want to disable monitoring without changing code).

export OUTRIG_DISABLED="1"

OUTRIG_DOMAINSOCKET

Sets an override domain socket path. Use - to disable domain socket connections.

export OUTRIG_DOMAINSOCKET="/custom/path/outrig.sock"
# or disable domain socket
export OUTRIG_DOMAINSOCKET="-"

OUTRIG_TCPADDR

Sets an override TCP address for connecting to the Outrig server. Use - to disable TCP connections.

export OUTRIG_TCPADDR="192.168.1.100:5005"
# or disable TCP
export OUTRIG_TCPADDR="-"

OUTRIG_DISABLEDOCKERPROBE

Disables the automatic probe for host.docker.internal:5005 when running in Docker environments. See Using Docker for more details.

export OUTRIG_DISABLEDOCKERPROBE="1"