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