timing

Documentation

Overview

Package timing is used to collect and write timing information about a process.

Index

• func FromContext(ctx context.Context) (*Log, *Stage, bool)
• func NewContext(ctx context.Context, l *Log) context.Context
• type Log
  • func NewLog() *Log
  • func (l *Log) Empty() bool
  • func (l *Log) MarshalJSON() ([]byte, error)
  • func (l *Log) StartTop(name string) *Stage
  • func (l *Log) UnmarshalJSON(b []byte) error
  • func (l *Log) Write(w io.Writer) error
• type Stage
  • func Start(ctx context.Context, name string) (context.Context, *Stage)
  • func (s *Stage) End()
  • func (s *Stage) Import(o *Log) error
  • func (s *Stage) StartChild(name string) *Stage

Functions

func FromContext

func FromContext(ctx context.Context) (*Log, *Stage, bool)

FromContext returns the Log and the current Stage stored in ctx, if any.

func NewContext

func NewContext(ctx context.Context, l *Log) context.Context

NewContext returns a new context that carries l and its root stage as the current stage.

Types

type Log

type Log struct {
	// Root is a special root stage containing all stages as its descendants.
	// Its End should not be called, and its timestamps should be ignored.
	Root *Stage
}

Log contains nested timing information.

func NewLog

func NewLog() *Log

NewLog returns a new Log.

func (*Log) Empty

func (l *Log) Empty() bool

Empty returns true if l doesn't contain any stages.

func (*Log) MarshalJSON

func (l *Log) MarshalJSON() ([]byte, error)

MarshalJSON marshals Log as JSON.

func (*Log) StartTop

func (l *Log) StartTop(name string) *Stage

StartTop starts and returns a new top-level stage named name.

func (*Log) UnmarshalJSON

func (l *Log) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals Log as JSON.

func (*Log) Write

func (l *Log) Write(w io.Writer) error

Write writes timing information to w as JSON, consisting of an array of stages, each represented by an array consisting of the stage's duration, name, and an optional array of child stages.

Note that this format is lossy and differs from that used by json.Marshaler.

Output is intended to improve human readability:

[[4.000, "stage0", [
         [3.000, "stage1", [
                 [1.000, "stage2"],
                 [2.000, "stage3"]]],
         [1.000, "stage4"]]],
 [0.531, "stage5"]]

type Stage

type Stage struct {
	Name      string    `json:"name"`
	StartTime time.Time `json:"startTime"`
	EndTime   time.Time `json:"endTime"`
	Children  []*Stage  `json:"children"`
	// contains filtered or unexported fields
}

Stage represents a discrete unit of work that is being timed.

func Start

func Start(ctx context.Context, name string) (context.Context, *Stage)

Start starts and returns a new Stage named name within the Log attached to ctx. If no Log is attached to ctx, nil is returned. It is safe to call Close on a nil stage.

Example usage to report the time used until the end of the current function:

ctx, st := timing.Start(ctx, "my_stage")
defer st.End()

func (*Stage) End

func (s *Stage) End()

End ends the stage. Child stages are recursively examined and also ended (although we expect them to have already been ended).

func (*Stage) Import

func (s *Stage) Import(o *Log) error

Import imports the stages from o into s, with o's top-level stages inserted as children of s. An error is returned if s is already ended.

func (*Stage) StartChild

func (s *Stage) StartChild(name string) *Stage

StartChild creates and returns a new named timing stage as a child of s. Stage.End should be called when the stage is completed.