doc: update go1.11.html with user annotation API additions

Change-Id: I357eea0efb04392e1a4671d20190a2052bf548de
Reviewed-on: https://go-review.googlesource.com/124706
Reviewed-by: Andrew Bonventre <andybons@golang.org>

1 files changed, 52 insertions, 1 deletions

diff --git a/doc/go1.11.html b/doc/go1.11.html
index df5cede349..a6dd66e8f3 100644
--- a/doc/go1.11.html
+++ b/doc/go1.11.html
@@ -666,7 +666,58 @@ func f(v interface{}) {
 <dl id="runtime/trace"><dt><a href="/pkg/runtime/trace/">runtime/trace</a></dt>
   <dd>
     <p><!-- CL 63274 -->
-      TODO: <a href="https://golang.org/cl/63274">https://golang.org/cl/63274</a>: user annotation API
+      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 -->