Name resolution delay

api/src/main/java/io/grpc/ClientStreamTracer.java

@@ -67,7 +67,7 @@ public void createPendingStream() {
    *
    * @param delayType canonical low-cardinality label categorizing the delay (e.g., "connecting")
    * @param delayReason high-cardinality diagnostic string describing granular runtime conditions
-   * @since 1.82.0
+   * @since 1.84.0
    */
   public void recordAttemptDelayStart(String delayType, String delayReason) {
   }
@@ -80,7 +80,7 @@ public void recordAttemptDelayStart(String delayType, String delayReason) {
    * on the active delay span without recreating the span or resetting cumulative timers.
    *
    * @param delayReason updated high-cardinality diagnostic string describing new conditions
-   * @since 1.82.0
+   * @since 1.84.0
    */
   public void recordAttemptDelayReasonChanged(String delayReason) {
   }
@@ -91,7 +91,7 @@ public void recordAttemptDelayReasonChanged(String delayReason) {
    * <p>Implementations should simultaneously close active child tracing spans and record elapsed
    * duration to the {@code grpc.client.attempt.delay.duration} histogram.
    *
-   * @since 1.82.0
+   * @since 1.84.0
    */
   public void recordAttemptDelayEnd() {
   }
@@ -156,6 +156,44 @@ public abstract static class Factory {
     public ClientStreamTracer newClientStreamTracer(StreamInfo info, Metadata headers) {
       throw new UnsupportedOperationException("Not implemented");
     }
+
+    /**
+     * Called when a call-level delay segment (such as waiting for name resolution or service
+     * configuration parsing) starts before any individual RPC attempt is created.
+     *
+     * <p>Implementations should start logical timers and create child tracing spans (named strictly
+     * {@code "Call Delay"}) carrying the canonical {@code grpc.delay_type} attribute.
+     *
+     * @param delayType canonical low-cardinality label categorizing the delay (e.g., "resolving")
+     * @param delayReason high-cardinality diagnostic string describing granular runtime conditions
+     * @since 1.84.0
+     */
+    public void recordCallDelayStart(String delayType, String delayReason) {
+    }
+
+    /**
+     * Called when a call-level delay reason changes while the active delay segment continues.
+     *
+     * <p>Implementations should emit structured events (such as {@code "Delay state transition"})
+     * on the active call delay span without recreating the span or resetting timers.
+     *
+     * @param delayReason updated high-cardinality diagnostic string describing new conditions
+     * @since 1.84.0
+     */
+    public void recordCallDelayReasonChanged(String delayReason) {
+    }
+
+    /**
+     * Called when a call-level delay segment ends upon successful name resolution or when an RPC
+     * is cancelled before resolution completes.
+     *
+     * <p>Implementations should close active call delay spans and record elapsed duration to the
+     * {@code grpc.client.call.delay.duration} histogram.
+     *
+     * @since 1.84.0
+     */
+    public void recordCallDelayEnd() {
+    }
   }
 
   /**

api/src/main/java/io/grpc/LoadBalancer.java

@@ -739,7 +739,7 @@ public static PickResult withNoResult() {
      *
      * @param delayType low-cardinality root cause label (e.g., "connecting")
      * @param delayReason high-cardinality diagnostic string for trace events
-     * @since 1.82.0
+     * @since 1.84.0
      */
     public static PickResult withNoResult(String delayType, String delayReason) {
       Preconditions.checkNotNull(delayType, "delayType");

api/src/test/java/io/grpc/ClientStreamTracerTest.java

@@ -57,4 +57,17 @@ public void streamInfo_toBuilder() {
     StreamInfo info2 = info1.toBuilder().build();
     assertThat(info2.getCallOptions()).isSameInstanceAs(callOptions);
   }
+
+  @Test
+  public void defaultDelayMethodsNoOp() {
+    ClientStreamTracer tracer = new ClientStreamTracer() {};
+    tracer.recordAttemptDelayStart("connecting", "test");
+    tracer.recordAttemptDelayReasonChanged("test2");
+    tracer.recordAttemptDelayEnd();
+
+    ClientStreamTracer.Factory factory = new ClientStreamTracer.Factory() {};
+    factory.recordCallDelayStart("resolving", "test");
+    factory.recordCallDelayReasonChanged("test2");
+    factory.recordCallDelayEnd();
+  }
 }

core/src/main/java/io/grpc/internal/DelayedClientTransport.java

@@ -396,7 +396,7 @@ private static String determineQueuingDelayReason(@Nullable PickResult pickResul
     return "client channel: waiting for picker";
   }
 
-  private class PendingStream extends DelayedStream {
+  class PendingStream extends DelayedStream {
     private final PickSubchannelArgs args;
     private final Context context = Context.current();
     private final ClientStreamTracer[] tracers;
@@ -405,6 +405,8 @@ private class PendingStream extends DelayedStream {
     @Nullable private String activeDelayType;
     @GuardedBy("this")
     @Nullable private String activeDelayReason;
+    @GuardedBy("this")
+    private boolean delayEnded;
 
     private PendingStream(PickSubchannelArgs args, ClientStreamTracer[] tracers,
         @Nullable String initialType, @Nullable String initialReason) {
@@ -428,11 +430,11 @@ private PendingStream(PickSubchannelArgs args, ClientStreamTracer[] tracers,
      * structured transition event is appended to the active span without span re-creation.
      */
     synchronized void updateDelay(@Nullable String newType, @Nullable String newReason) {
-      if (getRealStream() != null) {
+      if (getRealStream() != null || delayEnded) {
         return;
       }
+      // Delay type changed (e.g., from RLS lookup to connecting). End the previous delay.
       if (!Objects.equals(activeDelayType, newType)) {
-        // Delay type changed (e.g., from RLS lookup to connecting). End the previous delay.
         if (activeDelayType != null) {
           for (ClientStreamTracer tracer : tracers) {
             tracer.recordAttemptDelayEnd();
@@ -446,8 +448,9 @@ synchronized void updateDelay(@Nullable String newType, @Nullable String newReas
           }
         }
       }
-      if (newType != null && newReason != null && !Objects.equals(activeDelayReason, newReason)) {
-        // Delay type is unchanged, but the reason changed (e.g., priority failover).
+      // Delay type is unchanged, but the reason changed (e.g., priority failover).
+      if (newType != null && newReason != null
+          && !Objects.equals(activeDelayReason, newReason)) {
         activeDelayReason = newReason;
         for (ClientStreamTracer tracer : tracers) {
           tracer.recordAttemptDelayReasonChanged(newReason);
@@ -459,6 +462,10 @@ synchronized void updateDelay(@Nullable String newType, @Nullable String newReas
      * Ends active attempt delay segment telemetry upon stream creation or stream cancellation.
      */
     synchronized void endDelay() {
+      if (delayEnded) {
+        return;
+      }
+      delayEnded = true;
       if (activeDelayType != null) {
         for (ClientStreamTracer tracer : tracers) {
           tracer.recordAttemptDelayEnd();
@@ -469,8 +476,9 @@ synchronized void endDelay() {
     }
 
     Runnable setStreamAndEndDelay(ClientStream stream) {
+      Runnable runnable = setStream(stream);
       endDelay();
-      return setStream(stream);
+      return runnable;
     }
 
     /** Runnable may be null. */

core/src/main/java/io/grpc/internal/ManagedChannelImpl.java

@@ -918,6 +918,7 @@ public void run() {
               inUseStateAggregator.updateObjectInUse(pendingCallsInUseObject, true);
             }
             pendingCalls.add(pendingCall);
+            pendingCall.notifyQueuedForNameResolution();
           } else {
             pendingCall.reprocess();
           }
@@ -997,6 +998,9 @@ private final class PendingCall<ReqT, RespT> extends DelayedClientCall<ReqT, Res
       final MethodDescriptor<ReqT, RespT> method;
       final CallOptions callOptions;
       private final long callCreationTime;
+      private volatile boolean queuedForResolution;
+      private volatile boolean callCancelled;
+      private final AtomicBoolean delayEnded = new AtomicBoolean();
 
       PendingCall(Context context, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions) {
         super(
@@ -1010,14 +1014,42 @@ private final class PendingCall<ReqT, RespT> extends DelayedClientCall<ReqT, Res
         this.callCreationTime = ticker.nanoTime();
       }
 
+      void notifyQueuedForNameResolution() {
+        boolean shouldStart = false;
+        synchronized (this) {
+          if (!callCancelled && !queuedForResolution) {
+            queuedForResolution = true;
+            shouldStart = true;
+          }
+        }
+        if (shouldStart) {
+          for (ClientStreamTracer.Factory factory : callOptions.getStreamTracerFactories()) {
+            factory.recordCallDelayStart(
+                "resolving", "waiting for name resolution or service config");
+          }
+        }
+      }
+
+      private void endDelayIfNeeded() {
+        if (queuedForResolution && delayEnded.compareAndSet(false, true)) {
+          for (ClientStreamTracer.Factory factory : callOptions.getStreamTracerFactories()) {
+            factory.recordCallDelayEnd();
+          }
+        }
+      }
+
       /** Called when it's ready to create a real call and reprocess the pending call. */
       void reprocess() {
+        endDelayIfNeeded();
         ClientCall<ReqT, RespT> realCall;
         Context previous = context.attach();
         try {
-          CallOptions delayResolutionOption = callOptions.withOption(NAME_RESOLUTION_DELAYED,
-              ticker.nanoTime() - callCreationTime);
-          realCall = newClientCall(method, delayResolutionOption);
+          CallOptions effectiveOptions = callOptions;
+          if (queuedForResolution) {
+            effectiveOptions = callOptions.withOption(NAME_RESOLUTION_DELAYED,
+                ticker.nanoTime() - callCreationTime);
+          }
+          realCall = newClientCall(method, effectiveOptions);
         } finally {
           context.detach(previous);
         }
@@ -1037,6 +1069,10 @@ public void run() {
 
       @Override
       protected void callCancelled() {
+        synchronized (this) {
+          callCancelled = true;
+        }
+        endDelayIfNeeded();
         super.callCancelled();
         syncContext.execute(new PendingCallRemoval());
       }

core/src/test/java/io/grpc/internal/DelayedClientTransportTest.java

@@ -972,6 +972,86 @@ public PickResult pickSubchannel(PickSubchannelArgs args) {
     assertEquals(1, fakeTracer.delayEndedCount);
   }
 
+  @Test
+  public void streamDelayMetrics_allBranchCombinations() {
+    FakeStreamTracer fakeTracer = new FakeStreamTracer();
+    ClientStreamTracer[] customTracers = new ClientStreamTracer[] { fakeTracer };
+
+    // 1. Initial stream with no picker set (initialType defaults to "connecting")
+    ClientStream stream = delayedTransport.newStream(method, headers, callOptions, customTracers);
+    stream.start(streamListener);
+
+    assertEquals(Collections.singletonList("connecting"), fakeTracer.startedDelayTypes);
+    assertEquals(Collections.singletonList("client channel: waiting for picker"),
+        fakeTracer.startedDelayReasons);
+
+    // 2. Reprocess with same delay type ("connecting") but new reason ("attempting to connect")
+    delayedTransport.reprocess(fakePicker(
+        PickResult.withNoResult("connecting", "attempting to connect")));
+    assertEquals(Collections.singletonList("attempting to connect"),
+        fakeTracer.changedDelayReasons);
+
+    // 3. Reprocess with a different delay type ("rls_lookup_pending")
+    delayedTransport.reprocess(fakePicker(
+        PickResult.withNoResult("rls_lookup_pending", "RLS pending")));
+    assertEquals(1, fakeTracer.delayEndedCount);
+    assertEquals(Arrays.asList("connecting", "rls_lookup_pending"), fakeTracer.startedDelayTypes);
+
+    // 4. Reprocess with default PickResult.withNoResult() (defaults to "connecting")
+    delayedTransport.reprocess(fakePicker(PickResult.withNoResult()));
+    assertEquals(2, fakeTracer.delayEndedCount);
+
+    // 5. Cancel stream ends active delay
+    stream.cancel(Status.CANCELLED);
+    assertEquals(3, fakeTracer.delayEndedCount);
+
+    // 6. Direct updateDelay with null type and null reason
+    fakeTracer = new FakeStreamTracer();
+    customTracers = new ClientStreamTracer[] { fakeTracer };
+    ClientStream stream2 = delayedTransport.newStream(method, headers, callOptions, customTracers);
+    fakeTracer.startedDelayTypes.clear();
+    stream2.start(streamListener);
+
+    // Explicitly update delay to null
+    delayedTransport.reprocess(fakePicker(PickResult.withNoResult()));
+
+    // 7. Cancel stream2 (endDelay when activeDelayType is null)
+    stream2.cancel(Status.CANCELLED);
+  }
+
+  @Test
+  public void streamDelayMetrics_emptyTracersAndNullInitialReason() {
+    ClientStreamTracer[] emptyTracers = new ClientStreamTracer[0];
+    delayedTransport.reprocess(fakePicker(PickResult.withNoResult("resolving", "")));
+    ClientStream stream = delayedTransport.newStream(method, headers, callOptions, emptyTracers);
+    stream.start(streamListener);
+
+    // Update delay with empty tracers and empty reason
+    delayedTransport.reprocess(fakePicker(PickResult.withNoResult("connecting", "")));
+    stream.cancel(Status.CANCELLED);
+  }
+
+  @Test
+  public void streamDelayMetrics_delayEndedWhileRealStreamNull_updateDelayReturnsEarly() {
+    FakeStreamTracer fakeTracer = new FakeStreamTracer();
+    ClientStreamTracer[] customTracers = new ClientStreamTracer[] { fakeTracer };
+
+    DelayedClientTransport.PendingStream pendingStream =
+        (DelayedClientTransport.PendingStream) delayedTransport.newStream(
+            method, headers, callOptions, customTracers);
+    pendingStream.start(streamListener);
+
+    // End delay directly while realStream is still null (sets delayEnded = true)
+    pendingStream.endDelay();
+    assertEquals(1, fakeTracer.delayEndedCount);
+
+    // updateDelay after delayEnded when getRealStream() == null should return early
+    // without starting a new delay segment
+    pendingStream.updateDelay("connecting", "new reason");
+    assertEquals(Collections.singletonList("connecting"), fakeTracer.startedDelayTypes);
+    assertEquals(1, fakeTracer.delayEndedCount);
+  }
+
   private static TransportProvider newTransportProvider(final ClientTransport transport) {
     return new TransportProvider() {
       @Override

core/src/test/java/io/grpc/internal/ForwardingClientStreamTracerTest.java

@@ -17,6 +17,7 @@
 package io.grpc.internal;
 
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
 
 import io.grpc.ClientStreamTracer;
 import io.grpc.ForwardingTestUtil;
@@ -40,6 +41,19 @@ public void allMethodsForwarded() throws Exception {
         Collections.<Method>emptyList());
   }
 
+  @Test
+  public void attemptDelayMethodsForwarded() {
+    TestClientStreamTracer tracer = new TestClientStreamTracer();
+    tracer.recordAttemptDelayStart("connecting", "test");
+    verify(mockDelegate).recordAttemptDelayStart("connecting", "test");
+
+    tracer.recordAttemptDelayReasonChanged("test2");
+    verify(mockDelegate).recordAttemptDelayReasonChanged("test2");
+
+    tracer.recordAttemptDelayEnd();
+    verify(mockDelegate).recordAttemptDelayEnd();
+  }
+
   private final class TestClientStreamTracer extends ForwardingClientStreamTracer {
     @Override
     protected ClientStreamTracer delegate() {