logfile

Documentation

Overview

Package logfile implements a hook that will re-run the current process with a PTY attached to it, and then hook into the PTY's stdout/stderr to record logs. Also exposed is the lower level functions (recorder, storage) that are used to implement the hook.

Index

• Constants
• func Hook() error
• type Entry
  • func NewEntryFromFrame(f *Frame) Entry
  • func NewEntryFromMetadata(m *Metadata) Entry
  • func NewEntryFromTrace(t *Trace) Entry
  • func NewFrameEntry(delay time.Duration, b []byte) Entry
  • func NewMetadataEntry(startedAt time.Time, width, height int, command string, args []string) Entry
  • func NewTraceEntry(spans []*Span) Entry
  • func ReadFile(path string) ([]Entry, error)
  • func ReadFromReader(r io.Reader) ([]Entry, error)
  • func (e Entry) AsFrame() *Frame
  • func (e Entry) AsMetadata() *Metadata
  • func (e Entry) AsTrace() *Trace
  • func (e Entry) IsFrame() bool
  • func (e Entry) IsMetadata() bool
  • func (e Entry) IsTrace() bool
  • func (e Entry) MarshalJSON() ([]byte, error)
  • func (e *Entry) UnmarshalJSON(data []byte) error
• type EntryMetadata
• type EntryType
• type Frame
• type Metadata
• type Span
  • func (s *Span) Snapshot() tracesdk.ReadOnlySpan
  • func (s *Span) UnmarshalJSON(data []byte) error
• type Trace
  • func (t Trace) Snapshots() []tracesdk.ReadOnlySpan

Constants

const EnvironmentVariable = "OUTREACH_LOGGING_TO_FILE"

EnvironmentVariable is the environment variable that is set when the process is being re-ran with a PTY attached to it and its logs are being recorded.

const FrameVersion = 1

FrameVersion is the version of frames this package supports

const InProgressSuffix = "_inprog"

InProgressSuffix is the suffix to denote that a log file is for an in-progress command. Meaning that it is not complete, or that the wrapper has crashed.

Note: This does not include the file extension, which can be grabbed from LogExtension.

const LogDirectoryBase = ".outreach" + string(filepath.Separator) + "logs"

LogDirectoryBase is the directory where logs are stored relative to the user's home directory.

const LogExtension = "json"

LogExtension is the extension for log files

const MetadataVersion = 1

MetadataVersion is the version of the metadata format this package supports.

const TracePortEnvironmentVariable = "OUTREACH_LOGGING_PORT"

TracePortEnvironmentVariable is the environment variable for the socket port used to communicate traces between the child app and the logging wrapper.

const TraceSocketType = "tcp"

SocketType is the type of socket for the log file.

Functions

func Hook

func Hook() error

Hook re-runs the current process with a PTY attached to it, and then hooks into the PTY's stdout/stderr to record logs.

Types

type Entry

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

Entry is an entry in the log file

func NewEntryFromFrame

func NewEntryFromFrame(f *Frame) Entry

NewEntryFromFrame creates an entry from a frame

func NewEntryFromMetadata

func NewEntryFromMetadata(m *Metadata) Entry

NewEntryFromMetadata creates an entry from metadata

func NewEntryFromTrace

func NewEntryFromTrace(t *Trace) Entry

NewEntryFromTrace creates an entry from a trace

func NewFrameEntry

func NewFrameEntry(delay time.Duration, b []byte) Entry

NewFrameEntry creates a new frame entry

func NewMetadataEntry

func NewMetadataEntry(startedAt time.Time, width, height int, command string, args []string) Entry

NewMetadata creates a new metadata entry

func NewTraceEntry

func NewTraceEntry(spans []*Span) Entry

NewTraceEntry creates a new trace entry

func ReadFile

func ReadFile(path string) ([]Entry, error)

ReadFile reads a log file and returns the entries in it.

func ReadFromReader

func ReadFromReader(r io.Reader) ([]Entry, error)

ReadFromReader reads entires from a io.reader

func (Entry) AsFrame

func (e Entry) AsFrame() *Frame

AsFrame returns the current frame or nil if it's not a frame

func (Entry) AsMetadata

func (e Entry) AsMetadata() *Metadata

AsMetadata returns the metadata from the current entry, or nil if it's not metadata

func (Entry) AsTrace

func (e Entry) AsTrace() *Trace

AsFrame returns the current frame or nil if it's not a frame

func (Entry) IsFrame

func (e Entry) IsFrame() bool

