runlog

package
v2.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package runlog 保存模型运行(非 PTY 的一次性命令)的完整输出。

输出只存在主机本地(INV-M4):每一路(stdout / stderr)前 HeadBytes 字节完整保留, 之后只滚动保留最近 TailBytes 字节,中间被丢弃的部分只记录字节数。 这样既保住命令开头(报错通常在这里),也保住结尾(最终结果通常在这里),磁盘占用却有上限。

目录布局(<Dir> 通常是 <数据目录>/records/runs):

<Dir>/<run id>/meta.json   运行信息与结果(原子更新)
<Dir>/<run id>/stdout.log  stdout 的开头部分(追加写)
<Dir>/<run id>/stdout.tail stdout 的结尾部分(周期性与结束时整体重写)
<Dir>/<run id>/stderr.*    同上

对运行中的运行,读取直接取自内存里的状态;已结束的运行取自文件。

磁盘写不下(写满、只读、句柄耗尽……)不能挡住命令本身(INV-R3):Begin 先回收最旧的、Hub 已确认的运行腾出空间再试一次, 仍不行就退到「只在内存里保留」的运行:不落盘,只留预览与最近 TailBytes 字节(最多保留最近 maxMemDone 个已结束的这类运行供读取)。

Index

Constants

View Source
const (
	DefaultHeadBytes = 8 << 20
	DefaultTailBytes = 256 << 10
	DefaultRetention = 7 * 24 * time.Hour
	DefaultQuota     = 256 << 20

	// StateRunning 是 Meta.State 在运行期间的取值;结束后取 termproto.Run* 之一。
	StateRunning = "running"
)

默认容量与保留策略(均可通过 Options 调整)。

Variables

View Source
var (
	ErrNotFound = errors.New("runlog: run not found")
	ErrExists   = errors.New("runlog: run already exists")
	ErrBadID    = errors.New("runlog: bad run id")
)

Functions

This section is empty.

Types

type Finish

type Finish struct {
	State  string
	Code   *int
	Signal string
	Reason string
	Ended  time.Time
}

Finish 描述运行的结局。

type Meta

type Meta struct {
	ID       string     `json:"id"`
	Cmd      string     `json:"cmd"`
	Shell    string     `json:"shell,omitempty"`
	Cwd      string     `json:"cwd,omitempty"`
	PID      int        `json:"pid,omitempty"`
	Started  int64      `json:"started"` // Unix 毫秒
	State    string     `json:"state"`   // running | exited | signaled | timeout | cancelled | lost
	Ended    int64      `json:"ended,omitempty"`
	Code     *int       `json:"code,omitempty"`
	Signal   string     `json:"signal,omitempty"`
	DurMS    int64      `json:"dur_ms,omitempty"`
	Reason   string     `json:"reason,omitempty"`
	Out      StreamMeta `json:"out"`
	Err      StreamMeta `json:"err"`
	Reported bool       `json:"reported,omitempty"` // Hub 已确认收到结束事件

	// 以下四项在运行结束时一并落盘,使「重连后补报的结束事件」与首次上报的内容一致。
	// InlineOut/InlineErr 仅在对应输出不超过 RunInlineMax 时有值;Prev* 是合并两路输出的开头 / 结尾预览。
	InlineOut []byte `json:"inline_out,omitempty"`
	InlineErr []byte `json:"inline_err,omitempty"`
	PrevHead  []byte `json:"prev_head,omitempty"`
	PrevTail  []byte `json:"prev_tail,omitempty"`
}

Meta 是一次运行的信息与结果。

type Options

type Options struct {
	Dir        string
	HeadBytes  int
	TailBytes  int
	Retention  time.Duration
	Quota      int64
	Now        func() time.Time
	Logf       func(format string, args ...any)
	Harden     func(dir string) error
	PreviewCap [2]int // 测试用:覆盖预览的 [开头, 结尾] 大小
}

Options 是存储的配置。零值字段取默认值。

type Page

type Page struct {
	Off     uint64 // 实际起点(起点落在被丢弃部分时会大于请求的偏移)
	Data    []byte
	Next    uint64 // 继续读取应使用的偏移
	Total   uint64 // 该路到目前为止产生的总字节数
	Gap     bool   // 请求的起点被丢弃,已从下一段可用内容开始
	EOF     bool   // 已读到末尾且运行已结束
	Running bool
}

