Skip to content

Draft: xgo trace: a powerful visualization tool

Jump to bottom
xhd2015 edited this page Apr 21, 2024 · 2 revisions

Draft

Table of content:

  • the problem
  • the solution
  • a practical example

Two use cases:

  • read code from zero
  • debug unit test faster it actually make write unit test faster by inspecting actual values of specific interest point, without debugging.

useful when stack trace goes deeper.

However it seems debug unit test faster is not a claim.

Overview

Xgo has a set of tools to help go developers write unit test faster and easier.

In case you don't know, the xgo project is at https://github.com/xhd2015/xgo.

These tools include:

  • Trace
  • Mock
  • Trap

This blog introduces the Trace tool.

image image

image

About the Trace

The trace in xgo can be used visualize execution of go program.

In some cases, this can replace a debugger, reducing the cost to find a bug.

The problem

When starting with a new strange project, we cannot quickly get a picture of what the whole program will do.

It's hard break down the program by running some tests and observe the results.

Fortunately, this will never be the case in xgo -- xgo brings a trace utility to address this issue.

To demonstrate how trace helps us understand code quickly, I'll start with a random project that I saw in a post asked by a reddit user the other day(https://www.reddit.com/r/golang/s/RpEtEApIUj).

Clone the repo and run some tests

The project I choose is: https://github.com/pocketbase/pocketbase.

First, clone it

git clone [email protected]:pocketbase/pocketbase.git
cd pocketbase

Then I choose a top level test to run: apis/backup_test.go

go test -v -run TestBackupsList ./apis

Output:

$ go test -v -run TestBackupsList ./apis
=== RUN   TestBackupsList
=== PAUSE TestBackupsList
=== CONT  TestBackupsList
=== RUN   TestBackupsList/unauthorized
=== RUN   TestBackupsList/authorized_as_auth_record
=== RUN   TestBackupsList/authorized_as_admin_(empty_list)
=== RUN   TestBackupsList/authorized_as_admin
--- PASS: TestBackupsList (0.51s)
    --- PASS: TestBackupsList/unauthorized (0.17s)
    --- PASS: TestBackupsList/authorized_as_auth_record (0.14s)
    --- PASS: TestBackupsList/authorized_as_admin_(empty_list) (0.04s)
    --- PASS: TestBackupsList/authorized_as_admin (0.15s)
PASS
ok      github.com/pocketbase/pocketbase/apis

Focusing on the sub test

As we can, there are four sub cases running. And let's focus on the sub test TestBackupsList/x

First attempt to use trace

In the simplest form, xgo trace can be used with the following minimal setup:

Add a blank import in the back_test.go:

package ...

import (
   ...
   _ "github.com/xhd2015/xgo/runtime/trace"
)
...

This does nothing if you do not run the test with xgo.

Then, to get the trace, we update the dependency:

go get github.com/xhd2015/xgo/runtime/trace

And done, we can now run the test and get the output trace:

# ensure xgo is installed
go install github.com/xhd2015/xgo/cmd/xgo@latest

# run with --strace flag, which will generate stack trace
xgo test -v -run TestBackupsList --strace ./apis

I ran one all it's API test:

git clone [email protected]:pocketbase/pocketbase.git
cd pocketbase

go get github.com/xhd2015/xgo/runtime/trace

# add import _ "github.com/xhd2015/xgo/runtime/trace"

xgo test --strace -run TestBackupsList ./apis

# open the trace
xgo tool trace apis/TestBackupsList/authorized_as_auth_record.json

Of course this trace is deep, and for someone who have no ideas what this project does, it is merely useful.

image

But as soon as you get started to dive deep, you'll find this trace helpful, and it can reduce your time just to debug the program.

So let's get started with the help of trace.

Compare with traditional stack trace

The usual stack trace generated by the runtime is a snapshot of the program when trace is generated, thus it's missing full footprints of the program.

Besides, the stack trace generated by by runtime does not resolve values deeply. Only hex encoded values are shown.

comment: steps:

  • clone the repo
  • run a backup test
  • check the trace, find some error
  • now know where the error is
  • try to fix it: ctx.Set(, model.Amdin{})
  • still gets the error
  • check back, now get ctx.Get(. &model.Admin{})
  • check the trace again, the error gone,
  • now the tests fails, we know what exactly it is doing

Here comes the xgo trace

Once we have a basic understanding of it, we can try to .

A quick glance

(A screen record)

Live demo

(A live website)

How it is implemented?

A practical example

(Use kubernetes as an example)

A collection of projects that can be used to demonstrate:

Summary

With xgo trace utility, you can

Debugger is usually less needed, thus, xgo with trace, the killer of debugger.

----- backups -----

The problem (for reading code)

There are two cases when we are facing new project.

Take the X project for example, when first encounter its code, we have no idea what the whole thing is.

Reading doc and code is a traditional way to get some knowledge of the project. But it takes time to dive deep.

Clone this wiki locally