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