IsFrame returns true if the entry is a frame

func (Entry) IsMetadata

func (e Entry) IsMetadata() bool

IsMetadata returns true if the entry is metadata

func (Entry) IsTrace

func (e Entry) IsTrace() bool

IsTrace returns true if the entry is a trace

func (Entry) MarshalJSON

func (e Entry) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for an entry

func (*Entry) UnmarshalJSON

func (e *Entry) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler picking the correct type of entry based on the type field

type EntryMetadata

type EntryMetadata struct {
	// Type is the type of entry in the log file
	Type EntryType `json:"t"`
}

EntryMetadata is the basic metadata for an entry that must be present in all entries

type EntryType

type EntryType int

EntryType is the type of entry in the log file

const (
	// EntryTypeMetadata is a metadata entry which is equal to
	// a Metadata struct
	EntryTypeMetadata EntryType = iota

	// EntryTypeFrame is a frame entry which is equal to a Frame struct
	EntryTypeFrame

	// EntryTypeTrace is a trace entry representing a full or partial otel trace
	EntryTypeTrace
)

type Frame

type Frame struct {
	// EntryMetadata implements a entry
	EntryMetadata `json:",inline"`

	// Delay is the delay since the last frame.
	Delay time.Duration `json:"d"`

	// Bytes is the bytes written to the terminal.
	Bytes []byte `json:"b"`
}

Frame is a frame in a log file that contains the frames written to a terminal and the time between them.

type Metadata

type Metadata struct {
	// EntryMetadata implements a entry
	EntryMetadata `json:",inline"`

	// Version is the version of the metadata format
	Version int `json:"version"`

	// FrameVersion is the version of the frame format used
	FrameVersion int `json:"frame_version"`

	// Width is the width of the terminal
	Width int `json:"width"`

	// Height is the height of the terminal
	Height int `json:"height"`

	// StartedAt is the time that the process was started.
	StartedAt time.Time `json:"started_at"`

	// Command is the binary that was executed.
	Command string `json:"command"`

	// Args is the arguments that were passed to the binary.
	Args []string `json:"args"`
}

Metadata is the first entry in a log file that contains information about the log file.

type Span

type Span struct {
	// Name is the name of a the specific span
	Name string
	// SpanContext is the unique SpanContext that identifies the span
	SpanContext trace.SpanContext
	// Parten is the unique SpanContext that identifies the parent of the span.
	// If the span has no parent, this span context will be invalid.
	Parent trace.SpanContext
	// SpanKind is the role the span plays in a Trace
	SpanKind trace.SpanKind
	// StartTime is the time the span started recording
	StartTime time.Time
	// EndTime returns the time the span stopped recording
	EndTime time.Time
	// Attributes are the defining attributes of a span
	Attributes []attribute.KeyValue
	// Events are all the events that occurred within the span
	Events []tracesdk.Event
	// Links are all the links the span has to other spans
	Links []tracesdk.Link
	// Status is that span status
	Status tracesdk.Status
	// DroppedAttributes is the number of attributes dropped by the span due to a limit being reached
	DroppedAttributes int
	// DroppedEvents is the number of attributes dropped by the span due to a limit being reached
	DroppedEvents int
	// DroppedLinks is the number of links dropped by the span due to a limit being reached
	DroppedLinks int
	// ChildSpanCount is the count of spans that consider the span a direct parent
	ChildSpanCount int
	// Resource is the information about the entity that produced the span
	// We have to change this type from the otel type in order to make this struct marshallable
	Resource []attribute.KeyValue
	// InstrumentationLibrary is information about the library that produced the span
	InstrumentationLibrary instrumentation.Library
}

Span is a type similar to otel's SpanStub, but with the correct types needed for handle marshalling and unmarshalling.

func (*Span) Snapshot

func (s *Span) Snapshot() tracesdk.ReadOnlySpan

Snapshot turns a Span into a ReadOnlySpan which is exportable by otel.

func (*Span) UnmarshalJSON

func (s *Span) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for Span which allows correctly retrieving attribute.KeyValue values

type Trace

type Trace struct {
	// EntryMetadata implements a entry
	EntryMetadata `json:",inline"`

	// Spans is a list of spans
	Spans []*Span `json:"spans"`
}

Trace is an entry in the logfile representing an otel trace.

func (Trace) Snapshots

func (t Trace) Snapshots() []tracesdk.ReadOnlySpan

Snapshots returns a slice of ReadOnlySpans exportable by otle.