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
7package runtime
8
9import (
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!
23type traceEv uint8
24
25const (
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.
98type 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.
104type 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.
121func (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.
134func (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.
140func (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.
146func (e traceEventWriter) end() {
147	e.w.end()
148}
149
150// traceEventWrite is the part of traceEvent that actually writes the event.
151func (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.
175func (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.
184func (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.
195func (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.
202func (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.
207func (tl traceLocker) rtype(typ *abi.Type) traceArg {
208	return traceArg(trace.typeTab[tl.gen%2].put(typ))
209}
210