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

@@ -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) {
@@ -427,50 +429,75 @@ private PendingStream(PickSubchannelArgs args, ClientStreamTracer[] tracers,
      * spans are ended and a new segment is initiated. If only {@code newReason} changes, a
      * 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) {
-        return;
-      }
-      if (!Objects.equals(activeDelayType, newType)) {
-        // Delay type changed (e.g., from RLS lookup to connecting). End the previous delay.
-        if (activeDelayType != null) {
+    void updateDelay(@Nullable String newType, @Nullable String newReason) {
+      synchronized (this) {
+        if (getRealStream() != null || delayEnded) {
+          return;
+        }
+        String prevTypeToClose = null;
+        String newTypeToStart = null;
+        String newReasonToStart = null;
+        String newReasonToNotify = null;
+
+        if (!Objects.equals(activeDelayType, newType)) {
+          if (activeDelayType != null) {
+            prevTypeToClose = activeDelayType;
+          }
+          activeDelayType = newType;
+          activeDelayReason = null;
+          if (newType != null) {
+            newTypeToStart = newType;
+            newReasonToStart = newReason != null ? newReason : "";
+          }
+        }
+        if (newType != null && newReason != null
+            && !Objects.equals(activeDelayReason, newReason)) {
+          activeDelayReason = newReason;
+          newReasonToNotify = newReason;
+        }
+
+        if (prevTypeToClose != null) {
           for (ClientStreamTracer tracer : tracers) {
             tracer.recordAttemptDelayEnd();
           }
         }
-        activeDelayType = newType;
-        activeDelayReason = null;
-        if (newType != null) {
+        if (newTypeToStart != null) {
           for (ClientStreamTracer tracer : tracers) {
-            tracer.recordAttemptDelayStart(newType, newReason != null ? newReason : "");
+            tracer.recordAttemptDelayStart(newTypeToStart, newReasonToStart);
           }
         }
-      }
-      if (newType != null && newReason != null && !Objects.equals(activeDelayReason, newReason)) {
-        // Delay type is unchanged, but the reason changed (e.g., priority failover).
-        activeDelayReason = newReason;
-        for (ClientStreamTracer tracer : tracers) {
-          tracer.recordAttemptDelayReasonChanged(newReason);
+        if (newReasonToNotify != null) {
+          for (ClientStreamTracer tracer : tracers) {
+            tracer.recordAttemptDelayReasonChanged(newReasonToNotify);
+          }
         }
       }
     }
 
     /**
      * Ends active attempt delay segment telemetry upon stream creation or stream cancellation.
      */
-    synchronized void endDelay() {
-      if (activeDelayType != null) {
-        for (ClientStreamTracer tracer : tracers) {
-          tracer.recordAttemptDelayEnd();
+    void endDelay() {
+      synchronized (this) {
+        if (delayEnded) {
+          return;
         }
+        delayEnded = true;
+        boolean shouldEnd = activeDelayType != null;
         activeDelayType = null;
         activeDelayReason = null;
+        if (shouldEnd) {
+          for (ClientStreamTracer tracer : tracers) {
+            tracer.recordAttemptDelayEnd();
+          }
+        }
       }
     }
 
     Runnable setStreamAndEndDelay(ClientStream stream) {
+      Runnable runnable = setStream(stream);
       endDelay();
-      return setStream(stream);
+      return runnable;
     }
 
     /** Runnable may be null. */
@@ -496,6 +523,7 @@ private Runnable createRealStream(ClientTransport transport, String authorityOve
 
     @Override
     public void cancel(Status reason) {
+      endDelay();
       super.cancel(reason);
       synchronized (lock) {
         if (reportTransportTerminated != 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,10 @@ private final class PendingCall<ReqT, RespT> extends DelayedClientCall<ReqT, Res
       final MethodDescriptor<ReqT, RespT> method;
       final CallOptions callOptions;
       private final long callCreationTime;
+      @GuardedBy("this") private boolean queuedForResolution;
+      @GuardedBy("this") private boolean callCancelled;
+      @GuardedBy("this") private boolean delayEnded;
+      @GuardedBy("this") private boolean callDelayStarted;
 
       PendingCall(Context context, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions) {
         super(
@@ -1010,14 +1015,69 @@ private final class PendingCall<ReqT, RespT> extends DelayedClientCall<ReqT, Res
         this.callCreationTime = ticker.nanoTime();
       }
 
+      void notifyQueuedForNameResolution() {
+        boolean shouldStart = false;
+        synchronized (this) {
+          if (!callCancelled && !delayEnded && !queuedForResolution) {
+            queuedForResolution = true;
+            shouldStart = true;
+          }
+        }
+        if (shouldStart) {
+          for (ClientStreamTracer.Factory factory : callOptions.getStreamTracerFactories()) {
+            factory.recordCallDelayStart(
+                "resolving", "waiting for name resolution or service config");
+          }
+          boolean shouldEndNow = false;
+          synchronized (this) {
+            callDelayStarted = true;
+            if (!delayEnded && callCancelled) {
+              delayEnded = true;
+              shouldEndNow = true;
+            }
+          }
+          if (shouldEndNow) {
+            for (ClientStreamTracer.Factory factory : callOptions.getStreamTracerFactories()) {
+              factory.recordCallDelayEnd();
+            }
+          }
+        }
+      }
+
+      private void endDelayIfNeeded() {
+        boolean shouldEnd = false;
+        synchronized (this) {
+          if (!queuedForResolution || delayEnded) {
+            return;
+          }
+          if (callDelayStarted) {
+            delayEnded = true;
+            shouldEnd = true;
+          }
+        }
+        if (shouldEnd) {
+          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;
+          boolean wasQueued;
+          synchronized (this) {
+            wasQueued = queuedForResolution;
+          }
+          if (wasQueued) {
+            effectiveOptions = callOptions.withOption(NAME_RESOLUTION_DELAYED,
+                ticker.nanoTime() - callCreationTime);
+          }
+          realCall = newClientCall(method, effectiveOptions);
         } finally {
           context.detach(previous);
         }
@@ -1037,6 +1097,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/ForwardingClientStreamTracerTest.java

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

opentelemetry/src/main/java/io/grpc/opentelemetry/GrpcOpenTelemetry.java

@@ -243,6 +243,16 @@ && isMetricEnabled("grpc.client.attempt.delay.duration", enableMetrics, disableD
               .build());
     }
 
+    if (isDelayObservabilityEnabled()
+        && isMetricEnabled("grpc.client.call.delay.duration", enableMetrics, disableDefault)) {
+      builder.clientCallDelayCounter(
+          meter.histogramBuilder(
+                  "grpc.client.call.delay.duration")
+              .setUnit("s")
+              .setDescription("Time taken before a client call starts")
+              .setExplicitBucketBoundariesAdvice(LATENCY_BUCKETS)
+              .build());
+    }
     if (isMetricEnabled("grpc.client.attempt.sent_total_compressed_message_size", enableMetrics,
         disableDefault)) {
       builder.clientTotalSentCompressedMessageSizeCounter(
@@ -364,7 +374,7 @@ && isMetricEnabled("grpc.client.attempt.delay.duration", enableMetrics, disableD
    * Checks whether experimental client attempt and call delay observability is globally enabled.
    *
    * <p>Guarded strictly by the {@code GRPC_EXPERIMENTAL_ENABLE_DELAY_OBSERVABILITY} environment
-   * variable (defaults to {@code false}). When disabled, delay spans and
+   * variable or JVM system property (defaults to {@code false}). When disabled, delay spans and
    * duration histograms are suppressed to avoid runtime overhead.
    */
   static boolean isDelayObservabilityEnabled() {