chore(gax): add explanatory comments for tracer ordering and span scope lifecycle

Author: jinseopkim0

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java

@@ -298,6 +298,9 @@ static ApiTracerFactory getApiTracerFactory(
     ApiTracerFactory apiTracerFactory = settings.getTracerFactory();
 
     if (LoggingUtils.isLoggingEnabled()) {
+      // When an attempt ends, CompositeTracer calls tracers in reverse order.
+      // Placing LoggingTracerFactory second ensures logs are written before OpenTelemetry
+      // closes the active trace span.
       apiTracerFactory =
           new CompositeTracerFactory(
               ImmutableList.of(apiTracerFactory, new LoggingTracerFactory()));

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/tracing/OpenTelemetryTracingTracer.java

@@ -148,6 +148,7 @@ public void attemptStarted(Object request, int attemptNumber) {
     spanBuilder.setAllAttributes(ObservabilityUtils.toOtelAttributes(currentAttemptAttributes));
 
     this.attemptSpan = spanBuilder.startSpan();
+    // Make the span active on the current thread so logs can capture the trace ID.
     this.scope = attemptSpan.makeCurrent();
   }
 
@@ -241,6 +242,7 @@ private void endAttempt() {
       return;
     }
 
+    // Remove the span from the current thread before closing the span.
     try {
       if (scope != null) {
         scope.close();