pdebug

README

go-pdebug

Utilities for my print debugging fun. YMMV

WARNING

This repository has been moved to github.com/lestrrat-go/pdebug. This repository exists so that libraries pointing to this URL will keep functioning, but this repository will NOT be updated in the future. Please use the new import path.

Synopsis

Description

Building with pdebug declares a constant, pdebug.Enabled which you can use to easily compile in/out depending on the presence of a build tag.

func Foo() {
  // will only be available if you compile with `-tags debug`
  if pdebug.Enabled {
    pdebug.Printf("Starting Foo()!
  }
}

Note that using github.com/lestrrat/go-pdebug and -tags debug only compiles in the code. In order to actually show the debug trace, you need to specify an environment variable:

# For example, to show debug code during testing:
PDEBUG_TRACE=1 go test -tags debug

If you want to forcefully show the trace (which is handy when you're debugging/testing), you can use the debug0 tag instead:

go test -tags debug0

Markers

When you want to print debug a chain of function calls, you can use the Marker functions:

func Foo() {
  if pdebug.Enabled {
    g := pdebug.Marker("Foo")
    defer g.End()
  }

  pdebug.Printf("Inside Foo()!")
}

This will cause all of the Printf calls to automatically indent the output so it's visually easier to see where a certain trace log is being generated.

By default it will print something like:

|DEBUG| START Foo
|DEBUG|   Inside Foo()!
|DEBUG| END Foo (1.23μs)

If you want to automatically show the error value you are returning (but only if there is an error), you can use the BindError method:

func Foo() (err error) {
  if pdebug.Enabled {
    g := pdebug.Marker("Foo").BindError(&err)
    defer g.End()
  }

  pdebug.Printf("Inside Foo()!")

  return errors.New("boo")
}

This will print something like:

|DEBUG| START Foo
|DEBUG|   Inside Foo()!
|DEBUG| END Foo (1.23μs): ERROR boo

Documentation

Overview

Package pdebug provides tools to produce debug logs the way the author (Daisuke Maki a.k.a. lestrrat) likes. All of the functions are no-ops unless you compile with the `-tags debug` option.

When you compile your program with `-tags debug`, no trace is displayed, but the code enclosed within `if pdebug.Enabled { ... }` is compiled in. To show the debug trace, set the PDEBUG_TRACE environment variable to true (or 1, or whatever `strconv.ParseBool` parses to true)

If you want to show the debug trace regardless of an environment variable, for example, perhaps while you are debugging or running tests, use the `-tags debug0` build tag instead. This will enable the debug trace forcefully

Index

• Constants
• Variables
• func Dump(v ...interface{})
• func IPrintf(f string, args ...interface{}) guard
• func Marker(f string, args ...interface{}) *markerg
• func Printf(f string, args ...interface{})

Constants

const Enabled = false

Enabled is true if `-tags debug` or `-tags debug0` is used during compilation. Use this to "ifdef-out" debug blocks.

const Trace = false

Trace is true if `-tags debug` is used AND the environment variable `PDEBUG_TRACE` is set to a `true` value (i.e., 1, true, etc), or `-tags debug0` is used. This allows you to compile-in the trace logs, but only show them when you set the environment variable

Variables

var DefaultCtx = &pdctx{
	LogTime: true,
	Prefix:  "|DEBUG| ",
	Writer:  os.Stdout,
}

Functions

func Dump

func Dump(v ...interface{})

Dump dumps the objects using go-spew. Dump is a no op unless you compile with the `debug` tag.

func IPrintf

func IPrintf(f string, args ...interface{}) guard

IPrintf is deprecated. Use Marker()/End() instead

func Marker

func Marker(f string, args ...interface{}) *markerg

Marker marks the beginning of an indented block. The message you specify in the arguments is prefixed witha "START", and subsequent calls to Printf will be indented one level more.

To reset this, you must call End() on the guard object that gets returned by Marker().

func Printf

func Printf(f string, args ...interface{})

Printf prints to standard out, just like a normal fmt.Printf, but respects the indentation level set by IPrintf/IRelease. Printf is no op unless you compile with the `debug` tag.