src/internal/trace/v2/event/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         // 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 }