Documentation
¶
Overview ¶
Package terminal is the terminal trace kind: it records a PTY session its host feeds it, and exports it as an asciinema v2 cast. The PTY stays in the host, which copies the bytes it reads into Writer; the capture settles the screen on an interval, as gavel's ANSI capture does, so the cast carries the timeline a viewer scrubs, the final screen and the lines it repeats.
Index ¶
Constants ¶
const ( DefaultWidth = 120 DefaultHeight = 40 DefaultSnapshotInterval = 100 * time.Millisecond DefaultMaxBytes = "4MiB" )
Defaults a capture starts from, as gavel's PTY capture settles its screen and bounds its cast.
const ( KindOutput = "o" KindResize = "r" KindSnapshot = "snapshot" KindExit = "exit" )
Event kinds a capture records.
const Kind = "terminal"
Kind is the name the terminal kind is registered under.
const NoExitCode = -1
NoExitCode is the exit code of a window the session had not exited in, or whose host never reported one.
Variables ¶
var Cast = tracing.ExportFormat{Name: "cast", Ext: "cast", MIME: "application/x-asciicast"}
Cast is the cast format: asciinema v2, whose first line is a header object and every line after it one event array.
Functions ¶
func NewKind ¶
NewKind is the terminal kind. A host registers it, starts a session of it, and feeds the session's stream through Writer.
func SetExitCode ¶
SetExitCode tells the capture of stream how its session exited; the writer's Close records it. A capture closed without one records no exit code.
func Writer ¶
func Writer(stream string) (io.WriteCloser, error)
Writer is where a host copies the bytes its PTY produces into the capture of stream, the stream the session's status names. It never blocks the copy: an event a full buffer cannot take is dropped and counted. Close it once the PTY is done, after SetExitCode, to end the capture.
Types ¶
type DupLine ¶
DupLine is a line a settled screen shows more than once.
func (DupLine) MarshalJSON ¶
MarshalJSON emits the duplicate as an object, since an assertion reads it by name.
type Event ¶
type Event struct {
At time.Time `json:"at" pretty:"label=At" sort:"at"`
Offset float64 `json:"offset" pretty:"label=Offset" sort:"offset"`
Kind string `json:"kind" filter:"terms"`
// Data is the output of an "o" event and the screen of a "snapshot".
Data string `json:"data" pretty:"hide" filter:"none"`
Width int `json:"width"`
Height int `json:"height"`
// ExitCode is the host's report of how the session ended, on the "exit" row.
ExitCode *int `json:"exitCode,omitempty"`
// Truncated, on the "exit" row, says that output events were not recorded:
// the size caps stopped them, or a full buffer dropped them. The screen is
// still the true final one.
Truncated bool `json:"truncated,omitempty"`
// Command, on the "exit" row, is the command line the terminal ran, a
// label for the cast's header.
Command string `json:"command,omitempty"`
}
Event is one row of a terminal session: a chunk of output, a resize, the settled screen at an instant, or the end of the session. Offset is the seconds since the first byte, the clock a cast plays on. Every row carries the terminal's size at that moment.
type Params ¶
type Params struct {
// Width and Height are the terminal's size in cells, and the viewport the
// settled snapshots are bounded by.
Width int `json:"width,omitempty" clicky:"title=Width"`
Height int `json:"height,omitempty" clicky:"title=Height"`
// SnapshotInterval, a duration such as 100ms, is how often the settled
// screen is recorded.
SnapshotInterval string `json:"snapshotInterval,omitempty" clicky:"title=Snapshot interval"`
// MaxBytes, a size such as 4MiB, caps the output the capture records as
// events. The screen goes on settling past it.
MaxBytes string `json:"maxBytes,omitempty" clicky:"title=Max bytes"`
// Command is the command line the terminal runs, for the cast's header.
Command []string `json:"command,omitempty" clicky:"title=Command"`
}
Params describe the terminal a host feeds the capture from.
type Stats ¶
type Stats struct {
// Bytes is every byte the host wrote, recorded or not.
Bytes int64 `json:"bytes"`
// Dropped is the output and resize events a full buffer could not take.
Dropped int64 `json:"dropped,omitempty"`
// Truncated says the size caps or dropped events left output unrecorded.
Truncated bool `json:"truncated,omitempty"`
}
Stats are what a capture counts beyond the rows it stores.
Source Files