detrix

Detrix Go Client

Go client library for Detrix debug-on-demand observability.

Installation

go get github.com/flashus/detrix/clients/go

Prerequisites:

• Go 1.21+
• Delve debugger (dlv) installed and in PATH

Install Delve:

go install github.com/go-delve/delve/cmd/dlv@latest

Quick Start

package main

import (
    "log"
    detrix "github.com/flashus/detrix/clients/go"
)

func main() {
    // Initialize client (starts control plane, stays SLEEPING)
    err := detrix.Init(detrix.Config{
        Name:      "my-service",
        DaemonURL: "http://127.0.0.1:8090",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer detrix.Shutdown()

    // Your application code...
    runApp()
}

Try It

Run the end-to-end example that simulates an AI agent: starts a sample app, wakes it, adds metrics, and captures events.

# 1. Start the Detrix server
detrix serve --daemon

# 2. Build the Go fixture app (from clients/go/)
cd ../../fixtures/go && go build -gcflags="all=-N -l" -o detrix_example_app . && cd ../../clients/go

# 3. Run the agent simulation
go run ./examples/test_wake --daemon-port 8090

Other examples in examples/:

API

Init(cfg Config) error

Initialize the Detrix client. Starts the control plane HTTP server in SLEEPING state.

detrix.Init(detrix.Config{
    Name:        "my-service",           // Connection name (default: "detrix-client-{pid}")
    DaemonURL:   "http://127.0.0.1:8090", // Daemon URL
    ControlHost: "127.0.0.1",             // Control plane host
    ControlPort: 0,                       // Control plane port (0 = auto)
    DebugPort:   0,                       // Debug adapter port (0 = auto)
})

Wake() (WakeResponse, error)

Start the debugger and register with the daemon.

resp, err := detrix.Wake()
if err != nil {
    log.Printf("Wake failed: %v", err)
}
fmt.Printf("Debug port: %d\n", resp.DebugPort)

Sleep() (SleepResponse, error)

Stop the debugger and unregister from the daemon.

resp, err := detrix.Sleep()
// Delve process is fully stopped (unlike Python's debugpy)

Status() StatusResponse

Get the current client status.

status := detrix.Status()
fmt.Printf("State: %s, Port: %d\n", status.State, status.ControlPort)

Shutdown() error

Stop the client and clean up resources.

detrix.Shutdown()

Environment Variables

Build Information

The client automatically detects build metadata (commit SHA, version tag) from:

1. Explicit parameters (via Config.BuildCommit, Config.BuildTag)
2. Environment variables:
   • DETRIX_BUILD_COMMIT / DETRIX_BUILD_TAG (recommended for Docker)
   • GIT_COMMIT, CI_COMMIT_SHA, GITHUB_SHA (CI auto-detection)
   • GIT_TAG, CI_COMMIT_TAG, GITHUB_REF_NAME (tag detection)
3. Compile-time injection (via ldflags):

   go build -ldflags="-X github.com/flashus/detrix/clients/go.Version=1.0.0 \
     -X github.com/flashus/detrix/clients/go.BuildCommit=$(git rev-parse HEAD)"
   

4. Runtime git detection (local dev only, requires .git directory)

Docker Example

FROM golang:1.21 AS builder
ARG GIT_COMMIT=unknown
ARG GIT_TAG=unknown

ENV DETRIX_BUILD_COMMIT=${GIT_COMMIT}
ENV DETRIX_BUILD_TAG=${GIT_TAG}

# These will be captured at build time
RUN go build -ldflags="-X main.BuildCommit=${GIT_COMMIT}" ./cmd/myapp

Build with:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) \
             --build-arg GIT_TAG=$(git describe --tags) .

Control Plane API

The client exposes an HTTP control plane (same as Python client):

*Localhost requests bypass authentication

Architecture

Unlike Python's debugpy which runs in-process, Go uses Delve as a separate process:

┌─────────────────────────────────────┐
│  Go Application                     │
│  ┌─────────────────────────────────┐│
│  │ Detrix Client                   ││
│  │ - Control plane HTTP server     ││
│  │ - Delve process manager         ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘
        │ spawns & manages
        ↓
┌─────────────────────────────────────┐
│  Delve Process                      │
│  - Attaches via ptrace              │
│  - DAP server for Detrix daemon     │
└─────────────────────────────────────┘

Advantages over Python:

• Can fully stop debugger on Sleep() (Python's debugpy cannot stop its listener)
• Clean resource management
• Fresh debugger state on each Wake()

Expression Evaluation

Simple Variables (Recommended)

Go metrics use logpoints for fast, non-blocking evaluation:

// Simple variables - RECOMMENDED for production observability
addMetric(connID, file, 100, "symbol", "order_symbol", "go")
addMetric(connID, file, 101, "quantity", "order_qty", "go")
addMetric(connID, file, 102, "user.Name", "username", "go")
addMetric(connID, file, 103, "order.Price", "price", "go")

Characteristics:

• Non-blocking (no pause in execution)
• Minimal overhead
• Production-safe

Function Calls (Supported but Blocking)

Detrix supports Go function calls via Delve's call command, but with important caveats:

// Function calls - WORK but BLOCK the process
addMetric(connID, file, 111, `len(symbol)`, "symbol_len", "go")
addMetric(connID, file, 112, `user.GetBalance()`, "balance", "go")
addMetric(connID, file, 113, `calculatePnl(entry, current, qty)`, "pnl", "go")

How it works:

1. Detrix auto-detects function calls in expressions
2. Uses breakpoint mode (pauses execution)
3. Adds call prefix automatically for Delve DAP
4. Resumes execution after evaluation

Warnings:

• BLOCKS the target process while function executes
• Delve marks this as "highly EXPERIMENTAL"
• May cause issues with concurrent code
• Better for debugging than production observability

Critical limitation - Variadic functions NOT supported:

// ❌ DOES NOT WORK - variadic functions fail with error like:
// "Unable to evaluate expression: can not convert value of type string to []interface {}"
addMetric(connID, file, 111, `fmt.Sprintf("%s x%d", symbol, qty)`, ...)
addMetric(connID, file, 112, `fmt.Println(symbol)`, ...)  // variadic

// ✅ WORKS - non-variadic functions
addMetric(connID, file, 111, `len(symbol)`, ...)           // builtin
addMetric(connID, file, 112, `user.GetBalance()`, ...)     // method
addMetric(connID, file, 113, `math.Sqrt(value)`, ...)      // fixed arity

Delve's call command cannot handle variadic functions (... parameters). The error is returned in the event value for easy debugging. See Delve Issue #2261.

When to use function calls:

• Calling getters/methods that do simple calculations
• Built-in functions like len(), cap()
• User-defined functions with fixed parameter counts
• One-off debugging sessions

Preferred alternative: Capture variables separately and format in your agent:

// Non-blocking approach - RECOMMENDED
addMetric(connID, file, 111, "symbol", "order_symbol", "go")
addMetric(connID, file, 112, "quantity", "order_qty", "go")
// Format in your analysis tool instead

Mixing Metric Modes

Detrix supports mixing simple variables (logpoint mode) and function calls (breakpoint mode) in the same file, as long as they're on different lines:

// Line 111: Simple variable - uses logpoint mode (non-blocking)
addMetric(connID, file, 111, "symbol", "order_symbol", "go")

// Line 116: Function call - uses breakpoint mode (blocking)
addMetric(connID, file, 116, "len(symbol)", "symbol_len", "go")

// Both work together! Each is processed independently.

How it works:

1. When a metric is added, Detrix decides mode based on the expression:
   • Simple variable → logpoint (with logMessage)
   • Function call OR introspection → breakpoint (no logMessage)
2. ALL breakpoints for the file are sent in one setBreakpoints request
3. Logpoints capture via DAP output events (non-blocking)
4. Breakpoints capture via DAP stopped events (pauses briefly)

Important constraints:

• ⚠️ Only ONE metric per line (DAP limitation)
• Metrics on the same line: last one wins
• Function calls should be on different lines from simple variables

Introspection (Breakpoint Mode)

For stack traces and memory snapshots, Detrix uses breakpoint mode:

// With introspection - pauses briefly for data capture
addMetric(connID, file, 120, "pnl", "pnl_value", "go")
// + set captureStackTrace: true or captureMemorySnapshot: true

Technical Reference

• VSCode Go Issue #100 - Function call implementation
• Delve DAP docs - Debug console call syntax
• Delve Issue #2261 - Variadic function limitations

Platform Notes

Linux

May require ptrace permissions:

# Check current setting
cat /proc/sys/kernel/yama/ptrace_scope

# If value is 1 or higher, Delve spawned by the client can still attach
# because it's a child process. No changes needed.

macOS

May need to grant Developer Tools access in System Preferences → Security & Privacy.

Testing

cd clients/go
go test ./...

License

MIT