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 []byte
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 [][]byte
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 = [...][]byte{
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 := 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