From 8848619b474e54b1c0afb7bdb4ccb7f2e5506036 Mon Sep 17 00:00:00 2001
From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com>
Date: Thu, 11 Jul 2024 17:00:57 -0700
Subject: [PATCH] docs: Documentation update for OpenTelemetry and tracing

---
 .readme-partials.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/.readme-partials.yaml b/.readme-partials.yaml
index 588c70420..7ba50520d 100644
--- a/.readme-partials.yaml
+++ b/.readme-partials.yaml
@@ -227,4 +227,20 @@ custom_content: |
         <artifactId>google-cloud-logging-servlet-initializer</artifactId>
       </dependency>      
       ```
+  #### Population of log entrys' trace/span Id
+  Cloud Logging libraries use [trace fields within LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace) to capture trace contexts, which enables the [correlation of logs and traces](https://cloud.google.com/logging/docs/view/correlate-logs), and distributed tracing troubleshooting. 
+  These tracing fields including [trace](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace), [spanId](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.span_id), and [traceSampled](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace_sampled) define the trace context for a `LogEntry`.
+  
+  The library provides three methods to update the context:
+  * Manually set trace/span Id
+  The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` methods provided by `Context.Builder`. Alternatively it can also be parsed from the [W3C tracing context header](https://www.w3.org/TR/trace-context) using `loadW3CTraceParentContext()` or from the [Google Cloud tracing context header](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) using `loadCloudTraceContext()`.
+  Tracing information set using this method will take precedence over other methods below.
+  
+  * Auto-population trace/span Id from OpenTelemetry context
+  If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, that log entry will automatically have the `trace`, `span_id`, and `trace_sampled` fields populated from that span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/).
+  
+  * Using [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers
+  If trace/span Id is not manually set or auto-populated from OpenTelemetry context, you can use [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) package to populate trace/span Id from HTTP headers.
+  This package filters all servlet requests to automatically capture the execution context of the servlet request and store it using ContextHandler class. Http request and trace/span Id information will be populated from the stored Context class instances.  
+  Using this method, trace/span Id can be automatically populated from either the [W3C Traceparent](https://www.w3.org/TR/trace-context) or [X-Cloud-Trace-Context](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) headers.