runtime: document gctrace format

Fixes #10348.

Change-Id: I3eea9738e3f6fdc1998d04a601dc9b556dd2db72
Reviewed-on: https://go-review.googlesource.com/12453Reviewed-by: Russ Cox <rsc@golang.org>

src/runtime/extern.go

@@ -54,7 +54,23 @@ It is a comma-separated list of name=val pairs setting these named variables:
 	gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
 	error at each collection, summarizing the amount of memory collected and the
 	length of the pause. Setting gctrace=2 emits the same summary but also
-	repeats each collection.
+	repeats each collection. The format of this line is subject to change.
+	Currently, it is:
+		gc # @#s #%: #+...+# ms clock, #+...+# ms cpu, #->#-># MB, # MB goal, # P
+	where the fields are as follows:
+		gc #        the GC number, incremented at each GC
+		@#s         time in seconds since program start
+		#%          percentage of time spent in GC since program start
+		#+...+#     wall-clock/CPU times for the phases of the GC
+		#->#-># MB  heap size at GC start, at GC end, and live heap
+		# MB goal   goal heap size
+		# P         number of processors used
+	The phases are stop-the-world (STW) sweep termination, scan,
+	synchronize Ps, mark, and STW mark termination. The CPU times
+	for mark are broken down in to assist time (GC performed in
+	line with allocation), background GC time, and idle GC time.
+	If the line ends with "(forced)", this GC was forced by a
+	runtime.GC() call and all phases are STW.
 
 	memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate.
 	When set to 0 memory profiling is disabled.  Refer to the description of