diff options
author | Austin Clements <austin@google.com> | 2018-07-18 16:09:06 -0400 |
---|---|---|
committer | Austin Clements <austin@google.com> | 2018-07-18 20:11:46 +0000 |
commit | 798f74b9e6c714c7868a4e20870786bc7821bc32 (patch) | |
tree | c727b948ed9fedf5115962d7eb591357357d3fa1 | |
parent | 4016de0daffd46087e9ee9dc994e39c257191b40 (diff) | |
download | go-798f74b9e6c714c7868a4e20870786bc7821bc32.tar.gz go-798f74b9e6c714c7868a4e20870786bc7821bc32.zip |
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>
-rw-r--r-- | doc/go1.11.html | 71 |
1 files changed, 12 insertions, 59 deletions
diff --git a/doc/go1.11.html b/doc/go1.11.html index c62165af4e..a070442535 100644 --- a/doc/go1.11.html +++ b/doc/go1.11.html @@ -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> <code>tool</code> <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 --> |