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  	"internal/runtime/sys"
    12  	"internal/trace/tracev2"
    13  )
    14  
    15  // traceArg is a simple wrapper type to help ensure that arguments passed
    16  // to traces are well-formed.
    17  type traceArg uint64
    18  
    19  // traceEventWriter is the high-level API for writing trace events.
    20  //
    21  // See the comment on traceWriter about style for more details as to why
    22  // this type and its methods are structured the way they are.
    23  type traceEventWriter struct {
    24  	tl traceLocker
    25  }
    26  
    27  // eventWriter creates a new traceEventWriter. It is the main entrypoint for writing trace events.
    28  //
    29  // Before creating the event writer, this method will emit a status for the current goroutine
    30  // or proc if it exists, and if it hasn't had its status emitted yet. goStatus and procStatus indicate
    31  // what the status of goroutine or P should be immediately *before* the events that are about to
    32  // be written using the eventWriter (if they exist). No status will be written if there's no active
    33  // goroutine or P.
    34  //
    35  // Callers can elect to pass a constant value here if the status is clear (e.g. a goroutine must have
    36  // been Runnable before a GoStart). Otherwise, callers can query the status of either the goroutine
    37  // or P and pass the appropriate status.
    38  //
    39  // In this case, the default status should be tracev2.GoBad or tracev2.ProcBad to help identify bugs sooner.
    40  func (tl traceLocker) eventWriter(goStatus tracev2.GoStatus, procStatus tracev2.ProcStatus) traceEventWriter {
    41  	if pp := tl.mp.p.ptr(); pp != nil && !pp.trace.statusWasTraced(tl.gen) && pp.trace.acquireStatus(tl.gen) {
    42  		tl.writer().writeProcStatus(uint64(pp.id), procStatus, pp.trace.inSweep).end()
    43  	}
    44  	if gp := tl.mp.curg; gp != nil && !gp.trace.statusWasTraced(tl.gen) && gp.trace.acquireStatus(tl.gen) {
    45  		tl.writer().writeGoStatus(gp.goid, int64(tl.mp.procid), goStatus, gp.inMarkAssist, 0 /* no stack */).end()
    46  	}
    47  	return tl.rawEventWriter()
    48  }
    49  
    50  // rawEventWriter creates a new traceEventWriter without emitting any status events.
    51  //
    52  // It is the caller's responsibility to emit any status events, if necessary.
    53  func (tl traceLocker) rawEventWriter() traceEventWriter {
    54  	return traceEventWriter{tl}
    55  }
    56  
    57  // event writes out a trace event.
    58  func (e traceEventWriter) event(ev tracev2.EventType, args ...traceArg) {
    59  	e.tl.writer().event(ev, args...).end()
    60  }
    61  
    62  // stack takes a stack trace skipping the provided number of frames.
    63  // It then returns a traceArg representing that stack which may be
    64  // passed to write.
    65  func (tl traceLocker) stack(skip int) traceArg {
    66  	return traceArg(traceStack(skip, nil, &trace.stackTab[tl.gen%2]))
    67  }
    68  
    69  // startPC takes a start PC for a goroutine and produces a unique
    70  // stack ID for it.
    71  //
    72  // It then returns a traceArg representing that stack which may be
    73  // passed to write.
    74  func (tl traceLocker) startPC(pc uintptr) traceArg {
    75  	// +PCQuantum because makeTraceFrame expects return PCs and subtracts PCQuantum.
    76  	return traceArg(trace.stackTab[tl.gen%2].put([]uintptr{
    77  		logicalStackSentinel,
    78  		startPCForTrace(pc) + sys.PCQuantum,
    79  	}))
    80  }
    81  
    82  // string returns a traceArg representing s which may be passed to write.
    83  // The string is assumed to be relatively short and popular, so it may be
    84  // stored for a while in the string dictionary.
    85  func (tl traceLocker) string(s string) traceArg {
    86  	return traceArg(trace.stringTab[tl.gen%2].put(tl.gen, s))
    87  }
    88  
    89  // uniqueString returns a traceArg representing s which may be passed to write.
    90  // The string is assumed to be unique or long, so it will be written out to
    91  // the trace eagerly.
    92  func (tl traceLocker) uniqueString(s string) traceArg {
    93  	return traceArg(trace.stringTab[tl.gen%2].emit(tl.gen, s))
    94  }
    95  
    96  // rtype returns a traceArg representing typ which may be passed to write.
    97  func (tl traceLocker) rtype(typ *abi.Type) traceArg {
    98  	return traceArg(trace.typeTab[tl.gen%2].put(typ))
    99  }
   100
View as plain text