From 8476951ac1b33ea0c277a4ebed3c27c14ba2642f Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Thu, 11 Jul 2024 17:30:47 +0000 Subject: [PATCH 1/5] docs(logging): Documentation for automatic trace/span ID extraction --- logging/doc.go | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/logging/doc.go b/logging/doc.go index 343d99e0c64e..be454be9cd1f 100644 --- a/logging/doc.go +++ b/logging/doc.go @@ -146,5 +146,32 @@ 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 Metadata 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] and your http.Request's Context contains an [OpenTelemetry span context], + the Entry's Trace, SpanID, and TraceSampled will be populated with information from that 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, those values will take precedence over values automatically +extracted from the aforementioned process. + +[http.Request]: https://pkg.go.dev/net/http#Request +[OpenTelemetry]: https://opentelemetry.io/docs/languages/go/ +[OpenTelemetry span context]: https://pkg.go.dev/go.opentelemetry.io/otel/trace#SpanContext +[W3C Traceparent]: https://www.w3.org/TR/trace-context +[X-Cloud-Trace-Context]: https://cloud.google.com/trace/docs/trace-context#legacy-http-header */ package logging // import "cloud.google.com/go/logging" From 3bceeef6c517e58d1826c2716d6c2f551e7ed370 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Thu, 11 Jul 2024 18:41:04 +0000 Subject: [PATCH 2/5] updated documentation --- logging/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/logging/doc.go b/logging/doc.go index be454be9cd1f..7e15f34113cc 100644 --- a/logging/doc.go +++ b/logging/doc.go @@ -165,8 +165,8 @@ When Entry with an [http.Request] is logged, its Trace, SpanID, and TraceSampled 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, those values will take precedence over values automatically -extracted from the aforementioned process. +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/ From 035232ecce048cc8d372cd1d037d1e3a57397848 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Fri, 12 Jul 2024 17:43:25 +0000 Subject: [PATCH 3/5] addressed feedback --- logging/doc.go | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/logging/doc.go b/logging/doc.go index 7e15f34113cc..9c8a072c34a4 100644 --- a/logging/doc.go +++ b/logging/doc.go @@ -147,7 +147,7 @@ You should observe the child log entries grouped under the parent on the console parent entry will not inherit the severity of its children; you must update the parent severity yourself. -# Automatic Metadata Extraction +# 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: @@ -160,8 +160,8 @@ within the Entry's HTTPRequest field: 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] and your http.Request's Context contains an [OpenTelemetry span context], - the Entry's Trace, SpanID, and TraceSampled will be populated with information from that span context. + 1. If you are instrumenting your application with [OpenTelemetry], + 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. @@ -170,8 +170,9 @@ extracted values. [http.Request]: https://pkg.go.dev/net/http#Request [OpenTelemetry]: https://opentelemetry.io/docs/languages/go/ -[OpenTelemetry span context]: https://pkg.go.dev/go.opentelemetry.io/otel/trace#SpanContext [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" From 001cb1e6892782f750be64fcb6ea5dd93dc97628 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Mon, 15 Jul 2024 16:19:50 +0000 Subject: [PATCH 4/5] Changed OpenTelemetry to otelhttp --- logging/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/logging/doc.go b/logging/doc.go index 9c8a072c34a4..ca0a082dd667 100644 --- a/logging/doc.go +++ b/logging/doc.go @@ -160,7 +160,7 @@ within the Entry's HTTPRequest field: 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], + 1. If you are instrumenting your application with [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. @@ -169,7 +169,7 @@ Note that if Trace, SpanID, or TraceSampled are explicitly provided within an En 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 From 607d32897f0919003b71125cda0de493a994c0c5 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Mon, 15 Jul 2024 16:42:20 +0000 Subject: [PATCH 5/5] updated opentelemetry/otelhttp documentation --- logging/doc.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/logging/doc.go b/logging/doc.go index ca0a082dd667..2ed275b4d433 100644 --- a/logging/doc.go +++ b/logging/doc.go @@ -160,7 +160,7 @@ within the Entry's HTTPRequest field: 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 [otelhttp], + 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. @@ -169,6 +169,7 @@ Note that if Trace, SpanID, or TraceSampled are explicitly provided within an En 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