progress

package
v0.1.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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.

func Plan

func Plan(command string) []Phase

Plan is the phases the panes follow for a command, nil for a command that has none, which is how main knows which commands run under them.

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.

func (*Step) Elapsed

func (s *Step) Elapsed(now time.Time) time.Duration

Elapsed is how long the step has been running as of now, or how long it ran.

func (*Step) Running

func (s *Step) Running() bool

Running reports whether the step has not ended yet.

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

func NewTracker(plan []Phase) *Tracker

NewTracker returns a tracker following the given plan.

func (*Tracker) ForceFlush

func (t *Tracker) ForceFlush(context.Context) error

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

func (t *Tracker) Outcome() string

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

func (t *Tracker) Phases() []Phase

Phases returns the plan as it stands: which phases have started, ended, or been skipped.

func (*Tracker) Render

func (t *Tracker) Render(width int, now time.Time, spinner string) []string

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.

func (*Tracker) Root

func (t *Tracker) Root() *Step

Root returns the invocation's root step, nil before it starts.

func (*Tracker) Shutdown

func (t *Tracker) Shutdown(context.Context) error

Shutdown implements the span processor; the tracker holds nothing to release.

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

func New(command string, logFile io.Writer, logPath string) *UI

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

func (ui *UI) LogWriter() io.Writer

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

func (ui *UI) PrintSummary(w io.Writer)

PrintSummary writes Summary to w with its colours fitted to what w can show.

func (*UI) Run

func (ui *UI) Run(work func() error) (err error)

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.

func (*UI) Summary

func (ui *UI) Summary() string

Summary is what is printed once the panes have closed, so that the terminal keeps a record of the invocation: how it ended and after how long, the plan with every step's time, and where the full log is.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL