Documentation
¶
Overview ¶
Package runlog records privacy-safe telemetry for commands launched through `wb run --`. The log lives inside a managed worktree so an agent can write it without access to the user's home directory and so lifecycle tooling can later publish or aggregate it with the worktree's other local evidence.
Index ¶
- Constants
- func Append(path string, event Event) error
- type Event
- type KindSummary
- type Recorder
- func (recorder Recorder) Finish(exitCode int, userCPU, systemCPU time.Duration, now time.Time) error
- func (recorder *Recorder) RecordAdmission(units int, wait time.Duration)
- func (recorder *Recorder) RecordLoadFloorSkipped(reason string)
- func (recorder *Recorder) RecordLoadOverride(overridden bool)
- func (recorder *Recorder) RecordQueueAdmittedAt(admittedAt time.Time)
- type Summary
Constants ¶
const ( EventSchemaVersion = 1 OperationIDEnv = "WB_OPERATION_ID" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Event ¶
type Event struct {
SchemaVersion int `json:"schema_version"`
Timestamp time.Time `json:"timestamp"`
OperationID string `json:"operation_id"`
State string `json:"state"`
Kind string `json:"kind"`
ArgsSHA256 string `json:"args_sha256"`
ArgumentCount int `json:"argument_count"`
Repository string `json:"repository,omitempty"`
EffortID string `json:"effort_id,omitempty"`
RunID string `json:"run_id,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
UserCPUMS int64 `json:"user_cpu_ms,omitempty"`
SystemCPUMS int64 `json:"system_cpu_ms,omitempty"`
QueueWaitMS int64 `json:"queue_wait_ms,omitempty"`
CPUUnits int `json:"cpu_units,omitempty"`
LoadOverride bool `json:"load_override,omitempty"`
// LoadFloorSkipped names why host-load admission was disabled for this
// command, when it was: "env" (WB_ADMISSION_LOAD_FLOOR<=0), "ci"
// (CI/GITHUB_ACTIONS declared), or "config" (wb.yaml
// admission.load_floor: 0). Empty means the check was active. See
// internal/hostload.Resolve.
LoadFloorSkipped string `json:"load_floor_skipped,omitempty"`
// AdmittedAt is the wall-clock moment this operation's CPU lease was
// granted (immediately for units <= 0, after QueueWaitMS otherwise). A
// pointer distinguishes "never admitted" (a command refused before
// admission) from the zero time. See cmd/wb run.go's queue-visibility
// receipts, which surface this alongside QueueWaitMS on stderr.
AdmittedAt *time.Time `json:"admitted_at,omitempty"`
ExitCode *int `json:"exit_code,omitempty"`
// Provenance fields (wb#631, SDLC logging-gap analysis 2026-09-18): IDs
// only, stamped by Begin from the environment at zero cost, never a
// prompt or response body. Additive and omitempty: EventSchemaVersion did
// not need to move for a purely additive field.
HarnessSessionID string `json:"harness_session_id,omitempty"`
Harness string `json:"harness,omitempty"`
EffortLevel string `json:"effort_level,omitempty"`
AgentID string `json:"agent_id,omitempty"`
ToolUseID string `json:"tool_use_id,omitempty"`
WBVersion string `json:"wb_version,omitempty"`
}
Event is one immutable command lifecycle observation. It deliberately omits raw arguments and output; ArgsSHA256 supports correlation without copying prompts, commit messages, paths, tokens, or source into the log.
type KindSummary ¶
type Recorder ¶
type Recorder struct {
OperationID string
Path string
StartedAt time.Time
// contains filtered or unexported fields
}
Recorder owns one operation ID and its optional managed-worktree log.
func Begin ¶
Begin records a requested operation when cwd belongs to a managed worktree. Unmanaged directories still get an operation ID but no filesystem side effect; WB can therefore wrap diagnostics outside a worktree safely.
func (Recorder) Finish ¶
func (recorder Recorder) Finish(exitCode int, userCPU, systemCPU time.Duration, now time.Time) error
Finish records the terminal result. CPU durations come from the child process state and exclude WB orchestration overhead.
func (*Recorder) RecordAdmission ¶
RecordAdmission adds scheduler evidence to the terminal event without exposing command arguments or output.
func (*Recorder) RecordLoadFloorSkipped ¶ added in v0.118.0
RecordLoadFloorSkipped records why host-load admission was disabled for this command (see internal/hostload.Resolve for the reason values), so a CI or WB_ADMISSION_LOAD_FLOOR-driven skip is provable from the runlog rather than only from the caller's own log.
func (*Recorder) RecordLoadOverride ¶ added in v0.118.0
RecordLoadOverride records whether --allow-saturated-host admitted this command despite the host's load average exceeding the admission floor.
func (*Recorder) RecordQueueAdmittedAt ¶ added in v0.120.0
RecordQueueAdmittedAt records the wall-clock moment this operation's CPU lease was granted, alongside RecordAdmission's queue-wait duration. Call it once, right after the lease is acquired (or immediately, for a units <= 0 command that never queues).
Source Files