hopwatch

README

Hopwatch, a debugging tool for Go

Hopwatch is a simple tool in HTML5 that can help debug Go programs. It works by communicating to a WebSockets based client in Javascript. When your program calls the Break function, it sends debug information to the browser page and waits for user interaction. Using the functions Display, Printf or Dump (go-spew), you can log information on the browser page. On the hopwatch page, the developer can view debug information and choose to resume the execution of the program.

First announcement

Distributed (work in progress)

Hopwatch can be used in a distributed services architecture to hop and trace between services following an incoming request to downstream service.

Consider the setup where the browser is sending a HTTP request to a GraphQL endpoint which calls a gRPC backend service, which calls a PostgreSQL Database server to perform a query. The result of that query needs to be transformed into a gRPC response which in turn needs to be transformed into a GraphQL response before transporting it back to the browser.

We want to jump from client to server to server and back, for a given request. To signal the upstream services that it should break on this request, the request must be annotated using a special HTTP header x-hopwatch : your-correlation-name.

Each upstream server must have the hopwatch agent package included:

import _ "github.com/emicklei/hopwatch/agent"

© 2012-2022, http://ernestmicklei.com. MIT License

Documentation

Overview

Hopwatch is a debugging tool for Go programs.

Hopwatch uses a (embedded) HTML5 application to connect to your program (using a Websocket). Using Hopwatch requires adding function calls at points of interest that allow you to watch program state and suspend the program. On the Hopwatch page, you can view debug information (file:line,stack) and choose to resume the execution of your program.

You can provide more debug information using the Display and Dump functions which take an arbitrary number of variables. The Display and Dump functions do not suspend the program ; it is like having logging information in the browser.

Usage:

import (
	// use a tag
	"gopkg.in/emicklei/hopwatch.v1"

	// or use the master
	// "github.com/emicklei/hopwatch"
)

func foo() {
	bar := "john"
	// suspends execution until hitting "Resume" in the browser
	hopwatch.Display("foo", bar).Break()
}

Connect:

The Hopwatch debugger is automatically started on http://localhost:23456/hopwatch.html.
Your browser must support WebSockets. It has been tested with Chrome and Safari on a Mac.

Other code examples:

// zero or more conditions ; conditionally suspends program (or goroutine)
hopwatch.Break(i > 10,  j < 100)

// zero or more name,value pairs ; no program suspend
hopwatch.Display("i",i , "j",j")

// print any formatted string ; no program suspend
hopwatch.Printf("result=%v", result)

// display detailed (type, nesting) information using https://github.com/davecgh/go-spew
hopwatch.Dump(myVar1)

// format and display detailed (type, nesting) information using https://github.com/davecgh/go-spew
hopwatch.Dumpf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)

Flags:

-hopwatch	if set to false then hopwatch is disabled.
-hopwatch.open	if set to false then hopwatch will not try to open the debugger page on startup.
-hopwatch.break	if set to false then hopwatch will not suspend the program when Break(..) is called.
-hopwatch.host	tcp hostname of the listener address (default = localhost).
-hopwatch.port	tcp port of the listener address (default = 23456).

Install from master:

go get -u github.com/emicklei/hopwatch

Resources:

https://github.com/emicklei/hopwatch (project)
http://ernestmicklei.com/2012/12/14/hopwatch-a-debugging-tool-for-go/  (blog)

(c) 2012-2022+, Ernest Micklei. MIT License

Index

• func Break(conditions ...bool)
• func Disable()
• func Enable()
• type Watchpoint
  • func CallerOffset(offset int) *Watchpoint
  • func Display(nameValuePairs ...interface{}) *Watchpoint
  • func Dump(a ...interface{}) *Watchpoint
  • func Dumpf(format string, a ...interface{}) *Watchpoint
  • func Printf(format string, params ...interface{}) *Watchpoint
  • func (w Watchpoint) Break(conditions ...bool)
  • func (w *Watchpoint) CallerOffset(offset int) *Watchpoint
  • func (w *Watchpoint) Display(nameValuePairs ...interface{}) *Watchpoint
  • func (w *Watchpoint) Dump(a ...interface{}) *Watchpoint
  • func (w *Watchpoint) Dumpf(format string, a ...interface{}) *Watchpoint
  • func (w *Watchpoint) Printf(format string, params ...interface{}) *Watchpoint

Functions

func Break

func Break(conditions ...bool)

Break suspends the execution of the program and waits for an instruction from the debugger (e.g. Resume). Break is only effective if all (if any) conditions are true. The program will resume otherwise.

func Disable

func Disable()

func Enable

func Enable()

Types

type Watchpoint

type Watchpoint struct {
	// contains filtered or unexported fields
}

watchpoint is a helper to provide a fluent style api. This allows for statements like hopwatch.Display("var",value).Break()

func CallerOffset

func CallerOffset(offset int) *Watchpoint

CallerOffset (default=2) allows you to change the file indicator in hopwatch. Use this method when you wrap the .CallerOffset(..).Display(..).Break() in your own function.

func Display

func Display(nameValuePairs ...interface{}) *Watchpoint

Display sends variable name,value pairs to the debugger. The parameter nameValuePairs must be even sized.

func Dump

func Dump(a ...interface{}) *Watchpoint

Dump displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fdump, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func Dumpf

func Dumpf(format string, a ...interface{}) *Watchpoint

Dumpf formats and displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. delegates to spew.Fprintf, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func Printf

func Printf(format string, params ...interface{}) *Watchpoint

Printf formats according to a format specifier and writes to the debugger screen. It returns a new Watchpoint to send more or break.

func (Watchpoint) Break

func (w Watchpoint) Break(conditions ...bool)

Break halts the execution of the program and waits for an instruction from the debugger (e.g. Resume). Break is only effective if all (if any) conditions are true. The program will resume otherwise.

func (*Watchpoint) CallerOffset

func (w *Watchpoint) CallerOffset(offset int) *Watchpoint

CallerOffset (default=2) allows you to change the file indicator in hopwatch.

func (*Watchpoint) Display

func (w *Watchpoint) Display(nameValuePairs ...interface{}) *Watchpoint

Display sends variable name,value pairs to the debugger. Values are formatted using %#v. The parameter nameValuePairs must be even sized.

func (*Watchpoint) Dump

func (w *Watchpoint) Dump(a ...interface{}) *Watchpoint

Dump displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fdump, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func (*Watchpoint) Dumpf

func (w *Watchpoint) Dumpf(format string, a ...interface{}) *Watchpoint

Dumpf formats and displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fprintf, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func (*Watchpoint) Printf

func (w *Watchpoint) Printf(format string, params ...interface{}) *Watchpoint

Printf formats according to a format specifier and writes to the debugger screen.