github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/runtime/trace2.go (about)

     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  //go:build goexperiment.exectracer2
     6  
     7  // Go execution tracer.
     8  // The tracer captures a wide range of execution events like goroutine
     9  // creation/blocking/unblocking, syscall enter/exit/block, GC-related events,
    10  // changes of heap size, processor start/stop, etc and writes them to a buffer
    11  // in a compact form. A precise nanosecond-precision timestamp and a stack
    12  // trace is captured for most events.
    13  //
    14  // Tracer invariants (to keep the synchronization making sense):
    15  // - An m that has a trace buffer must be on either the allm or sched.freem lists.
    16  // - Any trace buffer mutation must either be happening in traceAdvance or between
    17  //   a traceAcquire and a subsequent traceRelease.
    18  // - traceAdvance cannot return until the previous generation's buffers are all flushed.
    19  //
    20  // See https://go.dev/issue/60773 for a link to the full design.
    21  
    22  package runtime
    23  
    24  // StartTrace enables tracing for the current process.
    25  // While tracing, the data will be buffered and available via [ReadTrace].
    26  // StartTrace returns an error if tracing is already enabled.
    27  // Most clients should use the [runtime/trace] package or the [testing] package's
    28  // -test.trace flag instead of calling StartTrace directly.
    29  func StartTrace() error
    30  
    31  // StopTrace stops tracing, if it was previously enabled.
    32  // StopTrace only returns after all the reads for the trace have completed.
    33  func StopTrace()
    34  
    35  // ReadTrace returns the next chunk of binary tracing data, blocking until data
    36  // is available. If tracing is turned off and all the data accumulated while it
    37  // was on has been returned, ReadTrace returns nil. The caller must copy the
    38  // returned data before calling ReadTrace again.
    39  // ReadTrace must be called from one goroutine at a time.
    40  func ReadTrace() []byte