raw

Documentation

Overview

Package raw provides an interface to interpret and emit Go execution traces. It can interpret and emit execution traces in its wire format as well as a bespoke but simple text format.

The readers and writers in this package perform no validation on or ordering of the input, and so are generally unsuitable for analysis. However, they're very useful for testing and debugging the tracer in the runtime and more sophisticated trace parsers.

Text format specification

The trace text format produced and consumed by this package is a line-oriented format.

The first line in each text trace is the header line.

Trace Go1.XX

Following that is a series of event lines. Each event begins with an event name, followed by zero or more named unsigned integer arguments. Names are separated from their integer values by an '=' sign. Names can consist of any UTF-8 character except '='.

For example:

EventName arg1=23 arg2=55 arg3=53

Any amount of whitespace is allowed to separate each token. Whitespace is identified via unicode.IsSpace.

Some events have additional data on following lines. There are two such special cases.

The first special case consists of events with trailing byte-oriented data. The trailer begins on the following line from the event. That line consists of a single argument 'data' and a Go-quoted string representing the byte data within. Note: an explicit argument for the length is elided, because it's just the length of the unquoted string.

For example:

String id=5
	data="hello world\x00"

These events are identified in their spec by the HasData flag.

The second special case consists of stack events. These events are identified by the IsStack flag. These events also have a trailing unsigned integer argument describing the number of stack frame descriptors that follow. Each stack frame descriptor is on its own line following the event, consisting of four signed integer arguments: the PC, an integer describing the function name, an integer describing the file name, and the line number in that file that function was at at the time the stack trace was taken.

For example:

Stack id=5 n=2
	pc=1241251 func=3 file=6 line=124
	pc=7534345 func=6 file=3 line=64

Index

• type Event
  • func (e *Event) String() string
• type Reader
  • func NewReader(r io.Reader) (*Reader, error)
  • func (r *Reader) ReadEvent() (Event, error)
  • func (r *Reader) Version() version.Version
• type TextReader
  • func NewTextReader(r io.Reader) (*TextReader, error)
  • func (r *TextReader) ReadEvent() (Event, error)
  • func (r *TextReader) Version() version.Version
• type TextWriter
  • func NewTextWriter(w io.Writer, v version.Version) (*TextWriter, error)
  • func (w *TextWriter) WriteEvent(e Event) error
• type Writer
  • func NewWriter(w io.Writer, v version.Version) (*Writer, error)
  • func (w *Writer) WriteEvent(e Event) error

Types

type Event

type Event struct {
	Version version.Version
	Ev      event.Type
	Args    []uint64
	Data    []byte
}

Event is a simple representation of a trace event.

Note that this typically includes much more than just timestamped events, and it also represents parts of the trace format's framing. (But not interpreted.)

func (*Event) String

func (e *Event) String() string

String returns the canonical string representation of the event.

This format is the same format that is parsed by the TextReader and emitted by the TextWriter.

type Reader

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

Reader parses trace bytes with only very basic validation into an event stream.

func NewReader

func NewReader(r io.Reader) (*Reader, error)

NewReader creates a new reader for the trace wire format.

func (*Reader) ReadEvent

func (r *Reader) ReadEvent() (Event, error)

ReadEvent reads and returns the next trace event in the byte stream.

func (*Reader) Version

func (r *Reader) Version() version.Version

Version returns the version of the trace that we're reading.

type TextReader

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

TextReader parses a text format trace with only very basic validation into an event stream.

func NewTextReader

func NewTextReader(r io.Reader) (*TextReader, error)

NewTextReader creates a new reader for the trace text format.

func (*TextReader) ReadEvent

func (r *TextReader) ReadEvent() (Event, error)

ReadEvent reads and returns the next trace event in the text stream.

func (*TextReader) Version

func (r *TextReader) Version() version.Version

Version returns the version of the trace that we're reading.

type TextWriter

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

TextWriter emits the text format of a trace.

func NewTextWriter

func NewTextWriter(w io.Writer, v version.Version) (*TextWriter, error)

NewTextWriter creates a new write for the trace text format.

func (*TextWriter) WriteEvent

func (w *TextWriter) WriteEvent(e Event) error

WriteEvent writes a single event to the stream.

type Writer

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

Writer emits the wire format of a trace.

It may not produce a byte-for-byte compatible trace from what is produced by the runtime, because it may be missing extra padding in the LEB128 encoding that the runtime adds but isn't necessary when you know the data up-front.

func NewWriter

func NewWriter(w io.Writer, v version.Version) (*Writer, error)

NewWriter creates a new byte format writer.

func (*Writer) WriteEvent

func (w *Writer) WriteEvent(e Event) error

WriteEvent writes a single event to the trace wire format stream.