what

README

What: debug-level logging that vanishes from production code

How to import the package

import "appliedgo.net/what"

(Do not use the direct path to the repo.)

What does what do

what is a set of simple and easy logging functions, suitable for tracing any kind of activities in your code. what can print the current function name, quickly Printf-format your data, and dumps data structures.

And last not least, no what calls reach your production binary (unless you want it so). Debug-level logging is for developers only.

Who need this?

You definitely should give what a closer look if you -

• heartily agree to Dave Cheney's article about logging, or
• want to keep your production code free from any log or trace output. (Think security!)

How does it work?

First of all, what is intended for debug-level logging only. So,

• Use what for tracing and debugging your code. ("Does my code do what I intended? Does this variable contain what I expect? Why does the loop not stop when the break condition should be fulfilled?...")
• Use log for user-facing log output. ("What was the app doing before it said, 'cannot connect to server'? Did that service already sync or is it still waiting for other services?...")

You have to explicitly enable what logging through build flags (see below).

Available functions

what.Happens("Foo: %s", bar) // log.Printf("Foo: %s\n", bar)
what.If(cond, "Foo: %s", bar) // only print if cond is true
what.Func() // Print out the fully qualified function name
what.Is(var) // dump the structure and contents of var 

Spread these calls across your code, especially in places you want to observe closer.

Debug-level logging is useful alongside unit testing as well as using a debugger. It does not attempt to replace any of these concepts.

Enabling and disabling

Enable all functions

Simply pass the what tag to go build, go install, go test etc:

go build -tags what

And now just lean back and see your code talking about what it does.

Enable specific functions

To reduce the noise, you can decide to compile only specific parts of what:

• whathappens only enables what.Happens() and what.If().
• whatfunc only enables what.Func().
• whatis only enables what.Is().

All disabled functions get replaced by no-ops.

Example:

go build -tags whathappens

You can also choose a combination of the above, for example: go build -tags whathappens,whatis

Enable debug logging for specific packages only

Go's build tag mechanism cannot help here, so this is done through an environment variable called "WHAT".

To enable specific packages for debug logging, set WHAT to a package name, or a list of package names.

Disable what

Nothing easier than that! Without any of the above build tags, all funtions get replace by no-ops, ready for being optimized away entirely (if the compiler decides to do so).

• No log output
• No bloated binary
• No security leak from chatty binaries.

Non-features

• Uses only stdlib log, no custom logger configurable
• No custom variable dumper/pretty-printer. At the moment, what uses github.com/davecgh/go-spew. See Spew's docs about the syntax used for printing a variable.

Restrictions

Although go run should recognize all build flags that go build recognizes (including -tags), it seems that go run main.go -tags what does not consider the tag. Use go build -tags what && ./main instead.

Documentation

Overview

Package what provides a quick and convenient way of adding development-only log statements to your code.

Instead of firing up the debugger and stepping through each line one-by-one, spread a few what calls across the code you want to inspect, then run the code and watch the output.

Log output from what must be enabled through build tags. This ensures that your debug logging does not leak into production code and involuntarily exposes sensitive data to prying eyes. Use the log package for generating user-facing log output from production code.

Enable what by passing "what" as a build tag:

go build -tags what

Enable only parts of what by passing the respective build tag: whathappens, whatis, whatfunc, or whatpackage. (Good for reducing noise, e.g by muting what.Func().)

Functions that are not enabled by a build tag become no-ops.

Enable what for particular packages only by setting the environment variable WHAT to a package name or a comma-separated list of package names:

export WHAT=pkg1,pkg2

(Also good for reducing noise.)

Index

• func Func()
• func Happens(fmt string, args ...interface{})
• func If(yes bool, fmt string, args ...interface{})
• func Is(v interface{})
• func Package()

Functions

func Func

func Func()

Func logs the current function name, line number, and file name. Useful for tracing function calls

func Happens

func Happens(fmt string, args ...interface{})

Happens logs the current function name and whatever message is passed in.

func If

func If(yes bool, fmt string, args ...interface{})

If works like Happens but only if yes is true.

func Is

func Is(v interface{})

Is pretty-prints data.

func Package

func Package()

Package prints the code's package name, including the parent path entry if any.