From c7c147c83016384db29791e2006f9919c571512a Mon Sep 17 00:00:00 2001
From: Andrew Bonventre <andybons@golang.org>
Date: Wed, 18 Jul 2018 15:16:26 -0400
Subject: [PATCH] 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>
---
 doc/go1.11.html | 53 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

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 -->
-- 
2.50.0