trace

Documentation

Overview

Package trace provides the structured execution event model used by gbash.

This is a supported public extension package for callers that need to consume, record, or test against gbash execution events. Most embedders should prefer the root `github.com/ewhauser/gbash` package unless they are integrating with tracing or telemetry systems directly. Runtime tracing is opt-in; most embedders should enable redacted tracing from the root package rather than wiring raw event capture by default.

Index

• Constants
• type Buffer
  • func NewBuffer(opts ...Option) *Buffer
  • func (b *Buffer) Record(event *Event)
  • func (b *Buffer) Snapshot() []Event
• type CommandEvent
• type Event
• type Fanout
  • func NewFanout(recorders ...Recorder) *Fanout
  • func (f *Fanout) Record(event *Event)
  • func (f *Fanout) Snapshot() []Event
• type FileEvent
• type Kind
• type NopRecorder
  • func (NopRecorder) Record(*Event)
  • func (NopRecorder) Snapshot() []Event
• type Option
  • func WithExecutionID(executionID string) Option
  • func WithSchema(schema string) Option
  • func WithSessionID(sessionID string) Option
• type PolicyEvent
• type Recorder

Constants

const SchemaVersion = "gbash.trace.v1"

Types

type Buffer

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

func NewBuffer

func NewBuffer(opts ...Option) *Buffer

func (*Buffer) Record

func (b *Buffer) Record(event *Event)

func (*Buffer) Snapshot

func (b *Buffer) Snapshot() []Event

type CommandEvent

type CommandEvent struct {
	Name             string
	Argv             []string
	Dir              string
	ExitCode         int
	Builtin          bool
	Position         string
	Duration         time.Duration
	ResolvedName     string
	ResolvedPath     string
	ResolutionSource string
}

type Event

type Event struct {
	Schema      string
	SessionID   string
	ExecutionID string
	Kind        Kind
	At          time.Time
	// Redacted reports whether gbash scrubbed sensitive argv material before
	// the event was recorded or emitted.
	Redacted bool
	Command  *CommandEvent
	File     *FileEvent
	Policy   *PolicyEvent
	Message  string
	Error    string
}

type Fanout

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

Fanout forwards each event to multiple recorders.

func NewFanout

func NewFanout(recorders ...Recorder) *Fanout

NewFanout builds a recorder that duplicates events to each non-nil recorder.

func (*Fanout) Record

func (f *Fanout) Record(event *Event)

func (*Fanout) Snapshot

func (f *Fanout) Snapshot() []Event

type FileEvent

type FileEvent struct {
	Action   string
	Path     string
	FromPath string
	ToPath   string
}

type Kind

type Kind string

const (
	EventCallExpanded Kind = "call.expanded"
	EventCommandStart Kind = "command.start"
	EventCommandExit  Kind = "command.exit"
	EventFileAccess   Kind = "file.access"
	EventFileMutation Kind = "file.mutation"
	EventPolicyDenied Kind = "policy.denied"
)

type NopRecorder

type NopRecorder struct{}

NopRecorder discards every event.

func (NopRecorder) Record

func (NopRecorder) Record(*Event)

func (NopRecorder) Snapshot

func (NopRecorder) Snapshot() []Event

type Option

type Option func(*Buffer)

func WithExecutionID

func WithExecutionID(executionID string) Option

func WithSchema

func WithSchema(schema string) Option

func WithSessionID

func WithSessionID(sessionID string) Option

type PolicyEvent

type PolicyEvent struct {
	Subject          string
	Reason           string
	Action           string
	Path             string
	Command          string
	ExitCode         int
	ResolutionSource string
}

type Recorder

type Recorder interface {
	Record(*Event)
	Snapshot() []Event
}