deploytrace

package
v1.3.1 Latest Latest
Warning

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

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

Documentation

Overview

Package deploytrace records the step-by-step pipeline of a deploy, build or not, as rows the step stream, the log stream and the CLI all read.

Index

Constants

View Source
const (
	StageSource  = "source"
	StageDetect  = "detect"
	StageInstall = "install"
	StageBuild   = "build"
	StageExport  = "export"
	StagePush    = "push"
)

Build stages in pipeline order. Roll out is not here: the deploy trace already records it with its own steps.

View Source
const (
	CacheHit     = "hit"
	CachePartial = "partial"
	CacheMiss    = "miss"
)

Cache states a stage reports.

View Source
const (
	StepResolveDigest   = "resolve_digest"
	StepRegistryAuth    = "registry_auth"
	StepImagePull       = "image_pull"
	StepImagePullLayer  = "image_pull_layer"
	StepImageInspect    = "image_inspect"
	StepConfigValidate  = "config_validate"
	StepEnsureNetwork   = "ensure_network"
	StepEnsureVolume    = "ensure_volume"
	StepContainerCreate = "container_create"
	StepContainerStart  = "container_start"
	StepDockerEvent     = "docker_event"
	StepReadinessProbe  = "readiness_probe"
	StepReadinessGate   = "readiness_gate"
	StepStabilityGate   = "stability_gate"
	StepCutover         = "cutover"
	StepDrainOld        = "drain_old"
	StepRetainImage     = "retain_image"
	StepComposeParse    = "compose_parse"
	StepComposePlan     = "compose_plan"
	StepComposeService  = "compose_service"
	StepDependsOn       = "depends_on"
	StepSummary         = store.TraceSummaryKey
)

Step names. One constant per concept, shared by emitters and the viewer.

View Source
const StepBuildStage = "build_stage"

StepBuildStage is the trace step name of one build stage row; its key is "build_stage.<stage>".

Variables

StageOrder lists the stages in the order a build runs them.

Functions

func Bytes

func Bytes(n int64) string

Bytes renders n as a short human size.

func ClassifyStage

func ClassifyStage(step string) string

ClassifyStage maps a BuildKit step name to its stage; "" for an empty name, so a bare log line stays with the stage that was running.

func ConfigStep

func ConfigStep(ctx context.Context, tr *Tracer, svc store.DesiredService)

ConfigStep records what a deploy asks the node to run: env names (masked by source), port, volumes and resource limits, never values.

func EnvSummary

func EnvSummary(plain []string, tagged map[string]string) string

EnvSummary lists env var names, tagging non-plain sources. Values are never included: a secret, vault or database reference must not reach a log.

func FormatLine

func FormatLine(s store.DeployTraceStep) string

FormatLine renders s as one human log line for the deploy log stream.

func IsStage

func IsStage(s string) bool

IsStage reports whether s names a build stage.

func StageKey

func StageKey(stage string) string

StageKey is the trace row key of stage.

func StageTail

func StageTail(rows []store.DeployTraceStep, stage string) []string

StageTail returns the stored log tail of stage, empty when none was kept.

func SummaryLine

func SummaryLine(detail string) string

SummaryLine is the first line of a stage row's detail, the part safe to show in step and log feeds; the rest is the stage's log tail.

Types

type Resolver

type Resolver interface {
	TraceTargetFor(ctx context.Context, serviceName, image string) (attemptID string, sealed bool, err error)
}

Resolver maps a reconcile pass (service, image) to its deploy attempt.

type Sink

type Sink interface {
	SaveDeployTraceStep(ctx context.Context, s store.DeployTraceStep) error
}

Sink persists steps. *store.DB satisfies it.

type Span

type Span struct {
	// contains filtered or unexported fields
}

Span is one running step.

func (*Span) Done

func (s *Span) Done(ctx context.Context, detail string)

Done ends the step successfully.

func (*Span) End

func (s *Span) End(ctx context.Context, status, reason, detail string)

End finishes the step with status, a short reason code and a detail line.

func (*Span) Fail

