go-debugger

Go debugging utilities.

Features

• Dump objects. On/off dumping with tag -tags dump.
• Dump errors. On/off dumping with tag -tags dumperr.
• Output destination can be cahnged to stdout, stderr, discard and files.
  • Object dumps with environmental variable GO_DEBUGGER_DUMP_OUTPUT.
  • Error dumps with environemtnal variable GO_DEBUGGER_DUMP_OUTPUT.
• Easy stack frames manipulation.

Usages

Object dumps

2 Options to output object dumps. The function Dump works with build tag so it can work only when debugging.

• Dump and DumpTo works with build tag -tags dump.
• DumpAlways and DumpAlwaysTo works without any build tag.

By default, Dump and DumpAlways output dumps to stdout. It can be changed by the environment variable GO_DEBUGGER_DUMP_OUTPUT. GO_DEBUGGER_DUMP_OUTPUT can take one of these values.

• stdout: standard output
• stderr: standard error output
• file: file output (files created in system's temp directory)
• discard: discard all output

val := struct {
    foo int
    bar string
}{
    foo: 123,
    bar: "bar",
}

debugger.Dump("this is an example.", val)

// Example output:
// 
// 2026-08-01 11:38:47 [DUMP] this is an example.
//   | Caller: Pkg:github.com/aileron-projects/go-debugger_test File:example_test.go Func:Example Line:42
//   | ┌── args[0]
//   | (struct { foo int; bar string }) {
//   |  foo: (int) 123,
//   |  bar: (string) (len=3) "bar"
//   | }

Error dumps

Error dumps works just like object dumps. Use following function for error dumps.

• DumpErr and DumpErrTo works with build tag -tags dumperr.
• DumpErrAlways and DumpErrAlwaysTo works without any build tag.

And use GO_DEBUGGER_DUMPERR_OUTPUT to change dump output destination.

debugger.DumpErr("this is an example.", io.EOF)

// Example output:
// 
// 2026-08-01 11:49:40 [DEBUGGER][DUMPERR] this is an example.
//   | Caller: Pkg:github.com/aileron-projects/go-debugger_test File:example_test.go Func:Example Line:36
//   | ┌── Error: EOF
//   | (*errors.errorString)(EOF)
//   | ┌── Stack Trace:
//   | goroutine 1 [running]:
//   | github.com/aileron-projects/go-debugger.dumpErr({0x7ff6afbde608, 0x1615158b2058}, {0x7ff6afa4598e, 0x13}, {0x1615158d7a48, 0x1, 0x1615158c63f0?})
// ~~ stack trace omitted ~~~

Build Tags

• dump: enables object dump output to work.
• dumperr: enables error dump output to work.

Enviromental Variables

• GO_DEBUGGER_DUMP_OUTPUT: optionaly specifies object dump output destination. stdout, stderr, discard or file.
• GO_DEBUGGER_DUMP_PACKAGES: optionaly filters go packages to output object dumps.
• GO_DEBUGGER_DUMPERR_OUTPUT: optionaly specifies error dump output destination. stdout, stderr, discard or file.
• GO_DEBUGGER_DUMPERR_PACKAGES: optionaly filters go packages to output error dumps.

Docs & Examples

• GoDoc: https://pkg.go.dev/github.com/aileron-projects/go-debugger
• Examples:
  • example_test.go
  • dump objects: examples/dump/
  • dump errors: examples/dump_err/

References