docs(tracing): add Javadoc and explanatory comments for T3 operation spans

Author: jinseopkim0

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

@@ -71,6 +71,9 @@ class OpenTelemetryTracingTracer implements ApiTracer {
 
   @Override
   public void injectTraceContext(Map<String, String> carrier) {
+    // Prefer the active attempt span (T4) so outgoing RPC wire context reflects the specific
+    // attempt;
+    // fall back to the overall operation span (T3) if no attempt is currently in-flight.
     Span currentAttempt = attemptSpan;
     Span spanToInject = currentAttempt != null ? currentAttempt : operationSpan;
     if (spanToInject != null) {
@@ -90,6 +93,8 @@ public void injectTraceContext(Map<String, String> carrier) {
   @Override
   @SuppressWarnings("MustBeClosedChecker")
   public Scope inScope() {
+    // Attach the active attempt span to the current execution thread context;
+    // fall back to the overall operation span when between attempts.
     Span currentAttempt = attemptSpan;
     Span currentSpan = currentAttempt != null ? currentAttempt : operationSpan;
     if (currentSpan == null) {
@@ -180,6 +185,12 @@ private static String resolveOperationSpanName(String attemptSpanName) {
     return "operation";
   }
 
+  /**
+   * Resolves the canonical attempt-level span name based on transport and context.
+   *
+   * @param apiTracerContext the tracer context containing transport and method metadata
+   * @return the attempt span name
+   */
   private static String resolveAttemptSpanName(ApiTracerContext apiTracerContext) {
     if (apiTracerContext.transport() == ApiTracerContext.Transport.GRPC) {
       // gRPC Uses the full method name as span name.
@@ -195,6 +206,7 @@ private static String resolveAttemptSpanName(ApiTracerContext apiTracerContext)
     }
   }
 
+  /** Copies attempt-level attributes from the tracer context into the local attribute cache. */
   private void buildAttributes() {
     this.attemptAttributes.putAll(this.apiTracerContext.getAttemptAttributes());
   }

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/tracing/OpenTelemetryTracingTracerIntegrationTest.java

@@ -91,6 +91,8 @@ void tearDown() {
 
   @Test
   void testAttemptSpan_linkedToParentContextFromCallingThread() {
+    // Verifies that when an application trace parent exists, the operation span (T3)
+    // links to the application parent, and the attempt span (T4) links to the operation span.
     Span parentSpan = tracer.spanBuilder("application-parent-operation").startSpan();
     ApiTracer apiTracer;
     try (Scope scope = parentSpan.makeCurrent()) {
@@ -132,6 +134,8 @@ void testAttemptSpan_linkedToParentContextFromCallingThread() {
 
   @Test
   void testAttemptSpan_withoutParentContext_hasNoParent() {
+    // Verifies that without an external parent context, the operation span acts as root
+    // and the attempt span is a child of the operation span.
     ApiTracer apiTracer = tracingFactory.newTracer(BaseApiTracer.getInstance(), TRACER_CONTEXT);
 
     apiTracer.attemptStarted(new Object(), 0);
@@ -209,6 +213,8 @@ void testSequentialAttempts_closesPreviousAttemptSpanAndLinksAllToParent() {
 
   @Test
   void testOperationFailed_endsActiveAttemptSpanWithErrorAttributes() {
+    // Verifies that when the operation fails permanently while an attempt is in-flight,
+    // both the attempt span and the operation span end with the error status and message.
     Span parentSpan = tracer.spanBuilder("application-parent-operation").startSpan();
     ApiTracer apiTracer;
     try (Scope scope = parentSpan.makeCurrent()) {
@@ -245,6 +251,8 @@ void testOperationFailed_endsActiveAttemptSpanWithErrorAttributes() {
 
   @Test
   void testAttemptStarted_afterOperationCompleted_doesNotEmitNewSpan() {
+    // Verifies that after operation completion, subsequent attemptStarted calls
+    // do not create orphan attempt spans.
     ApiTracer apiTracer = tracingFactory.newTracer(BaseApiTracer.getInstance(), TRACER_CONTEXT);
 
     apiTracer.operationSucceeded();

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/tracing/OpenTelemetryTracingTracerTest.java

@@ -747,6 +747,7 @@ void testOperationCancelled_endsActiveAttemptSpanWithCancellation() {
 
   @Test
   void testInScope_withAttemptSpan() {
+    // Verifies that inScope() activates the current attempt span if an attempt is currently active.
     io.opentelemetry.context.Scope mockScope = mock(io.opentelemetry.context.Scope.class);
     when(span.makeCurrent()).thenReturn(mockScope);
 
@@ -759,6 +760,8 @@ void testInScope_withAttemptSpan() {
 
   @Test
   void testInScope_withOperationSpanFallback() {
+    // Verifies that inScope() falls back to activating the operation span when no attempt span is
+    // active.
     io.opentelemetry.context.Scope mockScope = mock(io.opentelemetry.context.Scope.class);
     when(operationSpan.makeCurrent()).thenReturn(mockScope);
 
@@ -770,6 +773,8 @@ void testInScope_withOperationSpanFallback() {
 
   @Test
   void testInjectTraceContext_withOperationSpanFallback() {
+    // Verifies that injectTraceContext() injects the operation span context into the carrier
+    // when between attempts so that context propagation doesn't drop trace state.
     io.opentelemetry.api.trace.SpanContext mockSpanContext =
         io.opentelemetry.api.trace.SpanContext.create(
             "00000000000000000000000000000003",
@@ -792,6 +797,8 @@ void testInjectTraceContext_withOperationSpanFallback() {
 
   @Test
   void testAttemptStarted_whenPreviousAttemptActive_closesOldSpan() {
+    // Verifies that starting a new retry attempt cleanly closes any lingering previous attempt
+    // span.
     Span span1 = mock(Span.class);
     Span span2 = mock(Span.class);
 
@@ -811,6 +818,7 @@ void testAttemptStarted_whenPreviousAttemptActive_closesOldSpan() {
 
   @Test
   void testAttemptStarted_afterOperationCompleted_doesNotStartNewSpan() {
+    // Verifies that after operation completion, late callbacks cannot spawn new attempt spans.
     openTelemetryTracingTracer.operationSucceeded();
 
     // Attempting to start a new attempt after operation completion should be a no-op