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 <[email protected]>
blinkinglight · Jul 18, 2018 · c7c147c · c7c147c
1 parent 96b5f6d
commit c7c147c
Showing 1 changed file with 52 additions and 1 deletion.
diff --git a/doc/go1.11.html b/doc/go1.11.html
@@ -666,7 +666,58 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
 <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 -->