docs(logging): Documentation for automatic trace/span ID extraction

logging/doc.go

@@ -146,5 +146,34 @@ parent.Timestamp marks the end of the request.)
 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.
+
+# Automatic Trace/Span ID Extraction
+
+You can automatically populate the Trace, SpanID, and TraceSampled fields of an Entry object by providing an [http.Request] object
+within the Entry's HTTPRequest field:
+
+	logging.Entry{
+		HTTPRequest: &logging.HTTPRequest{
+			Request: // Reference to your http.Request here
+		}
+	}
+
+When Entry with an [http.Request] is logged, its Trace, SpanID, and TraceSampled fields may be automatically populated as follows:
+
+ 1. If you are instrumenting your application with [OpenTelemetry], more specifically [otelhttp],
+    the Entry's Trace, SpanID, and TraceSampled will be populated with information from the [http.Request]'s span context.
+ 2. Trace, SpanID, and TraceSampled fields will be populated from information from the http.Request's [W3C Traceparent]
+    or [X-Cloud-Trace-Context] headers, if those headers exist.
+
+Note that if Trace, SpanID, or TraceSampled are explicitly provided within an Entry object, then those values take precedence over values automatically
+extracted values.
+
+[http.Request]: https://pkg.go.dev/net/http#Request
+[OpenTelemetry]: https://opentelemetry.io/docs/languages/go/
+[otelhttp]: https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
+[W3C Traceparent]: https://www.w3.org/TR/trace-context
+[X-Cloud-Trace-Context]: https://cloud.google.com/trace/docs/trace-context#legacy-http-header
+
+[OpenTelemetry span context]: https://pkg.go.dev/go.opentelemetry.io/otel/trace#SpanContext
 */
 package logging // import "cloud.google.com/go/logging"