Help us shape the future of Go! Take the 2026 Go Developer Survey

diagnostics

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package diagnostics records bounded, content-free collection diagnostics. Callers supply metadata and structured events, never argv, output or error text.

Index

Constants

View Source 
const (
	SchemaVersion  = 1
	MaxCommands    = 128
	MaxSlowest     = 20
	MaxStages      = 128
	MaxStageTotals = 512
	MaxReportBytes = 1 << 20
	MaxReports     = 5
)

Variables

View Source 
var (
	ErrInvalidReport = errors.New("invalid diagnostics report")
	ErrInvalidID     = errors.New("invalid diagnostics report ID")
	ErrNotFound      = errors.New("diagnostics report not found")
)

Functions

func Export 

func Export(directory, id string, latest bool, output string) error

Export copies one validated schema-1 report to a newly created private output file. latest and id are mutually exclusive. Existing output is never replaced, including symlinks. Reads reject report symlinks and files over 1 MiB.

func Save 

func Save(directory string, report Report) error

Save atomically stores a report under directory and retains the five newest reports. Every reader/writer uses the same persistent process lock. The caller decides whether a save error should be logged; it must not replace collection's primary result. No configuration or application services are consulted here.

func ValidID 

func ValidID(id string) bool

ValidID permits canonical random UUIDs only, never file paths.

Types

type CommandInfo 

type CommandInfo struct {
	StageInfo
	Operation string `json:"operation"`
}

type CommandRecord 

type CommandRecord struct {
	CommandInfo
	Sequence     uint64   `json:"sequence"`
	StartedMS    int64    `json:"startedMs"`
	ElapsedMS    int64    `json:"elapsedMs"`
	QueueWaitMS  int64    `json:"queueWaitMs"`
	StdoutBytes  int64    `json:"stdoutBytes"`
	StderrBytes  int64    `json:"stderrBytes"`
	ExitStatus   *int     `json:"exitStatus,omitempty"`
	DeadlineKind string   `json:"deadlineKind"`
	InFlight     bool     `json:"inFlight"`
	Failure      *Failure `json:"failure,omitempty"`
}

type CommandResult 

type CommandResult struct {
	QueueWait    time.Duration
	Elapsed      time.Duration
	StdoutBytes  int64
	StderrBytes  int64
	ExitStatus   *int
	DeadlineKind string
	Failure      *Failure
}

CommandResult includes queue wait separately from process execution time. ExitStatus is nil when a process never produced an exit status.

type Failure 

type Failure struct {
	Kind   string `json:"kind"`
	Detail string `json:"detail,omitempty"`
	Phase  string `json:"phase,omitempty"`
	Code   string `json:"code,omitempty"`
}

Failure deliberately has no error/string-message field. Unknown values become "unknown"; Detail is an allowlisted summary code, never exception text.

type Metadata 

type Metadata struct {
	AppVersion    string `json:"appVersion"`
	BuildCommit   string `json:"buildCommit,omitempty"`
	BuildDate     string `json:"buildDate,omitempty"`
	BuildModified bool   `json:"buildModified"`
	Platform      string `json:"platform"`
	Architecture  string `json:"architecture"`
	GoVersion     string `json:"goVersion"`
	GitVersion    string `json:"gitVersion"`
	GitPath       string `json:"gitPath,omitempty"`
	Operation     string `json:"operation"`
}

Metadata contains build/runtime facts only. GitPath is pseudonymized by New. Unrecognized versions/platforms/operations are replaced with "unknown".

type Outcome 

type Outcome struct {
	Status    string    `json:"status"`
	Primary   *Failure  `json:"primary,omitempty"`
	Cancelled bool      `json:"cancelled"`
	Cleanup   []Failure `json:"cleanup,omitempty"`
}

type Recorder 

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

Recorder is safe for concurrent workers. A snapshot includes active commands; it cannot survive a process crash unless the caller saves it before the crash.

func New 

func New(metadata Metadata) *Recorder

func (*Recorder) AddWorkload 

func (r *Recorder) AddWorkload(delta Workload)

