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
- Variables
- func Bytes(n int64) string
- func ClassifyStage(step string) string
- func ConfigStep(ctx context.Context, tr *Tracer, svc store.DesiredService)
- func EnvSummary(plain []string, tagged map[string]string) string
- func FormatLine(s store.DeployTraceStep) string
- func IsStage(s string) bool
- func StageKey(stage string) string
- func StageTail(rows []store.DeployTraceStep, stage string) []string
- func SummaryLine(detail string) string
- type Resolver
- type Sink
- type Span
- type StageObs
- type StageTracker
- type StageView
- type Tracer
- func (t *Tracer) AttemptID() string
- func (t *Tracer) Begin(ctx context.Context, name, detail string) *Span
- func (t *Tracer) BeginKey(ctx context.Context, name, key, detail string) *Span
- func (t *Tracer) Clone() *Tracer
- func (t *Tracer) Flush(ctx context.Context, sink Sink, attemptID, service string)
- func (t *Tracer) Has(key string) bool
- func (t *Tracer) Note(ctx context.Context, name, status, reason, detail string)
- func (t *Tracer) NoteKey(ctx context.Context, name, key, status, reason, detail string)
- func (t *Tracer) WithService(name string) *Tracer
Constants ¶
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.
const ( CacheHit = "hit" CachePartial = "partial" CacheMiss = "miss" )
Cache states a stage reports.
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.
const StepBuildStage = "build_stage"
StepBuildStage is the trace step name of one build stage row; its key is "build_stage.<stage>".
Variables ¶
var StageOrder = []string{StageSource, StageDetect, StageInstall, StageBuild, StageExport, StagePush}
StageOrder lists the stages in the order a build runs them.
Functions ¶
func ClassifyStage ¶
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 ¶
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 StageTail ¶
func StageTail(rows []store.DeployTraceStep, stage string) []string
StageTail returns the stored log tail of stage, empty when none was kept.
func SummaryLine ¶
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.
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.
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 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) BeginKey ¶
BeginKey starts a step whose key differs from its name (one per layer, probe).
func (*Tracer) Clone ¶
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 ¶
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) WithService ¶
WithService labels steps with a compose service name.