tracer

Documentation

Overview

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

• func CounterAdd(marker interface{}, name string, value float64)
• func CounterSet(marker interface{}, name string, value float64)
• func Discard(marker interface{})
• func Instant(marker interface{}, name string, s Scope, args Args)
• func NewPID(marker interface{}, pname string)
• func Span(marker interface{}, name string, args Args) func(args Args)
• func Start(w io.Writer, stackDepth int) error
• func Stop()
• type Args
• type Scope

Examples

• Instant
• NewPID
• Span

Functions

func CounterAdd

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

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

func Discard(marker interface{})

Discard forgets a context association created with NewPID.

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

func Instant

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

Instant registers an intantaneous event that has no duration.

Example

// 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

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

// 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

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

// 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

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

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.

Types

type Args

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

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.