mirror
/
go
mirror of https://github.com/golang/go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc/go1.11: shorten, tidy, and promote user annotation API 

Text based on CL 124655.

Change-Id: I7c4866ce829cb28a4c60cd8ced3ef99047a38c54
Reviewed-on: https://go-review.googlesource.com/124711
Reviewed-by: Austin Clements <austin@google.com>
This commit is contained in:
Austin Clements 2018-07-18 16:09:06 -04:00
parent 4016de0daf
commit 798f74b9e6
1 changed files with 12 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/go1.11.html
View File

@ -300,6 +300,18 @@ func f(v interface{}) {
a warning to be printed, and <code>vet</code> to exit with status 1.
</p>
<h3 id="trace">Trace</h3>
<p><!-- CL 63274 -->
With the new <code>runtime/trace</code>
package's <a href="/pkg/runtime/trace/#hdr-User_annotation">user
annotation API</a>, users can record application-level information
in execution traces and create groups of related goroutines.
The <code>go</code>&nbsp;<code>tool</code>&nbsp;<code>trace</code>
command visualizes this information in the trace view and the new
user task/span analysis page.
</p>
<h2 id="runtime">Runtime</h2>
<p><!-- CL 85887 -->
@ -696,65 +708,6 @@ for k := range m {
</dl><!-- runtime/pprof -->
<dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
<dd>
<p><!-- CL 63274 -->
This release adds a new user annotation API.
It introduces three basic building blocks: Log, Span, and Task.
</p>
<p>
Log is for basic logging. When called, the message will be recorded
to the trace along with timestamp, goroutine id, and stack info.
</p>
<pre>trace.Log(ctx, messageType message)</pre>
<p>
Span can be thought as an extension of log to record interesting
time interval during a goroutine's execution. A span is local to a
goroutine by definition.
</p>
<pre>
trace.WithSpan(ctx, "doVeryExpensiveOp", func(ctx context) {
/* do something very expensive */
})</pre>
<p>
Task is higher-level concept that aids tracing of complex operations
that encompass multiple goroutines or are asynchronous.
For example, an RPC request, a HTTP request, a file write, or a
batch job can be traced with a Task.
</p>
<p>
Note we chose to design the API around context.Context so it allows
easier integration with other tracing tools, often designed around
context.Context as well. Log and WithSpan APIs recognize the task
information embedded in the context and record it in the trace as
well. That allows the Go execution tracer to associate and group
the spans and log messages based on the task information.
</p>
<p>
In order to create a Task,
</p>
<pre>ctx, end := trace.NewContext(ctx, "myTask")
defer end()</pre>
<p>
The Go execution tracer measures the time between the task created
and the task ended for the task latency.
</p>
<p>
More discussion history is in <a href="https://golang.org/cl/59572">golang.org/cl/59572</a>.
</p>
</dl><!-- runtime/trace -->
<dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
<dd>
<p><!-- CL 87095 -->