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 } 90