go_tracing.cli.txt

                                  ┏━━━━━━━━━━━━━━━━┓
                                  ┃   GO_TRACING   ┃
                                  ┗━━━━━━━━━━━━━━━━┛

VERSION ==>                       #See Go language
RELATED DOCUMENTATION ==>         #See Go language

                                  ┌─────────────┐
                                  │   GENERAL   │
                                  └─────────────┘

TRACING ==>                       #Similar to profiling, but instead:
                                  #  - records everything instead of sampling
                                  #  - records over time, i.e. can see as time series graph
                                  #  - especially good to debug latency|wait issues

CORE INFORMATION ==>              #Records information over time:
                                  #  - includes:
                                  #     - heap memory used
                                  #     - number of goroutines|threads running|waiting
                                  #     - syscalls
                                  #     - GC
                                  #  - can be per CPU ("process")
                                  #  - ns-precise
                                  #Also records total waits:
                                  #  - includes:
                                  #     - network|mutex|syscall|scheduler waits
                                  #     - GC sweeps|pauses
                                  #  - can be per goroutine
                                  #  - can be as graph showing non-wait time (minimum mutator utilization)

USER-DEFINED INFORMATION ==>      #Can group into programmatical user-defined:
                                  #  - tasks: group functions|goroutines together. Can be nested.
                                  #  - regions: time interval within a specific goroutine. Can be nested.
                                  #  - logs: message|metadata at a specific point in time

                                  ┌─────────┐
                                  │   CLI   │
                                  └─────────┘

go test -trace=TRACE_FILE         #Write TRACE_FILE
go tool compile
 -traceprofile=TRACE_FILE         #Same

                                  ┌──────────────────┐
                                  │   PROGRAMMATIC   │
                                  └──────────────────┘

import "runtime/trace"
trace.Start(WRITER)[->ERROR]
trace.Stop()                      #Same but programmatic
runtime.StartTrace()[->ERROR]
runtime.StopTrace()
runtime.ReadTrace()->[]BYTE       #Low-level API for trace.Start|Stop()

trace.IsEnabled()->BOOL           #

trace.NewTask(CONTEXT, STR)       #Start a user-defined task
 ->CONTEXT2,TASK                  #CONTEXT2 must be passed to other trace.*(CONTEXT, ...) (which should otherwise use nil)
                                  #STR is custom name
TASK.End()                        #

trace.StartRegion(CONTEXT, STR)
 ->*REGION
REGION.End()                      #Same but for a user-defined region
trace.WithRegion
 (CONTEXT, STR, FUNC())           #Call StartRegion() then FUNC() then REGION.End()

trace.Log
 (CONTEXT, 'CATEGORY', 'MESSAGE') #Adds a user-defined trace log
trace.Logf(CONTEXT, 'CATEGORY',
 'MESSAGE', VAL...)               #Same but using fmt.Sprintf()

                                  ┌────────────┐
                                  │   REPORT   │
                                  └────────────┘

go tool trace [BIN] TRACE_FILE    #Visualize trace file in browser
                                  #  - Chromium is better at visualizing the main dynamic graph
                                  #BIN: like go tool pprof
-http=HOST:PORT                   #
-d                                #Verbose mode
-pprof=TYPE                       #Output in a format to visualize with go tool pprof
                                  #TYPE can be net|sync|syscall|scheduler for network|mutex|syscall|scheduler waits