new repository

1 files changed, 136 insertions, 0 deletions

diff --git a/devdocs/go/runtime%2Ftrace%2Findex.html b/devdocs/go/runtime%2Ftrace%2Findex.html
new file mode 100644
index 00000000..980aa1a1
--- /dev/null
+++ b/devdocs/go/runtime%2Ftrace%2Findex.html
@@ -0,0 +1,136 @@
+<h1> Package trace  </h1>     <ul id="short-nav">
+<li><code>import "runtime/trace"</code></li>
+<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
+<li><a href="#pkg-index" class="indexLink">Index</a></li>
+<li><a href="#pkg-examples" class="examplesLink">Examples</a></li>
+</ul>     <h2 id="pkg-overview">Overview </h2> <p>Package trace contains facilities for programs to generate traces for the Go execution tracer. </p>
+<h3 id="hdr-Tracing_runtime_activities">Tracing runtime activities</h3> <p>The execution trace captures a wide range of execution events such as goroutine creation/blocking/unblocking, syscall enter/exit/block, GC-related events, changes of heap size, processor start/stop, etc. When CPU profiling is active, the execution tracer makes an effort to include those samples as well. A precise nanosecond-precision timestamp and a stack trace is captured for most events. The generated trace can be interpreted using `go tool trace`. </p>
+<p>Support for tracing tests and benchmarks built with the standard testing package is built into `go test`. For example, the following command runs the test in the current directory and writes the trace file (trace.out). </p>
+<pre data-language="go">go test -trace=trace.out
+</pre> <p>This runtime/trace package provides APIs to add equivalent tracing support to a standalone program. See the Example that demonstrates how to use this API to enable tracing. </p>
+<p>There is also a standard HTTP interface to trace data. Adding the following line will install a handler under the /debug/pprof/trace URL to download a live trace: </p>
+<pre data-language="go">import _ "net/http/pprof"
+</pre> <p>See the <span>net/http/pprof</span> package for more details about all of the debug endpoints installed by this import. </p>
+<h3 id="hdr-User_annotation">User annotation</h3> <p>Package trace provides user annotation APIs that can be used to log interesting events during execution. </p>
+<p>There are three types of user annotations: log messages, regions, and tasks. </p>
+<p><a href="#Log">Log</a> emits a timestamped message to the execution trace along with additional information such as the category of the message and which goroutine called <a href="#Log">Log</a>. The execution tracer provides UIs to filter and group goroutines using the log category and the message supplied in <a href="#Log">Log</a>. </p>
+<p>A region is for logging a time interval during a goroutine's execution. By definition, a region starts and ends in the same goroutine. Regions can be nested to represent subintervals. For example, the following code records four regions in the execution trace to trace the durations of sequential steps in a cappuccino making operation. </p>
+<pre data-language="go">trace.WithRegion(ctx, "makeCappuccino", func() {
+
+   // orderID allows to identify a specific order
+   // among many cappuccino order region records.
+   trace.Log(ctx, "orderID", orderID)
+
+   trace.WithRegion(ctx, "steamMilk", steamMilk)
+   trace.WithRegion(ctx, "extractCoffee", extractCoffee)
+   trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
+})
+</pre> <p>A task is a higher-level component that aids tracing of logical operations such as an RPC request, an HTTP request, or an interesting local operation which may require multiple goroutines working together. Since tasks can involve multiple goroutines, they are tracked via a <span>context.Context</span> object. <a href="#NewTask">NewTask</a> creates a new task and embeds it in the returned <span>context.Context</span> object. Log messages and regions are attached to the task, if any, in the Context passed to <a href="#Log">Log</a> and <a href="#WithRegion">WithRegion</a>. </p>
+<p>For example, assume that we decided to froth milk, extract coffee, and mix milk and coffee in separate goroutines. With a task, the trace tool can identify the goroutines involved in a specific cappuccino order. </p>
+<pre data-language="go">ctx, task := trace.NewTask(ctx, "makeCappuccino")
+trace.Log(ctx, "orderID", orderID)
+
+milk := make(chan bool)
+espresso := make(chan bool)
+
+go func() {
+        trace.WithRegion(ctx, "steamMilk", steamMilk)
+        milk &lt;- true
+}()
+go func() {
+        trace.WithRegion(ctx, "extractCoffee", extractCoffee)
+        espresso &lt;- true
+}()
+go func() {
+        defer task.End() // When assemble is done, the order is complete.
+        &lt;-espresso
+        &lt;-milk
+        trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
+}()
+</pre> <p>The trace tool computes the latency of a task by measuring the time between the task creation and the task end and provides latency distributions for each task type found in the trace. </p>   <h4 id="example_"> <span class="text">Example</span>
+</h4> <p>Example demonstrates the use of the trace package to trace the execution of a Go program. The trace output will be written to the file trace.out </p> <p>Code:</p> <pre class="code" data-language="go">package trace_test
+
+import (
+    "fmt"
+    "log"
+    "os"
+    "runtime/trace"
+)
+
+// Example demonstrates the use of the trace package to trace
+// the execution of a Go program. The trace output will be
+// written to the file trace.out
+func Example() {
+    f, err := os.Create("trace.out")
+    if err != nil {
+        log.Fatalf("failed to create trace output file: %v", err)
+    }
+    defer func() {
+        if err := f.Close(); err != nil {
+            log.Fatalf("failed to close trace file: %v", err)
+        }
+    }()
+
+    if err := trace.Start(f); err != nil {
+        log.Fatalf("failed to start trace: %v", err)
+    }
+    defer trace.Stop()
+
+    // your program here
+    RunMyProgram()
+}
+
+func RunMyProgram() {
+    fmt.Printf("this function will be traced")
+}
+</pre>        <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
+<li><a href="#IsEnabled">func IsEnabled() bool</a></li>
+<li><a href="#Log">func Log(ctx context.Context, category, message string)</a></li>
+<li><a href="#Logf">func Logf(ctx context.Context, category, format string, args ...any)</a></li>
+<li><a href="#Start">func Start(w io.Writer) error</a></li>
+<li><a href="#Stop">func Stop()</a></li>
+<li><a href="#WithRegion">func WithRegion(ctx context.Context, regionType string, fn func())</a></li>
+<li><a href="#Region">type Region</a></li>
+<li> <a href="#StartRegion">func StartRegion(ctx context.Context, regionType string) *Region</a>
+</li>
+<li> <a href="#Region.End">func (r *Region) End()</a>
+</li>
+<li><a href="#Task">type Task</a></li>
+<li> <a href="#NewTask">func NewTask(pctx context.Context, taskType string) (ctx context.Context, task *Task)</a>
+</li>
+<li> <a href="#Task.End">func (t *Task) End()</a>
+</li>
+</ul> <div id="pkg-examples"> <h3>Examples</h3>  <dl> <dd><a class="exampleLink" href="#example_">Package</a></dd> </dl> </div> <h3>Package files</h3> <p>  <span>annotation.go</span> <span>trace.go</span>  </p>   <h2 id="IsEnabled">func <span>IsEnabled</span>  <span title="Added in Go 1.11">1.11</span> </h2> <pre data-language="go">func IsEnabled() bool</pre> <p>IsEnabled reports whether tracing is enabled. The information is advisory only. The tracing status may have changed by the time this function returns. </p>
+<h2 id="Log">func <span>Log</span>  <span title="Added in Go 1.11">1.11</span> </h2> <pre data-language="go">func Log(ctx context.Context, category, message string)</pre> <p>Log emits a one-off event with the given category and message. Category can be empty and the API assumes there are only a handful of unique categories in the system. </p>
+<h2 id="Logf">func <span>Logf</span>  <span title="Added in Go 1.11">1.11</span> </h2> <pre data-language="go">func Logf(ctx context.Context, category, format string, args ...any)</pre> <p>Logf is like <a href="#Log">Log</a>, but the value is formatted using the specified format spec. </p>
+<h2 id="Start">func <span>Start</span>  <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Start(w io.Writer) error</pre> <p>Start enables tracing for the current program. While tracing, the trace will be buffered and written to w. Start returns an error if tracing is already enabled. </p>
+<h2 id="Stop">func <span>Stop</span>  <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func Stop()</pre> <p>Stop stops the current tracing, if any. Stop only returns after all the writes for the trace have completed. </p>
+<h2 id="WithRegion">func <span>WithRegion</span>  <span title="Added in Go 1.11">1.11</span> </h2> <pre data-language="go">func WithRegion(ctx context.Context, regionType string, fn func())</pre> <p>WithRegion starts a region associated with its calling goroutine, runs fn, and then ends the region. If the context carries a task, the region is associated with the task. Otherwise, the region is attached to the background task. </p>
+<p>The regionType is used to classify regions, so there should be only a handful of unique region types. </p>
+<h2 id="Region">type <span>Region</span>  <span title="Added in Go 1.11">1.11</span> </h2> <p>Region is a region of code whose execution time interval is traced. </p>
+<pre data-language="go">type Region struct {
+    // contains filtered or unexported fields
+}
+</pre> <h3 id="StartRegion">func <span>StartRegion</span>  <span title="Added in Go 1.11">1.11</span> </h3> <pre data-language="go">func StartRegion(ctx context.Context, regionType string) *Region</pre> <p>StartRegion starts a region and returns it. The returned Region's <a href="#Region.End">Region.End</a> method must be called from the same goroutine where the region was started. Within each goroutine, regions must nest. That is, regions started after this region must be ended before this region can be ended. Recommended usage is </p>
+<pre data-language="go">defer trace.StartRegion(ctx, "myTracedRegion").End()
+</pre> <h3 id="Region.End">func (*Region) <span>End</span>  <span title="Added in Go 1.11">1.11</span> </h3> <pre data-language="go">func (r *Region) End()</pre> <p>End marks the end of the traced code region. </p>
+<h2 id="Task">type <span>Task</span>  <span title="Added in Go 1.11">1.11</span> </h2> <p>Task is a data type for tracing a user-defined, logical operation. </p>
+<pre data-language="go">type Task struct {
+    // contains filtered or unexported fields
+}
+</pre> <h3 id="NewTask">func <span>NewTask</span>  <span title="Added in Go 1.11">1.11</span> </h3> <pre data-language="go">func NewTask(pctx context.Context, taskType string) (ctx context.Context, task *Task)</pre> <p>NewTask creates a task instance with the type taskType and returns it along with a Context that carries the task. If the input context contains a task, the new task is its subtask. </p>
+<p>The taskType is used to classify task instances. Analysis tools like the Go execution tracer may assume there are only a bounded number of unique task types in the system. </p>
+<p>The returned Task's <a href="#Task.End">Task.End</a> method is used to mark the task's end. The trace tool measures task latency as the time between task creation and when the End method is called, and provides the latency distribution per task type. If the End method is called multiple times, only the first call is used in the latency measurement. </p>
+<pre data-language="go">ctx, task := trace.NewTask(ctx, "awesomeTask")
+trace.WithRegion(ctx, "preparation", prepWork)
+// preparation of the task
+go func() {  // continue processing the task in a separate goroutine.
+    defer task.End()
+    trace.WithRegion(ctx, "remainingWork", remainingWork)
+}()
+</pre> <h3 id="Task.End">func (*Task) <span>End</span>  <span title="Added in Go 1.11">1.11</span> </h3> <pre data-language="go">func (t *Task) End()</pre> <p>End marks the end of the operation represented by the <a href="#Task">Task</a>. </p><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
+    <a href="http://golang.org/pkg/runtime/trace/" class="_attribution-link">http://golang.org/pkg/runtime/trace/</a>
+  </p>
+</div>