github.com/go-asm/go@v1.21.1-0.20240213172139-40c5ead50c48/trace/v2/event/event.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  package event
     6  
     7  // Type is the common in-memory representation of the low-leve
     8  type Type uint8
     9  
    10  // Spec is a specification for a trace event. It contains sufficient information
    11  // to perform basic parsing of any trace event for any version of Go.
    12  type Spec struct {
    13  	// Name is the human-readable name of the trace event.
    14  	Name string
    15  
    16  	// Args contains the names of each trace event's argument.
    17  	// Its length determines the number of arguments an event has.
    18  	//
    19  	// Argument names follow a certain structure and this structure
    20  	// is relied on by the testing framework to type-check arguments.
    21  	// The structure is is:
    22  	//
    23  	//     (?P<name>[A-Za-z]+_)?(?P<type>[A-Za-z]+)
    24  	//
    25  	// In sum, it's an optional name followed by a type. If the name
    26  	// is present, it is separated from the type with an underscore.
    27  	// The valid argument types and the Go types they map to are listed
    28  	// in the ArgTypes variable.
    29  	Args []string
    30  
    31  	// StartEv indicates the event type of the corresponding "start"
    32  	// event, if this event is an "end," for a pair of events that
    33  	// represent a time range.
    34  	StartEv Type
    35  
    36  	// IsTimedEvent indicates whether this is an event that both
    37  	// appears in the main event stream and is surfaced to the
    38  	// trace reader.
    39  	//
    40  	// Events that are not "timed" are considered "structural"
    41  	// since they either need significant reinterpretation or
    42  	// otherwise aren't actually surfaced by the trace reader.
    43  	IsTimedEvent bool
    44  
    45  	// HasData is true if the event has trailer consisting of a
    46  	// varint length followed by unencoded bytes of some data.
    47  	HasData bool
    48  
    49  	// StringIDs indicates which of the arguments are string IDs.
    50  	StringIDs []int
    51  
    52  	// StackIDs indicates which of the arguments are stack IDs.
    53  	//
    54  	// The list is not sorted. The first index always refers to
    55  	// the main stack for the current execution context of the event.
    56  	StackIDs []int
    57  
    58  	// IsStack indicates that the event represents a complete
    59  	// stack trace. Specifically, it means that after the arguments
    60  	// there's a varint length, followed by 4*length varints. Each
    61  	// group of 4 represents the PC, file ID, func ID, and line number
    62  	// in that order.
    63  	IsStack bool
    64  }
    65  
    66  // ArgTypes is a list of valid argument types for use in Args.
    67  //
    68  // See the documentation of Args for more details.
    69  var ArgTypes = [...]string{
    70  	"seq",     // sequence number
    71  	"pstatus", // P status
    72  	"gstatus", // G status
    73  	"g",       // trace.GoID
    74  	"m",       // trace.ThreadID
    75  	"p",       // trace.ProcID
    76  	"string",  // string ID
    77  	"stack",   // stack ID
    78  	"value",   // uint64
    79  	"task",    // trace.TaskID
    80  }
    81  
    82  // Names is a helper that produces a mapping of event names to event types.
    83  func Names(specs []Spec) map[string]Type {
    84  	nameToType := make(map[string]Type)
    85  	for i, spec := range specs {
    86  		nameToType[spec.Name] = Type(byte(i))
    87  	}
    88  	return nameToType
    89  }