luci: Index | Files

package annotation

import ""

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.


Package Files

annotation.go doc.go execution.go

type Callbacks Uses

type Callbacks interface {
    // StepClosed is called when a Step has closed. An Updated callback will still
    // be invoked.
    // 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 Uses

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

Execution describes the high-level execution metadata.

func ProbeExecution Uses

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

ProbeExecution loads Execution parameters by probing the current runtime environment.

type State Uses

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 Uses

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

func (*State) CurrentStep Uses

func (s *State) CurrentStep() *Step

CurrentStep returns the step referenced by the step cursor.

func (*State) Finish Uses

func (s *State) Finish()

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

func (*State) LookupStep Uses

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 Uses

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 Uses

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 Uses

func (s *State) RootStep() *Step

RootStep returns the root step.

func (*State) SetCurrentStep Uses

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 Uses

type Step struct {

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

Step represents a single step.

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 Uses

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

AddStep generates a new substep.

func (*Step) AddText Uses

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

AddText adds a line of step component text.

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

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

func (*Step) BaseStream Uses

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 Uses

func (as *Step) ClearSummary()

ClearSummary clears the step's summary text.

func (*Step) ClearText Uses

func (as *Step) ClearText() bool

ClearText clears step component text.

func (*Step) Close Uses

func (as *Step) Close(closeTime *timestamp.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 Uses

func (as *Step) LogEnd(label string)

LogEnd ends the log for the specified label.

func (*Step) LogLine Uses

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

LogLine emits a log line for a specified log label.

func (*Step) Name Uses

func (as *Step) Name() string

Name returns the step's component name.

func (*Step) Proto Uses

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

Proto returns the annotation Step protobuf associated with this Step.

func (*Step) SetNestLevel Uses

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 Uses

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

SetProperty sets a key/value property for this Step.

func (*Step) SetSTDERRStream Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Start marks the Step as started.

func (*Step) String Uses

func (as *Step) String() string

type UpdateType Uses

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.

Package annotation imports 14 packages (graph) and is imported by 5 packages. Updated 2020-12-01. Refresh now. Tools for package owners.