golang.org/x/exp@v0.0.0-20240506185415-9bf2ced13842/trace/internal/raw/doc.go (about)

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Code generated by "gen.bash" from internal/trace/v2; DO NOT EDIT.
     6  
     7  //go:build go1.21
     8  
     9  /*
    10  Package raw provides an interface to interpret and emit Go execution traces.
    11  It can interpret and emit execution traces in its wire format as well as a
    12  bespoke but simple text format.
    13  
    14  The readers and writers in this package perform no validation on or ordering of
    15  the input, and so are generally unsuitable for analysis. However, they're very
    16  useful for testing and debugging the tracer in the runtime and more sophisticated
    17  trace parsers.
    18  
    19  # Text format specification
    20  
    21  The trace text format produced and consumed by this package is a line-oriented
    22  format.
    23  
    24  The first line in each text trace is the header line.
    25  
    26  	Trace Go1.XX
    27  
    28  Following that is a series of event lines. Each event begins with an
    29  event name, followed by zero or more named unsigned integer arguments.
    30  Names are separated from their integer values by an '=' sign. Names can
    31  consist of any UTF-8 character except '='.
    32  
    33  For example:
    34  
    35  	EventName arg1=23 arg2=55 arg3=53
    36  
    37  Any amount of whitespace is allowed to separate each token. Whitespace
    38  is identified via unicode.IsSpace.
    39  
    40  Some events have additional data on following lines. There are two such
    41  special cases.
    42  
    43  The first special case consists of events with trailing byte-oriented data.
    44  The trailer begins on the following line from the event. That line consists
    45  of a single argument 'data' and a Go-quoted string representing the byte data
    46  within. Note: an explicit argument for the length is elided, because it's
    47  just the length of the unquoted string.
    48  
    49  For example:
    50  
    51  	String id=5
    52  		data="hello world\x00"
    53  
    54  These events are identified in their spec by the HasData flag.
    55  
    56  The second special case consists of stack events. These events are identified
    57  by the IsStack flag. These events also have a trailing unsigned integer argument
    58  describing the number of stack frame descriptors that follow. Each stack frame
    59  descriptor is on its own line following the event, consisting of four signed
    60  integer arguments: the PC, an integer describing the function name, an integer
    61  describing the file name, and the line number in that file that function was at
    62  at the time the stack trace was taken.
    63  
    64  For example:
    65  
    66  	Stack id=5 n=2
    67  		pc=1241251 func=3 file=6 line=124
    68  		pc=7534345 func=6 file=3 line=64
    69  */
    70  package raw