annotation

Documentation

Overview

Package annotation implements a state machine that constructs Milo annotation protobufs from a series of annotation commands.

The annotation state is represented by a State object. Annotation strings are appended to the State via Append(), causing the State to incorporate that annotation and advance. During state advancement, any number of the State's Callbacks may be invoked in response to changes that are made.

State is pure (not bound to any I/O). Users of a State should interact with it by implementing Callbacks.

Index

• type Callbacks
• type Execution
  • func ProbeExecution(argv, env []string, cwd string) *Execution
• type State
  • func (s *State) Append(annotation string) error
  • func (s *State) CurrentStep() *Step
  • func (s *State) Finish()
  • func (s *State) LookupStep(name string) *Step
  • func (s *State) LookupStepErr(name string) (*Step, error)
  • func (s *State) ResolveStep(ms *annopb.Step) *Step
  • func (s *State) RootStep() *Step
  • func (s *State) SetCurrentStep(v *Step)
• type Step
  • func (as *Step) AddLogdogStreamLink(server, label string, prefix, name types.StreamName)
  • func (as *Step) AddStep(name string, legacy bool) *Step
  • func (as *Step) AddText(text string) bool
  • func (as *Step) AddURLLink(label, alias, url string)
  • func (as *Step) BaseStream(name types.StreamName) types.StreamName
  • func (as *Step) ClearSummary()
  • func (as *Step) ClearText() bool
  • func (as *Step) Close(closeTime *timestamppb.Timestamp) bool
  • func (as *Step) LogEnd(label string)
  • func (as *Step) LogLine(label, line string) bool
  • func (as *Step) Name() string
  • func (as *Step) Proto() *annopb.Step
  • func (as *Step) SetNestLevel(l int) bool
  • func (as *Step) SetProperty(name, value string) bool
  • func (as *Step) SetSTDERRStream(st *annopb.LogdogStream) (updated bool)
  • func (as *Step) SetSTDOUTStream(st *annopb.LogdogStream) (updated bool)
  • func (as *Step) SetStatus(s annopb.Status, fd *annopb.FailureDetails) bool
  • func (as *Step) SetSummary(value string) bool
  • func (as *Step) Start(startTime *timestamppb.Timestamp) bool
  • func (as *Step) String() string
• type UpdateType

Types

type Callbacks

type Callbacks interface {
	// StepClosed is called when a Step has closed. An Updated callback will still
	// be invoked.
	StepClosed(*Step)
	// Updated is called when a Step's state has been updated.
	Updated(*Step, UpdateType)
	// StepLogLine is called when a Step emits a log line.
	StepLogLine(s *Step, stream types.StreamName, label, line string)
	// StepLogEnd is called when a Step finishes emitting logs.
	StepLogEnd(*Step, types.StreamName)
}

Callbacks is the set of callbacks that a State may invoke as it processes annotations.

type Execution

type Execution struct {
	Name    string
	Command []string
	Dir     string
	Env     map[string]string
}

Execution describes the high-level execution metadata.

func ProbeExecution

func ProbeExecution(argv, env []string, cwd string) *Execution

ProbeExecution loads Execution parameters by probing the current runtime environment.

type State

type State struct {
	// LogNameBase is the base log stream name that is prepeneded to generated
	// log streams.
	LogNameBase types.StreamName
	// Callbacks implements annotation callbacks. It may not be nil.
	Callbacks Callbacks
	// Execution is the supplied Execution. If nil, no execution details will be
	// added to the generated annotation protos.
	Execution *Execution
	// Offline specifies whether parsing happens not at the same time as
	// emitting. If true and CURRENT_TIMESTAMP annotations are not provided
	// then step start/end times are left empty.
	Offline bool
	// Clock is the clock implementation to use for time information.
	// Defaults to system time.
	Clock clock.Clock
	// contains filtered or unexported fields
}

State is the aggregate annotation state for a given annotation stream. It receives updates in the form of annotations added via Append, and can be serialized to an annotation state protobuf.

func (*State) Append

func (s *State) Append(annotation string) error

Append adds an annotation to the state. If the state was updated, Append will return true.

The appended annotation should only contain the annotation text body, not any annotation indicators (e.g., "@@@") that surround it.

If the annotation is invalid or could not be added to the state, an error will be returned.

Steps and descriptions can be found at: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/ master/chromium_step.py

func (*State) CurrentStep

func (s *State) CurrentStep() *Step

CurrentStep returns the step referenced by the step cursor.

func (*State) Finish

func (s *State) Finish()

Finish closes the top-level annotation state and any outstanding steps.

func (*State) LookupStep

func (s *State) LookupStep(name string) *Step

