trace2

Documentation

Index

• type Hook
• type Manager
  • func NewManager(sid string, hooks []Hook) (*Manager, error)
  • func (m *Manager) Error() error
  • func (m *Manager) Finish(ctx context.Context)
  • func (m *Manager) HookNames() []string
  • func (m *Manager) Inject(env []string) []string
• type Trace
  • func Parse(ctx context.Context, reader io.Reader) (*Trace, error)
  • func (trace *Trace) Inspect(detailed bool) string
  • func (trace *Trace) IsRoot() bool
  • func (trace *Trace) SetMetadata(key, value string)
  • func (trace *Trace) Walk(ctx context.Context, handler func(context.Context, *Trace) context.Context)

Types

type Hook

type Hook interface {
	// Name returns the name of the hook
	Name() string
	// Handle is handler function that a hook registers with the manager. After trace tree is
	// built, the manager dispatches handlers in order with the root trace of the tree.
	Handle(context.Context, *Trace) error
}

Hook is the interface for Trace2 hooks

type Manager

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

Manager is responsible for enabling Trace2 for a Git command. It manages the list of hooks who are interested in trace2 data. Before the command starts, the manager opens a tempfile. It injects the path to this file and some other conventional environment variables to the ENV list of the command by calling Inject. After the command exits, the caller is expected to call Finish. Finally, the transformed trace2 tree is passed into handlers of registered hooks.

func NewManager

func NewManager(sid string, hooks []Hook) (*Manager, error)

NewManager returns a Manager object that manages the registered hooks

func (*Manager) Error

func (m *Manager) Error() error

Error returns the error occurs after the manager finishes

func (*Manager) Finish

func (m *Manager) Finish(ctx context.Context)

Finish reads the events, parses them to a tree, triggers hook handlers, and clean up the fd.

func (*Manager) HookNames

func (m *Manager) HookNames() []string

HookNames return names of hooks

func (*Manager) Inject

func (m *Manager) Inject(env []string) []string

Inject injects the path to the tempfile used to store trace2 events and conventional environment variables to the input ENV list.

type Trace

type Trace struct {
	// Thread is the name of the thread of the corresponding event. The default thread name is
	// "main". A new thread is assigned with a new name.
	Thread string `json:"thread"`
	// Name denotes the name of the trace. The node name depends on the event types. Data-type
	// trace name is the most significant. It can be used to access the accurate data trace node
	// For example: data:index:refresh/sum_scan
	Name string `json:"name"`
	// StartTime is the starting time of the trace
	StartTime time.Time `json:"start_time"`
	// FinishTime is the finishing time of the trace
	FinishTime time.Time `json:"finish_time"`
	// Metadata is a map of metadata and data extracted from the event. A data-type trace always
	// stores its data under "data" key of this map
	Metadata map[string]string `json:"metadata"`
	// ChildID is the unique ID assigned by the parent process when it spawns a sub-process
	// The ID of root process is empty.
	ChildID string `json:"child_id,omitempty"`
	// Parent points to the parent node of the current trace. The root node's parent is nil.
	// Ignore this field when unmarshalling as it causes cyclic errors
	Parent *Trace `json:"-"`
	// Children stores the list of order-significant traces belong to the current trace
	Children []*Trace `json:"children,omitempty"`
	// Depth indicates the depth of the trace node
	Depth int `json:"depth"`
}

Trace denotes a node in the tree representation of Git Trace2 events. A node is not necessary a one-one mapping of an event.

func Parse

func Parse(ctx context.Context, reader io.Reader) (*Trace, error)

Parse parses the events generated by Git Trace2 API into a tree data structure.

Git Trace2 produces a flat list of events. They are sorted in chronological order. Each event describes a certain sub operation, including some relative data and metadata. Some events, such as "region_enter" or "cmd_start", indicate a new subtree in which the consecutive events belong to. Correspondingly, closing events such as "region_leave" or "atexit", exits the current section. Trace2 also captures the events of children processes.

By default, all events include "time", "file", and "line" fields. Those fields increase the size and processing overhead significantly. So, we set GIT_TRACE2_BRIEF environment variable to omit such information. Only the time from the initial events of main process or sub processes contains the absolute. The times of other events can be inferred from the time difference relative to the first event ("t_abs" field) or the current section ("t_rel" field).

Apart from the processing events, Trace2 API also exposes useful statistical information. They are stored in "data" and "data_json" events under "key" and "value" fields. They are particularly useful to sample and expose internal Git metrics.

The result of the parsing process is a root Trace node of the tree. The root node is a dummy node, not a part of the original events. So, it's recommended to skip this node when walking.

For more information, please visit Trace2 API: https://git-scm.com/docs/api-trace2

func (*Trace) Inspect

func (trace *Trace) Inspect(detailed bool) string

Inspect returns the formatted string of the tree. It mimics the format for trace2's performance target: https://git-scm.com/docs/api-trace2#_perf_format. It's mostly used for testing and debugging purpose.

func (*Trace) IsRoot

func (trace *Trace) IsRoot() bool

IsRoot returns true if the current trace is the root of the tree

func (*Trace) SetMetadata

func (trace *Trace) SetMetadata(key, value string)

SetMetadata sets the metadata for the trace.

func (*Trace) Walk

func (trace *Trace) Walk(ctx context.Context, handler func(context.Context, *Trace) context.Context)

Walk performs in-order tree traversal. It stops at each node and trigger handler function with the current trace.