func (s *Span) Fail(ctx context.Context, reason string, err error)

Fail ends the step failed, carrying the underlying error text verbatim.

func (*Span) Progress

func (s *Span) Progress(ctx context.Context, detail string)

Progress updates a running step's detail without ending it.

type StageObs

type StageObs struct {
	Step      string
	Cached    bool
	Completed bool
	Error     string
	Log       string
}

StageObs is one build progress update as the tracker needs it.

type StageTracker

type StageTracker struct {
	// contains filtered or unexported fields
}

StageTracker turns one build's progress events into per-stage trace rows with start, end, cache state and a short log tail. A nil tracker is valid.

func NewStageTracker

func NewStageTracker(tr *Tracer, tailLines func() int) *StageTracker

NewStageTracker returns a tracker writing to tr, or nil when tr is nil. tailLines gives the live per-stage tail size.

func (*StageTracker) Finish

func (s *StageTracker) Finish(ctx context.Context)

Finish closes every stage still open.

func (*StageTracker) Observe

func (s *StageTracker) Observe(ctx context.Context, o StageObs) string

Observe records o and returns the stage it belongs to.

type StageView

type StageView struct {
	Stage          string     `json:"stage"`
	Status         string     `json:"status"`
	StartedAt      time.Time  `json:"started_at"`
	EndedAt        *time.Time `json:"ended_at,omitempty"`
	DurationMS     int64      `json:"duration_ms"`
	Cache          string     `json:"cache,omitempty"`
	Vertices       int        `json:"vertices"`
	CachedVertices int        `json:"cached_vertices"`
	LogBytes       int64      `json:"log_bytes"`
}

StageView is the API and CLI shape of one build stage.

func StagesFromRows

func StagesFromRows(rows []store.DeployTraceStep) []StageView

StagesFromRows picks the build stage rows out of a trace, in pipeline order.

type Tracer

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer writes steps for one attempt. A nil *Tracer is valid and records nothing, so call sites never nil-check.

func ForImage

func ForImage(ctx context.Context, sink Sink, res Resolver, service, image string, logger *slog.Logger) *Tracer

ForImage resolves the attempt converging (service, image) and returns its tracer, or nil when none matches or the attempt's trace is already sealed.

func New

func New(sink Sink, attemptID string, logger *slog.Logger) *Tracer

New returns a tracer for attemptID, or nil when there is nothing to write to.

func NewBuffered

func NewBuffered() *Tracer

NewBuffered returns a tracer that holds steps in memory until Flush, for work that happens before the deploy attempt row (and so its id) exists.

func (*Tracer) AttemptID

func (t *Tracer) AttemptID() string

AttemptID reports which attempt t writes to.

func (*Tracer) Begin

func (t *Tracer) Begin(ctx context.Context, name, detail string) *Span

Begin starts a step keyed by its name.

func (*Tracer) BeginKey

func (t *Tracer) BeginKey(ctx context.Context, name, key, detail string) *Span

BeginKey starts a step whose key differs from its name (one per layer, probe).

func (*Tracer) Clone

func (t *Tracer) Clone() *Tracer

Clone copies a buffered tracer so one deploy's shared steps can gain per-service steps without leaking them to its siblings.

func (*Tracer) Flush

func (t *Tracer) Flush(ctx context.Context, sink Sink, attemptID, service string)

Flush writes every buffered step to sink under attemptID, labelled with service when the step has none. It can run once per attempt (a compose file's shared steps go to each service's attempt).

func (*Tracer) Has

func (t *Tracer) Has(key string) bool

Has reports whether a buffered step with key exists.

func (*Tracer) Note

func (t *Tracer) Note(ctx context.Context, name, status, reason, detail string)

Note records an instantaneous step.

func (*Tracer) NoteKey

func (t *Tracer) NoteKey(ctx context.Context, name, key, status, reason, detail string)

NoteKey is Note with an explicit key.

func (*Tracer) WithService

func (t *Tracer) WithService(name string) *Tracer

WithService labels steps with a compose service name.

Jump to

Keyboard shortcuts

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