spec.go

     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 tracev2
     6  
     7  // EventType indicates an event's type from which its arguments and semantics can be
     8  // derived. Its representation matches the wire format's representation of the event
     9  // types that precede all event data.
    10  type EventType uint8
    11  
    12  // EventSpec is a specification for a trace event. It contains sufficient information
    13  // to perform basic parsing of any trace event for any version of Go.
    14  type EventSpec struct {
    15  	// Name is the human-readable name of the trace event.
    16  	Name string
    17  
    18  	// Args contains the names of each trace event's argument.
    19  	// Its length determines the number of arguments an event has.
    20  	//
    21  	// Argument names follow a certain structure and this structure
    22  	// is relied on by the testing framework to type-check arguments
    23  	// and to produce Values for experimental events.
    24  	//
    25  	// The structure is:
    26  	//
    27  	//     (?P<name>[A-Za-z]+)(_(?P<type>[A-Za-z]+))?
    28  	//
    29  	// In sum, it's a name followed by an optional type.
    30  	// If the type is present, it is preceded with an underscore.
    31  	// Arguments without types will be interpreted as just raw uint64s.
    32  	// The valid argument types and the Go types they map to are listed
    33  	// in the ArgTypes variable.
    34  	Args []string
    35  
    36  	// StringIDs indicates which of the arguments are string IDs.
    37  	StringIDs []int
    38  
    39  	// StackIDs indicates which of the arguments are stack IDs.
    40  	//
    41  	// The list is not sorted. The first index always refers to
    42  	// the main stack for the current execution context of the event.
    43  	StackIDs []int
    44  
    45  	// StartEv indicates the event type of the corresponding "start"
    46  	// event, if this event is an "end," for a pair of events that
    47  	// represent a time range.
    48  	StartEv EventType
    49  
    50  	// IsTimedEvent indicates whether this is an event that both
    51  	// appears in the main event stream and is surfaced to the
    52  	// trace reader.
    53  	//
    54  	// Events that are not "timed" are considered "structural"
    55  	// since they either need significant reinterpretation or
    56  	// otherwise aren't actually surfaced by the trace reader.
    57  	IsTimedEvent bool
    58  
    59  	// HasData is true if the event has trailer consisting of a
    60  	// varint length followed by unencoded bytes of some data.
    61  	//
    62  	// An event may not be both a timed event and have data.
    63  	HasData bool
    64  
    65  	// IsStack indicates that the event represents a complete
    66  	// stack trace. Specifically, it means that after the arguments
    67  	// there's a varint length, followed by 4*length varints. Each
    68  	// group of 4 represents the PC, file ID, func ID, and line number
    69  	// in that order.
    70  	IsStack bool
    71  
    72  	// Experiment indicates the ID of an experiment this event is associated
    73  	// with. If Experiment is not NoExperiment, then the event is experimental
    74  	// and will be exposed as an EventExperiment.
    75  	Experiment Experiment
    76  }
    77  
    78  // EventArgTypes is a list of valid argument types for use in Args.
    79  //
    80  // See the documentation of Args for more details.
    81  var EventArgTypes = [...]string{
    82  	"seq",     // sequence number
    83  	"pstatus", // P status
    84  	"gstatus", // G status
    85  	"g",       // trace.GoID
    86  	"m",       // trace.ThreadID
    87  	"p",       // trace.ProcID
    88  	"string",  // string ID
    89  	"stack",   // stack ID
    90  	"value",   // uint64
    91  	"task",    // trace.TaskID
    92  }
    93  
    94  // EventNames is a helper that produces a mapping of event names to event types.
    95  func EventNames(specs []EventSpec) map[string]EventType {
    96  	nameToType := make(map[string]EventType)
    97  	for i, spec := range specs {
    98  		nameToType[spec.Name] = EventType(byte(i))
    99  	}
   100  	return nameToType
   101  }
   102  
   103  // Experiment is an experiment ID that events may be associated with.
   104  type Experiment uint
   105  
   106  // NoExperiment is the reserved ID 0 indicating no experiment.
   107  const NoExperiment Experiment = 0
   108
View as plain text