Page 是一次读取的结果。

type Result

type Result struct {
	Meta     Meta
	Out, Err []byte // 对应输出不超过 RunInlineMax 时给出全文,否则为 nil
	PrevHead []byte
	PrevTail []byte
}

Result 是 Finish 的返回:落盘后的元信息,以及随 run_end 上报的内联输出与预览。

type Store

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

Store 管理一台主机上的全部运行输出。

func Open

func Open(o Options) (*Store, error)

Open 打开(必要时创建)存储目录。

func (*Store) Begin

func (s *Store) Begin(meta Meta) (*Writer, error)

Begin 为一次新运行创建目录与输出文件。同一 ID 已存在时返回 ErrExists。 磁盘上建不出来时不会让命令跑不了(INV-R3):先回收旧运行腾空间再试一次,仍不行就退到只在内存里保留(见包注释)。

func (*Store) MarkReported

func (s *Store) MarkReported(id string) error

MarkReported 记下 Hub 已确认收到结束事件。运行不存在时返回 ErrNotFound。

func (*Store) Meta

func (s *Store) Meta(id string) (Meta, error)

Meta 返回一次运行的信息(运行中的取内存里的最新值)。

func (*Store) Read

func (s *Store) Read(id string, stream byte, off uint64, max int) (Page, error)

Read 从某一路输出的 off 起读取至多 max 字节。

func (*Store) RecoverOrphans

func (s *Store) RecoverOrphans(reason string) []Meta

RecoverOrphans 把上次没来得及收尾的运行(元信息仍是 running,但没有对应的写入器)标记为 lost, reason 说明为什么(主机重启 / 守护进程被停止 / 守护进程崩溃)。返回被标记的运行。

func (*Store) Sweep

func (s *Store) Sweep() int

Sweep 清理过期与超出配额的已结束运行(运行中的与尚未被 Hub 确认的结束事件之外的一律按时间和配额处理)。 返回删除的运行数。

func (*Store) Unreported

func (s *Store) Unreported(limit int) []Meta

Unreported 返回已结束但 Hub 尚未确认收到结束事件的运行(按结束时间从旧到新,最多 limit 条)。

type StreamMeta

type StreamMeta struct {
	Total int64 `json:"total"` // 该路产生的总字节数
	Head  int64 `json:"head"`  // 文件里保留的开头字节数
	Tail  int64 `json:"tail"`  // 文件里保留的结尾字节数(覆盖 [Total-Tail, Total))
}

StreamMeta 是一路输出的统计。

func (StreamMeta) Dropped

func (m StreamMeta) Dropped() int64

Dropped 返回被丢弃的中间字节数。

type Writer

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

Writer 是一次运行的输出写入器,可被两路输出的读取协程并发使用。

func (*Writer) Discard

func (w *Writer) Discard()

Discard 丢弃一次根本没有真正开始的运行(例如进程没能启动):删除目录并注销写入器,不留下任何记录。

func (*Writer) Finish

func (w *Writer) Finish(f Finish) Result

Finish 收尾:写下结尾文件与最终元信息,并把写入器从存储里注销。重复调用返回第一次的结果之后的快照。

func (*Writer) FlushTails

func (w *Writer) FlushTails()

FlushTails 把结尾环整体写入 .tail 文件(有变化时)。运行较长时由持有者定期调用, 这样守护进程崩溃时磁盘上的结尾部分最多落后一个调用间隔。

func (*Writer) ID

func (w *Writer) ID() string

ID 返回运行 ID。

func (*Writer) SetStarted

func (w *Writer) SetStarted(pid int, shell, cwd string, started time.Time)

SetStarted 记下进程已启动后才知道的信息(PID、实际 shell 与工作目录、启动时间)。

func (*Writer) Totals

func (w *Writer) Totals() (out, errBytes int64)

Totals 返回两路输出到目前为止的总字节数。

func (*Writer) Write

func (w *Writer) Write(stream byte, p []byte) uint64

Write 追加一段输出,返回这段数据在该路输出中的起始偏移(用于给实时帧标注位置)。 写盘失败不会影响调用方:计数与实时流照常,只是这部分不会出现在文件里。

Jump to

Keyboard shortcuts

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