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