LookupStep returns the step with the supplied name, or nil if no such step exists.

If multiple steps share a name, this will return the latest registered step with that name.

func (*State) LookupStepErr

func (s *State) LookupStepErr(name string) (*Step, error)

LookupStepErr returns the step with the supplied name, or an error if no such step exists.

If multiple steps share a name, this will return the latest registered step with that name.

func (*State) ResolveStep

func (s *State) ResolveStep(ms *annopb.Step) *Step

ResolveStep returns the annotation package *Step corresponding to the supplied *annopb.Step. This is a reverse lookup operation.

If the supplied *annopb.Step is not registered with this annotation State, this function will return nil.

func (*State) RootStep

func (s *State) RootStep() *Step

RootStep returns the root step.

func (*State) SetCurrentStep

func (s *State) SetCurrentStep(v *Step)

SetCurrentStep sets the current step. If the supplied step is nil, the root step will be used.

The supplied step must already be registered with the State.

type Step

type Step struct {
	annopb.Step

	// logNameBase is the LogDog stream name root for this step.
	LogNameBase types.StreamName
	// contains filtered or unexported fields
}

Step represents a single step.

func (*Step) AddLogdogStreamLink

func (as *Step) AddLogdogStreamLink(server, label string, prefix, name types.StreamName)

AddLogdogStreamLink adds a LogDog stream link to this Step's links list.

func (*Step) AddStep

func (as *Step) AddStep(name string, legacy bool) *Step

AddStep generates a new substep.

func (*Step) AddText

func (as *Step) AddText(text string) bool

AddText adds a line of step component text.

func (*Step) AddURLLink

func (as *Step) AddURLLink(label, alias, url string)

AddURLLink adds a URL link to this Step's links list.

func (*Step) BaseStream

func (as *Step) BaseStream(name types.StreamName) types.StreamName

BaseStream returns the supplied name prepended with this Step's base log name.

For example, if the base name is "foo/bar", BaseStream("baz") will return "foo/bar/baz".

func (*Step) ClearSummary

func (as *Step) ClearSummary()

ClearSummary clears the step's summary text.

func (*Step) ClearText

func (as *Step) ClearText() bool

ClearText clears step component text.

func (*Step) Close

func (as *Step) Close(closeTime *timestamppb.Timestamp) bool

Close closes this step and any outstanding resources that it owns. If it is already closed, does not have side effects and returns false.

func (*Step) LogEnd

func (as *Step) LogEnd(label string)

LogEnd ends the log for the specified label.

func (*Step) LogLine

func (as *Step) LogLine(label, line string) bool

LogLine emits a log line for a specified log label.

func (*Step) Name

func (as *Step) Name() string

Name returns the step's component name.

func (*Step) Proto

func (as *Step) Proto() *annopb.Step

Proto returns the annotation Step protobuf associated with this Step.

func (*Step) SetNestLevel

func (as *Step) SetNestLevel(l int) bool

SetNestLevel sets the nest level of this Step, and identifies its nesting parent.

If no parent could be found at level "l-1", the root step will become the parent.

func (*Step) SetProperty

func (as *Step) SetProperty(name, value string) bool

SetProperty sets a key/value property for this Step.

func (*Step) SetSTDERRStream

func (as *Step) SetSTDERRStream(st *annopb.LogdogStream) (updated bool)

SetSTDERRStream sets the LogDog STDERR stream value, returning true if the Step was updated.

func (*Step) SetSTDOUTStream

func (as *Step) SetSTDOUTStream(st *annopb.LogdogStream) (updated bool)

SetSTDOUTStream sets the LogDog STDOUT stream value, returning true if the Step was updated.

func (*Step) SetStatus

func (as *Step) SetStatus(s annopb.Status, fd *annopb.FailureDetails) bool

SetStatus sets this step's component status.

If the status doesn't change, the supplied failure details will be ignored.

func (*Step) SetSummary

func (as *Step) SetSummary(value string) bool

SetSummary sets the Step's summary text.

The summary is implemented as the first line of step component text. If no summary is currently defined, one will be inserted; otherwise, the current summary will be replaced.

func (*Step) Start

func (as *Step) Start(startTime *timestamppb.Timestamp) bool

Start marks the Step as started.

func (*Step) String

func (as *Step) String() string

type UpdateType

type UpdateType int

UpdateType is information sent to the Updated callback to indicate the nature of the update.

const (
	// UpdateIterative indicates that a non-structural update occurred.
	UpdateIterative UpdateType = iota
	// UpdateStructural indicates that a structural update has occurred. A
	// structural update is one that affects the existence of or relationship of
	// the Steps in the annotation.
	UpdateStructural
)