luci-go: github.com/luci/luci-go/common/runtime/tracer Index | Examples | Files

package tracer

import "github.com/luci/luci-go/common/runtime/tracer"

Package tracer implements code to generate Chrome-compatible traces.

Since there is no thread id concept in Go, pseudo process id and pseudo thread id are used. These are defined at application level relative to the application-specific context.

See https://github.com/google/trace-viewer for more information.

Index

Examples

Package Files

doc.go tracer.go tracer_posix.go

func CounterAdd Uses

❖
func CounterAdd(marker interface{}, name string, value float64)

CounterAdd increments a value for a counter.

The values will be grouped inside the PID and each name displayed as a separate line.

func CounterSet Uses

❖
func CounterSet(marker interface{}, name string, value float64)

CounterSet registers a new value for a counter.

The values will be grouped inside the PID and each name displayed as a separate line.

func Discard Uses

❖
func Discard(marker interface{})

Discard forgets a context association created with NewPID.

If not called, contexts accumulates and form a memory leak.

func Instant Uses

❖
func Instant(marker interface{}, name string, s Scope, args Args)

Instant registers an intantaneous event that has no duration.

Example

Code: 

// Open a file with os.Create().
if err := Start(&bytes.Buffer{}, 0); err != nil {
    defer Stop()
}
Instant(nil, "explosion", Global, Args{"level": "hard"})

func NewPID Uses

❖
func NewPID(marker interface{}, pname string)

NewPID assigns a pseudo-process ID for this marker and TID 1.

Optionally assigns name to the 'process'. The main use is to create a logical group for events.

Example

Code: 

// Open a file with os.Create().
if err := Start(&bytes.Buffer{}, 0); err != nil {
    defer Stop()
}

// Logging to sub will use a different group in the UI.
key := new(int)
NewPID(key, "main")
Instant(key, "explosion", Process, Args{"level": "hard"})

func Span Uses

❖
func Span(marker interface{}, name string, args Args) func(args Args)

Span defines an event with a duration.

The caller MUST call the returned callback to 'close' the event. The callback doesn't need to be called from the same goroutine as the initial caller.

Example

Code: 

// Open a file with os.Create().
if err := Start(&bytes.Buffer{}, 0); err != nil {
    defer Stop()
}

// Do stuff.
var err error

end := Span(nil, "action1", Args{"foo": "bar"})
defer func() { end(Args{"err": err}) }()

func Start Uses

❖
func Start(w io.Writer, stackDepth int) error

Start starts the trace.

There can be only one trace at a time. If a trace was already started, the current trace will not be affected and an error will be returned.

Initial context has pid 1 and tid 1. Stop() must be called on exit to generate a valid JSON trace file.

If stackDepth is non-zero, up to 'stackDepth' PC entries are kept for each log entry.

Tracing events before this call are ignored.

TODO(maruel): Implement stackDepth.

func Stop Uses

❖
func Stop()

Stop stops the trace.

It is important to call it so the trace file is properly formatted. Tracing events after this call are ignored.

type Args Uses

❖
type Args map[string]interface{}

Args is user-defined arguments for an event. It can be anything as long as it is JSON serializable.

type Scope Uses

❖
type Scope string

Scope is used with Instant event to determine the scope of the instantaneous event.

❖
const (
    Global  Scope = "g"
    Process Scope = "p"
    Thread  Scope = "t"
)

Possible scopes that can be passed to Instant.

Package tracer imports 8 packages (graph) and is imported by 4 packages. Updated 2019-07-28. Refresh now. Tools for package owners.