AddWorkload adds nonnegative deltas; counters survive event truncation.

func (*Recorder) BeginCommand 

func (r *Recorder) BeginCommand(info CommandInfo) func(CommandResult)

BeginCommand starts before queue admission. Complete it even on cancellation. At most 128 active commands are retained, independently of the latest list.

func (*Recorder) BeginStage 

func (r *Recorder) BeginStage(info StageInfo) func(*Failure)

BeginStage returns an idempotent completion callback. Active stages remain in the bounded latest stage list; totals count even stages omitted from that list.

func (*Recorder) Finish 

func (r *Recorder) Finish(outcome Outcome) Report

Finish sets the overall outcome without replacing its primary error with a cancellation or cleanup failure. It also retains unfinished command metadata. The first call freezes the recorder; subsequent events and finishes are ignored.

func (*Recorder) Snapshot 

func (r *Recorder) Snapshot() Report

type Report 

type Report struct {
	SchemaVersion    int             `json:"schemaVersion"`
	ID               string          `json:"id"`
	Metadata         Metadata        `json:"metadata"`
	StartedAt        time.Time       `json:"startedAt"`
	ElapsedMS        int64           `json:"elapsedMs"`
	Outcome          Outcome         `json:"outcome"`
	Totals           Totals          `json:"totals"`
	Stages           []StageRecord   `json:"stages"`
	LatestCommands   []CommandRecord `json:"latestCommands"`
	SlowestCommands  []CommandRecord `json:"slowestCommands"`
	InFlightCommands []CommandRecord `json:"inFlightCommands"`
	DroppedCommands  uint64          `json:"droppedCommands"`
	DroppedStages    uint64          `json:"droppedStages"`
	DroppedInFlight  uint64          `json:"droppedInFlight"`
}

type StageInfo 

type StageInfo struct {
	Name       string `json:"name"`
	Scope      string `json:"scope,omitempty"`
	Attempt    int    `json:"attempt"`
	Repository string `json:"repository,omitempty"`
	Ref        string `json:"ref,omitempty"`
	URL        string `json:"url,omitempty"`
}

StageInfo and CommandInfo use fixed category names. Repository, Ref and URL accept raw identifiers only to hash them immediately, with a report-local key.

type StageRecord 

type StageRecord struct {
	StageInfo
	Sequence  uint64   `json:"sequence"`
	StartedMS int64    `json:"startedMs"`
	ElapsedMS int64    `json:"elapsedMs"`
	InFlight  bool     `json:"inFlight"`
	Failure   *Failure `json:"failure,omitempty"`
}

type StageTotal 

type StageTotal struct {
	Name      string `json:"name"`
	Scope     string `json:"scope,omitempty"`
	Started   uint64 `json:"started"`
	Completed uint64 `json:"completed"`
	Failed    uint64 `json:"failed"`
	Attempts  uint64 `json:"attempts"`
	ElapsedMS int64  `json:"elapsedMs"`
}

StageTotal aggregates every event by its fixed stage and scope categories, independently of the bounded individual stage list.

type Totals 

type Totals struct {
	Commands          uint64       `json:"commands"`
	CompletedCommands uint64       `json:"completedCommands"`
	FailedCommands    uint64       `json:"failedCommands"`
	CommandElapsedMS  int64        `json:"commandElapsedMs"`
	QueueWaitMS       int64        `json:"queueWaitMs"`
	StdoutBytes       int64        `json:"stdoutBytes"`
	StderrBytes       int64        `json:"stderrBytes"`
	Stages            uint64       `json:"stages"`
	Workload          Workload     `json:"workload"`
	StageTotals       []StageTotal `json:"stageTotals"`
}

type Workload 

type Workload struct {
	Repositories int64 `json:"repositories"`
	Checkouts    int64 `json:"checkouts"`
	Scopes       int64 `json:"scopes"`
	Attempts     int64 `json:"attempts"`
	Files        int64 `json:"files"`
	Commits      int64 `json:"commits"`
	Bytes        int64 `json:"bytes"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.