logging: document per-request logging
Fixes
@@ -113,5 +113,22 @@ running from a Google Cloud Platform VM, select "GCE VM Instance". Otherwise, se
accounts can be viewed on the command line with the "gcloud logging read" command.
+Grouping Logs by Request
+
+To group all the log entries written during a single HTTP request, create two
+Loggers, a "parent" and a "child," with different log IDs. Both should be in the same
+project, and have the same MonitoredResouce type and labels.
+
+- Parent entries must have HTTPRequest.Request populated. (Strictly speaking, only the URL is necessary.)
+
+- A child entry's timestamp must be within the time interval covered by the parent request (i.e., older
+ than parent.Timestamp, and newer than parent.Timestamp - parent.HTTPRequest.Latency, assuming the
+ parent timestamp marks the end of the request.
+
+- The trace field must be populated in all of the entries and match exactly.
+
+You should observe the child log entries grouped under the parent on the console. The
+parent entry will not inherit the severity of its children; you must update the
+parent severity yourself.
*/
package logging // import "cloud.google.com/go/logging"
