traceevent.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  // Trace event writing API for trace2runtime.go.
     6  
     7  package runtime
     8  
     9  import (
    10  	"internal/abi"
    11  	"runtime/internal/sys"
    12  )
    13  
    14  // Event types in the trace, args are given in square brackets.
    15  //
    16  // Naming scheme:
    17  //   - Time range event pairs have suffixes "Begin" and "End".
    18  //   - "Start", "Stop", "Create", "Destroy", "Block", "Unblock"
    19  //     are suffixes reserved for scheduling resources.
    20  //
    21  // NOTE: If you add an event type, make sure you also update all
    22  // tables in this file!
    23  type traceEv uint8
    24  
    25  const (
    26  	traceEvNone traceEv = iota // unused
    27  
    28  	// Structural events.
    29  	traceEvEventBatch // start of per-M batch of events [generation, M ID, timestamp, batch length]
    30  	traceEvStacks     // start of a section of the stack table [...traceEvStack]
    31  	traceEvStack      // stack table entry [ID, ...{PC, func string ID, file string ID, line #}]
    32  	traceEvStrings    // start of a section of the string dictionary [...traceEvString]
    33  	traceEvString     // string dictionary entry [ID, length, string]
    34  	traceEvCPUSamples // start of a section of CPU samples [...traceEvCPUSample]
    35  	traceEvCPUSample  // CPU profiling sample [timestamp, M ID, P ID, goroutine ID, stack ID]
    36  	traceEvFrequency  // timestamp units per sec [freq]
    37  
    38  	// Procs.
    39  	traceEvProcsChange // current value of GOMAXPROCS [timestamp, GOMAXPROCS, stack ID]
    40  	traceEvProcStart   // start of P [timestamp, P ID, P seq]
    41  	traceEvProcStop    // stop of P [timestamp]
    42  	traceEvProcSteal   // P was stolen [timestamp, P ID, P seq, M ID]
    43  	traceEvProcStatus  // P status at the start of a generation [timestamp, P ID, status]
    44  
    45  	// Goroutines.
    46  	traceEvGoCreate            // goroutine creation [timestamp, new goroutine ID, new stack ID, stack ID]
    47  	traceEvGoCreateSyscall     // goroutine appears in syscall (cgo callback) [timestamp, new goroutine ID]
    48  	traceEvGoStart             // goroutine starts running [timestamp, goroutine ID, goroutine seq]
    49  	traceEvGoDestroy           // goroutine ends [timestamp]
    50  	traceEvGoDestroySyscall    // goroutine ends in syscall (cgo callback) [timestamp]
    51  	traceEvGoStop              // goroutine yields its time, but is runnable [timestamp, reason, stack ID]
    52  	traceEvGoBlock             // goroutine blocks [timestamp, reason, stack ID]
    53  	traceEvGoUnblock           // goroutine is unblocked [timestamp, goroutine ID, goroutine seq, stack ID]
    54  	traceEvGoSyscallBegin      // syscall enter [timestamp, P seq, stack ID]
    55  	traceEvGoSyscallEnd        // syscall exit [timestamp]
    56  	traceEvGoSyscallEndBlocked // syscall exit and it blocked at some point [timestamp]
    57  	traceEvGoStatus            // goroutine status at the start of a generation [timestamp, goroutine ID, M ID, status]
    58  
    59  	// STW.
    60  	traceEvSTWBegin // STW start [timestamp, kind]
    61  	traceEvSTWEnd   // STW done [timestamp]
    62  
    63  	// GC events.
    64  	traceEvGCActive           // GC active [timestamp, seq]
    65  	traceEvGCBegin            // GC start [timestamp, seq, stack ID]
    66  	traceEvGCEnd              // GC done [timestamp, seq]
    67  	traceEvGCSweepActive      // GC sweep active [timestamp, P ID]
    68  	traceEvGCSweepBegin       // GC sweep start [timestamp, stack ID]
    69  	traceEvGCSweepEnd         // GC sweep done [timestamp, swept bytes, reclaimed bytes]
    70  	traceEvGCMarkAssistActive // GC mark assist active [timestamp, goroutine ID]
    71  	traceEvGCMarkAssistBegin  // GC mark assist start [timestamp, stack ID]
    72  	traceEvGCMarkAssistEnd    // GC mark assist done [timestamp]
    73  	traceEvHeapAlloc          // gcController.heapLive change [timestamp, heap alloc in bytes]
    74  	traceEvHeapGoal           // gcController.heapGoal() change [timestamp, heap goal in bytes]
    75  
    76  	// Annotations.
    77  	traceEvGoLabel         // apply string label to current running goroutine [timestamp, label string ID]
    78  	traceEvUserTaskBegin   // trace.NewTask [timestamp, internal task ID, internal parent task ID, name string ID, stack ID]
    79  	traceEvUserTaskEnd     // end of a task [timestamp, internal task ID, stack ID]
    80  	traceEvUserRegionBegin // trace.{Start,With}Region [timestamp, internal task ID, name string ID, stack ID]
    81  	traceEvUserRegionEnd   // trace.{End,With}Region [timestamp, internal task ID, name string ID, stack ID]
    82  	traceEvUserLog         // trace.Log [timestamp, internal task ID, key string ID, stack, value string ID]
    83  
    84  	// Coroutines.
    85  	traceEvGoSwitch        // goroutine switch (coroswitch) [timestamp, goroutine ID, goroutine seq]
    86  	traceEvGoSwitchDestroy // goroutine switch and destroy [timestamp, goroutine ID, goroutine seq]
    87  	traceEvGoCreateBlocked // goroutine creation (starts blocked) [timestamp, new goroutine ID, new stack ID, stack ID]
    88  
    89  	// GoStatus with stack.
    90  	traceEvGoStatusStack // goroutine status at the start of a generation, with a stack [timestamp, goroutine ID, M ID, status, stack ID]
    91  
    92  	// Batch event for an experimental batch with a custom format.
    93  	traceEvExperimentalBatch // start of extra data [experiment ID, generation, M ID, timestamp, batch length, batch data...]
    94  )
    95  
    96  // traceArg is a simple wrapper type to help ensure that arguments passed
    97  // to traces are well-formed.
    98  type traceArg uint64
    99  
   100  // traceEventWriter is the high-level API for writing trace events.
   101  //
   102  // See the comment on traceWriter about style for more details as to why
   103  // this type and its methods are structured the way they are.
   104  type traceEventWriter struct {
   105  	w traceWriter
   106  }
   107  
   108  // eventWriter creates a new traceEventWriter. It is the main entrypoint for writing trace events.
   109  //
   110  // Before creating the event writer, this method will emit a status for the current goroutine
   111  // or proc if it exists, and if it hasn't had its status emitted yet. goStatus and procStatus indicate
   112  // what the status of goroutine or P should be immediately *before* the events that are about to
   113  // be written using the eventWriter (if they exist). No status will be written if there's no active
   114  // goroutine or P.
   115  //
   116  // Callers can elect to pass a constant value here if the status is clear (e.g. a goroutine must have
   117  // been Runnable before a GoStart). Otherwise, callers can query the status of either the goroutine
   118  // or P and pass the appropriate status.
   119  //
   120  // In this case, the default status should be traceGoBad or traceProcBad to help identify bugs sooner.
   121  func (tl traceLocker) eventWriter(goStatus traceGoStatus, procStatus traceProcStatus) traceEventWriter {
   122  	w := tl.writer()
   123  	if pp := tl.mp.p.ptr(); pp != nil && !pp.trace.statusWasTraced(tl.gen) && pp.trace.acquireStatus(tl.gen) {
   124  		w = w.writeProcStatus(uint64(pp.id), procStatus, pp.trace.inSweep)
   125  	}
   126  	if gp := tl.mp.curg; gp != nil && !gp.trace.statusWasTraced(tl.gen) && gp.trace.acquireStatus(tl.gen) {
   127  		w = w.writeGoStatus(uint64(gp.goid), int64(tl.mp.procid), goStatus, gp.inMarkAssist, 0 /* no stack */)
   128  	}
   129  	return traceEventWriter{w}
   130  }
   131  
   132  // commit writes out a trace event and calls end. It's a helper to make the
   133  // common case of writing out a single event less error-prone.
   134  func (e traceEventWriter) commit(ev traceEv, args ...traceArg) {
   135  	e = e.write(ev, args...)
   136  	e.end()
   137  }
   138  
   139  // write writes an event into the trace.
   140  func (e traceEventWriter) write(ev traceEv, args ...traceArg) traceEventWriter {
   141  	e.w = e.w.event(ev, args...)
   142  	return e
   143  }
   144  
   145  // end finishes writing to the trace. The traceEventWriter must not be used after this call.
   146  func (e traceEventWriter) end() {
   147  	e.w.end()
   148  }
   149  
   150  // traceEventWrite is the part of traceEvent that actually writes the event.
   151  func (w traceWriter) event(ev traceEv, args ...traceArg) traceWriter {
   152  	// Make sure we have room.
   153  	w, _ = w.ensure(1 + (len(args)+1)*traceBytesPerNumber)
   154  
   155  	// Compute the timestamp diff that we'll put in the trace.
   156  	ts := traceClockNow()
   157  	if ts <= w.traceBuf.lastTime {
   158  		ts = w.traceBuf.lastTime + 1
   159  	}
   160  	tsDiff := uint64(ts - w.traceBuf.lastTime)
   161  	w.traceBuf.lastTime = ts
   162  
   163  	// Write out event.
   164  	w.byte(byte(ev))
   165  	w.varint(tsDiff)
   166  	for _, arg := range args {
   167  		w.varint(uint64(arg))
   168  	}
   169  	return w
   170  }
   171  
   172  // stack takes a stack trace skipping the provided number of frames.
   173  // It then returns a traceArg representing that stack which may be
   174  // passed to write.
   175  func (tl traceLocker) stack(skip int) traceArg {
   176  	return traceArg(traceStack(skip, nil, tl.gen))
   177  }
   178  
   179  // startPC takes a start PC for a goroutine and produces a unique
   180  // stack ID for it.
   181  //
   182  // It then returns a traceArg representing that stack which may be
   183  // passed to write.
   184  func (tl traceLocker) startPC(pc uintptr) traceArg {
   185  	// +PCQuantum because makeTraceFrame expects return PCs and subtracts PCQuantum.
   186  	return traceArg(trace.stackTab[tl.gen%2].put([]uintptr{
   187  		logicalStackSentinel,
   188  		startPCForTrace(pc) + sys.PCQuantum,
   189  	}))
   190  }
   191  
   192  // string returns a traceArg representing s which may be passed to write.
   193  // The string is assumed to be relatively short and popular, so it may be
   194  // stored for a while in the string dictionary.
   195  func (tl traceLocker) string(s string) traceArg {
   196  	return traceArg(trace.stringTab[tl.gen%2].put(tl.gen, s))
   197  }
   198  
   199  // uniqueString returns a traceArg representing s which may be passed to write.
   200  // The string is assumed to be unique or long, so it will be written out to
   201  // the trace eagerly.
   202  func (tl traceLocker) uniqueString(s string) traceArg {
   203  	return traceArg(trace.stringTab[tl.gen%2].emit(tl.gen, s))
   204  }
   205  
   206  // rtype returns a traceArg representing typ which may be passed to write.
   207  func (tl traceLocker) rtype(typ *abi.Type) traceArg {
   208  	return traceArg(trace.typeTab[tl.gen%2].put(typ))
   209  }
   210
View as plain text