Documentation
¶
Overview ¶
Package progress is the terminal UI `sal build`, `sal run`, `sal push`, `sal pull`, and `sal clone` show while they work: a progress pane following every step of the invocation, and a log pane holding the log as it would otherwise have been printed, toggled with a key. The progress pane is a view over the OpenTelemetry spans sal already records around its slow steps (see pkg/telemetry), fed by a span processor rather than by progress calls of its own, so a step shows up here exactly when it shows up in a trace. A transfer span updates its attributes while it runs, and the pane reads them off the live span, which is how a push or pull shows how far along it is.
Index ¶
- Variables
- func TerminalSupported() bool
- type Phase
- type Step
- type Tracker
- func (t *Tracker) ForceFlush(context.Context) error
- func (t *Tracker) OnEnd(span sdktrace.ReadOnlySpan)
- func (t *Tracker) OnStart(_ context.Context, span sdktrace.ReadWriteSpan)
- func (t *Tracker) Outcome() string
- func (t *Tracker) Phases() []Phase
- func (t *Tracker) Render(width int, now time.Time, spinner string) []string
- func (t *Tracker) Root() *Step
- func (t *Tracker) Shutdown(context.Context) error
- type UI
Constants ¶
This section is empty.
Variables ¶
var ErrInterrupted = tea.ErrInterrupted
ErrInterrupted is returned by Run when the user pressed ctrl+c, or the process was sent SIGINT, before the work finished.
Functions ¶
func TerminalSupported ¶
func TerminalSupported() bool
TerminalSupported reports whether the panes can be shown: stdin and stderr are both terminals, since the panes draw on stderr and read keys from stdin, the terminal is a real one, and the process is not running in CI, where nobody is watching and a log that scrolls is what the job keeps. A CI runner that attaches a pseudo-terminal would otherwise open them.
Types ¶
type Phase ¶
type Phase struct {
// Span is the name of the span that marks the phase, started directly
// under the invocation's root span.
Span string
Label string
// Step is the span the phase is bound to, nil until it starts.
Step *Step
Skipped bool
// SkippedAttribute names the attribute the root span carries when the
// command decided there was nothing for the phase to do, holding why:
// a pull of a data product that is up to date. A phase skipped with a
// reason is shown as done with that reason, since what the command was
// for is already so, rather than as skipped.
SkippedAttribute string
}
Phase is one step of the plan a command follows, in the order the command takes them, bound to the span that marks it once that span starts. A phase whose span never started by the time a later phase did, or by the time the invocation ended, was skipped: a build with no imports fetches none, and a build with --without-sal-modules runs no task.
type Step ¶
type Step struct {
Name string
Started time.Time
// Ended is zero while the step is still running.
Ended time.Time
// Failed is the error a failed step ended with, and empty otherwise.
Failed string
// Unmet marks a step that ended without failing but without what it
// was after either: the lookup of an image the daemon does not hold.
// The pane marks it apart from a success and a failure.
Unmet bool
Attrs map[string]attribute.Value
Parent *Step
Children []*Step
// contains filtered or unexported fields
}
Step is one span of the invocation as the progress pane follows it: what it is, when it started and ended, the attributes it carries, and the steps under it.
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker follows the spans of one invocation as a tree of steps and binds the ones directly under the root to the phases of the plan. It is a span processor, so it is installed through telemetry.Setup, and it is safe to read from another goroutine than the one the spans are recorded on.
func NewTracker ¶
NewTracker returns a tracker following the given plan.
func (*Tracker) ForceFlush ¶
ForceFlush implements the span processor; the tracker exports nothing.
func (*Tracker) OnEnd ¶
func (t *Tracker) OnEnd(span sdktrace.ReadOnlySpan)
OnEnd records when a step ended, the attributes it ended with, and the error it failed with if any. The root ending marks every phase that never started as skipped.
func (*Tracker) OnStart ¶
func (t *Tracker) OnStart(_ context.Context, span sdktrace.ReadWriteSpan)
OnStart records a span as a step under its parent. The first span with no parent is the invocation's root; a later one started from a context without a span is kept under the root rather than as a second tree.
func (*Tracker) Outcome ¶
Outcome is what the command said about the phase it decided not to run, which the summary's headline carries so that a pull that pulled nothing says so on its first line; empty when every phase ran or none said why.
func (*Tracker) Phases ¶
Phases returns the plan as it stands: which phases have started, ended, or been skipped.
func (*Tracker) Render ¶
Render draws the progress pane as lines fitted to width: the phases of the plan in order, each with the steps under it, their elapsed times, and what their attributes say about them. Steps still running show the given spinner frame as their mark.
type UI ¶
type UI struct {
// contains filtered or unexported fields
}
UI is the pair of panes a command runs under: it owns the span processor the progress pane reads, the writer the log pane reads, and the terminal while Run is running.
func New ¶
New prepares the panes for a command. Every log line is also written to logFile when it is not nil, and logPath is where the user is told to find it once the panes close.
func (*UI) LogWriter ¶
LogWriter is where the slog handler writes while the panes are up: each line goes to the log pane and to the log file.
func (*UI) PrintSummary ¶
PrintSummary writes Summary to w with its colours fitted to what w can show.
func (*UI) Run ¶
Run shows the panes while work runs and returns what work returned, or ErrInterrupted when the user cancelled before it finished. The panes close as soon as work returns; Summary then says how it went. A yes/no prompt the work asks through pkg.Confirm is answered in the panes.
func (*UI) SpanProcessor ¶
func (ui *UI) SpanProcessor() telemetry.SpanProcessor
SpanProcessor is what feeds the progress pane; pass it to telemetry.Setup.