grpc · shivaspeaks · Jul 7, 2025
diff --git a/xds/src/main/java/io/grpc/xds/BackendMetricPropagation.java b/xds/src/main/java/io/grpc/xds/BackendMetricPropagation.java
@@ -0,0 +1,110 @@
+/*
+ * Copyright 2025 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc.xds;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.collect.ImmutableSet;
+import io.grpc.Internal;
+import javax.annotation.Nullable;
+
+/**
+ * Represents the configuration for which ORCA metrics should be propagated from backend
+ * to LRS load reports, as defined in gRFC A85.
+ */
+@Internal
+public final class BackendMetricPropagation {
+
+  public final boolean propagateCpuUtilization;
+  public final boolean propagateMemUtilization;
+  public final boolean propagateApplicationUtilization;
+
+  private final boolean propagateAllNamedMetrics;
+  private final ImmutableSet<String> namedMetricKeys;
+
+  private BackendMetricPropagation(
+      boolean propagateCpuUtilization,
+      boolean propagateMemUtilization,
+      boolean propagateApplicationUtilization,
+      boolean propagateAllNamedMetrics,
+      ImmutableSet<String> namedMetricKeys) {
+    this.propagateCpuUtilization = propagateCpuUtilization;
+    this.propagateMemUtilization = propagateMemUtilization;
+    this.propagateApplicationUtilization = propagateApplicationUtilization;
+    this.propagateAllNamedMetrics = propagateAllNamedMetrics;
+    this.namedMetricKeys = checkNotNull(namedMetricKeys, "namedMetricKeys");
+  }
+
+  /**
+   * Creates a BackendMetricPropagation from a list of metric specifications.
+   *
+   * @param metricSpecs list of metric specification strings from CDS resource
+   * @return BackendMetricPropagation instance
+   */
+  public static BackendMetricPropagation fromMetricSpecs(@Nullable java.util.List<String> metricSpecs) {
+    if (metricSpecs == null || metricSpecs.isEmpty()) {
+      return new BackendMetricPropagation(false, false, false, false, ImmutableSet.of());
+    }
+
+    boolean propagateCpuUtilization = false;
+    boolean propagateMemUtilization = false;
+    boolean propagateApplicationUtilization = false;
+    boolean propagateAllNamedMetrics = false;
+    ImmutableSet.Builder<String> namedMetricKeysBuilder = ImmutableSet.builder();
+    for (String spec : metricSpecs) {
+      if (spec == null) {
+        continue;
+      }
+      switch (spec) {
+        case "cpu_utilization":
+          propagateCpuUtilization = true;
+          break;
+        case "mem_utilization":
+          propagateMemUtilization = true;
+          break;
+        case "application_utilization":
+          propagateApplicationUtilization = true;
+          break;
+        case "named_metrics.*":
+          propagateAllNamedMetrics = true;
+          break;
+        default:
+          if (spec.startsWith("named_metrics.")) {
+            String metricKey = spec.substring("named_metrics.".length());
+            if (!metricKey.isEmpty()) {
+              namedMetricKeysBuilder.add(metricKey);
+            }
+          }
+          break;
+      }
+    }
+
+    return new BackendMetricPropagation(
+        propagateCpuUtilization,
+        propagateMemUtilization,
+        propagateApplicationUtilization,
+        propagateAllNamedMetrics,
+        namedMetricKeysBuilder.build());
+  }
+
+  /**
+   * Returns whether the given named metric key should be propagated.
+   */
+  public boolean shouldPropagateNamedMetric(String metricKey) {
+    return propagateAllNamedMetrics || namedMetricKeys.contains(metricKey);
+  }
+} 
diff --git a/xds/src/main/java/io/grpc/xds/CdsLoadBalancer2.java b/xds/src/main/java/io/grpc/xds/CdsLoadBalancer2.java
@@ -141,15 +141,17 @@ public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
             result.maxConcurrentRequests(),
             result.upstreamTlsContext(),
             result.filterMetadata(),
-            result.outlierDetection());
+            result.outlierDetection(),
+            result.backendMetricPropagation());
       } else {
         instance = DiscoveryMechanism.forLogicalDns(
             leafName,
             result.dnsHostName(),
             result.lrsServerInfo(),
             result.maxConcurrentRequests(),
             result.upstreamTlsContext(),
-            result.filterMetadata());
+            result.filterMetadata(),
+            result.backendMetricPropagation());
       }
       instances.add(instance);
     }

diff --git a/xds/src/main/java/io/grpc/xds/ClusterImplLoadBalancer.java b/xds/src/main/java/io/grpc/xds/ClusterImplLoadBalancer.java
@@ -148,6 +148,7 @@ public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     childLbHelper.updateMaxConcurrentRequests(config.maxConcurrentRequests);
     childLbHelper.updateSslContextProviderSupplier(config.tlsContext);
     childLbHelper.updateFilterMetadata(config.filterMetadata);
+    childLbHelper.updateBackendMetricPropagation(config.backendMetricPropagation);
 
     childSwitchLb.handleResolvedAddresses(
         resolvedAddresses.toBuilder()
@@ -208,6 +209,8 @@ private final class ClusterImplLbHelper extends ForwardingLoadBalancerHelper {
     private Map<String, Struct> filterMetadata = ImmutableMap.of();
     @Nullable
     private final ServerInfo lrsServerInfo;
+    @Nullable
+    private BackendMetricPropagation backendMetricPropagation;
 
     private ClusterImplLbHelper(AtomicLong inFlights, @Nullable ServerInfo lrsServerInfo) {
       this.inFlights = checkNotNull(inFlights, "inFlights");
@@ -320,7 +323,7 @@ private ClusterLocality createClusterLocalityFromAttributes(Attributes addressAt
           (lrsServerInfo == null)
               ? null
               : xdsClient.addClusterLocalityStats(lrsServerInfo, cluster,
-                  edsServiceName, locality);
+                  edsServiceName, locality, backendMetricPropagation);
 
       return new ClusterLocality(localityStats, localityName);
     }
@@ -370,6 +373,11 @@ private void updateFilterMetadata(Map<String, Struct> filterMetadata) {
       this.filterMetadata = ImmutableMap.copyOf(filterMetadata);
     }
 
+    private void updateBackendMetricPropagation(
+        @Nullable BackendMetricPropagation backendMetricPropagation) {
+      this.backendMetricPropagation = backendMetricPropagation;
+    }
+
     private class RequestLimitingSubchannelPicker extends SubchannelPicker {
       private final SubchannelPicker delegate;
       private final List<DropOverload> dropPolicies;
@@ -505,11 +513,18 @@ private OrcaPerRpcListener(ClusterLocalityStats stats) {
     }
 
     /**
-     * Copies {@link MetricReport#getNamedMetrics()} to {@link ClusterLocalityStats} such that it is
-     * included in the snapshot for the LRS report sent to the LRS server.
+     * Copies ORCA metrics from {@link MetricReport} to {@link ClusterLocalityStats}
+     * such that they are included in the snapshot for the LRS report sent to the LRS server.
+     * This includes both top-level metrics (CPU, memory, application utilization) and named
+     * metrics, filtered according to the backend metric propagation configuration.
      */
     @Override
     public void onLoadReport(MetricReport report) {
+      stats.recordTopLevelMetrics(
+          report.getCpuUtilization(),
+          report.getMemoryUtilization(),
+          report.getApplicationUtilization());
+
       stats.recordBackendLoadMetricStats(report.getNamedMetrics());
     }
   }

diff --git a/xds/src/main/java/io/grpc/xds/ClusterImplLoadBalancerProvider.java b/xds/src/main/java/io/grpc/xds/ClusterImplLoadBalancerProvider.java
@@ -98,11 +98,14 @@ static final class ClusterImplConfig {
     // Provides the direct child policy and its config.
     final Object childConfig;
     final Map<String, Struct> filterMetadata;
+    @Nullable
+    final BackendMetricPropagation backendMetricPropagation;
 
     ClusterImplConfig(String cluster, @Nullable String edsServiceName,
         @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
         List<DropOverload> dropCategories, Object childConfig,
-        @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata) {
+        @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
+        @Nullable BackendMetricPropagation backendMetricPropagation) {
       this.cluster = checkNotNull(cluster, "cluster");
       this.edsServiceName = edsServiceName;
       this.lrsServerInfo = lrsServerInfo;
@@ -112,6 +115,7 @@ static final class ClusterImplConfig {
       this.dropCategories = Collections.unmodifiableList(
           new ArrayList<>(checkNotNull(dropCategories, "dropCategories")));
       this.childConfig = checkNotNull(childConfig, "childConfig");
+      this.backendMetricPropagation = backendMetricPropagation;
     }
 
     @Override

diff --git a/xds/src/main/java/io/grpc/xds/ClusterResolverLoadBalancer.java b/xds/src/main/java/io/grpc/xds/ClusterResolverLoadBalancer.java
@@ -191,11 +191,11 @@ public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
         if (instance.type == DiscoveryMechanism.Type.EDS) {
           state = new EdsClusterState(instance.cluster, instance.edsServiceName,
               instance.lrsServerInfo, instance.maxConcurrentRequests, instance.tlsContext,
-              instance.filterMetadata, instance.outlierDetection);
+              instance.filterMetadata, instance.outlierDetection, instance.backendMetricPropagation);
         } else {  // logical DNS
           state = new LogicalDnsClusterState(instance.cluster, instance.dnsHostName,
               instance.lrsServerInfo, instance.maxConcurrentRequests, instance.tlsContext,
-              instance.filterMetadata);
+              instance.filterMetadata, instance.backendMetricPropagation);
         }
         clusterStates.put(instance.cluster, state);
         state.start();
@@ -334,6 +334,8 @@ private abstract class ClusterState {
       protected final Map<String, Struct> filterMetadata;
       @Nullable
       protected final OutlierDetection outlierDetection;
+      @Nullable
+      protected final BackendMetricPropagation backendMetricPropagation;
       // Resolution status, may contain most recent error encountered.
       protected Status status = Status.OK;
       // True if has received resolution result.
@@ -346,13 +348,15 @@ private abstract class ClusterState {
 
       private ClusterState(String name, @Nullable ServerInfo lrsServerInfo,
           @Nullable Long maxConcurrentRequests, @Nullable UpstreamTlsContext tlsContext,
-          Map<String, Struct> filterMetadata, @Nullable OutlierDetection outlierDetection) {
+          Map<String, Struct> filterMetadata, @Nullable OutlierDetection outlierDetection,
+          @Nullable BackendMetricPropagation backendMetricPropagation) {
         this.name = name;
         this.lrsServerInfo = lrsServerInfo;
         this.maxConcurrentRequests = maxConcurrentRequests;
         this.tlsContext = tlsContext;
         this.filterMetadata = ImmutableMap.copyOf(filterMetadata);
         this.outlierDetection = outlierDetection;
+        this.backendMetricPropagation = backendMetricPropagation;
       }
 
       abstract void start();
@@ -371,9 +375,10 @@ private final class EdsClusterState extends ClusterState implements ResourceWatc
       private EdsClusterState(String name, @Nullable String edsServiceName,
           @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
           @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
-          @Nullable OutlierDetection outlierDetection) {
+          @Nullable OutlierDetection outlierDetection,
+          @Nullable BackendMetricPropagation backendMetricPropagation) {
         super(name, lrsServerInfo, maxConcurrentRequests, tlsContext, filterMetadata,
-            outlierDetection);
+            outlierDetection, backendMetricPropagation);
         this.edsServiceName = edsServiceName;
       }
 
@@ -470,8 +475,8 @@ public void run() {
             Map<String, PriorityChildConfig> priorityChildConfigs =
                 generateEdsBasedPriorityChildConfigs(
                     name, edsServiceName, lrsServerInfo, maxConcurrentRequests, tlsContext,
-                    filterMetadata, outlierDetection, endpointLbConfig, lbRegistry,
-                    prioritizedLocalityWeights, dropOverloads);
+                    filterMetadata, backendMetricPropagation, outlierDetection,
+                    endpointLbConfig, lbRegistry, prioritizedLocalityWeights, dropOverloads);
             status = Status.OK;
             resolved = true;
             result = new ClusterResolutionResult(addresses, priorityChildConfigs,
@@ -585,8 +590,10 @@ private final class LogicalDnsClusterState extends ClusterState {
 
       private LogicalDnsClusterState(String name, String dnsHostName,
           @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
-          @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata) {
-        super(name, lrsServerInfo, maxConcurrentRequests, tlsContext, filterMetadata, null);
+          @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
+          @Nullable BackendMetricPropagation backendMetricPropagation) {
+        super(name, lrsServerInfo, maxConcurrentRequests, tlsContext,
+            filterMetadata, null, backendMetricPropagation);
         this.dnsHostName = checkNotNull(dnsHostName, "dnsHostName");
         nameResolverFactory =
             checkNotNull(helper.getNameResolverRegistry().asFactory(), "nameResolverFactory");
@@ -688,7 +695,7 @@ public Status onResult2(final ResolutionResult resolutionResult) {
             }
             PriorityChildConfig priorityChildConfig = generateDnsBasedPriorityChildConfig(
                     name, lrsServerInfo, maxConcurrentRequests, tlsContext, filterMetadata,
-                    lbRegistry, Collections.<DropOverload>emptyList());
+                    backendMetricPropagation, lbRegistry, Collections.<DropOverload>emptyList());
             status = Status.OK;
             resolved = true;
             result = new ClusterResolutionResult(addresses, priorityName, priorityChildConfig);
@@ -772,13 +779,14 @@ private static class ClusterResolutionResult {
   private static PriorityChildConfig generateDnsBasedPriorityChildConfig(
       String cluster, @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
       @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
+      @Nullable BackendMetricPropagation backendMetricPropagation,
       LoadBalancerRegistry lbRegistry, List<DropOverload> dropOverloads) {
     // Override endpoint-level LB policy with pick_first for logical DNS cluster.
     Object endpointLbConfig = GracefulSwitchLoadBalancer.createLoadBalancingPolicyConfig(
         lbRegistry.getProvider("pick_first"), null);
     ClusterImplConfig clusterImplConfig =
         new ClusterImplConfig(cluster, null, lrsServerInfo, maxConcurrentRequests,
-            dropOverloads, endpointLbConfig, tlsContext, filterMetadata);
+            dropOverloads, endpointLbConfig, tlsContext, filterMetadata, backendMetricPropagation);
     LoadBalancerProvider clusterImplLbProvider =
         lbRegistry.getProvider(XdsLbPolicies.CLUSTER_IMPL_POLICY_NAME);
     Object clusterImplPolicy = GracefulSwitchLoadBalancer.createLoadBalancingPolicyConfig(
@@ -795,15 +803,15 @@ private static PriorityChildConfig generateDnsBasedPriorityChildConfig(
   private static Map<String, PriorityChildConfig> generateEdsBasedPriorityChildConfigs(
       String cluster, @Nullable String edsServiceName, @Nullable ServerInfo lrsServerInfo,
       @Nullable Long maxConcurrentRequests, @Nullable UpstreamTlsContext tlsContext,
-      Map<String, Struct> filterMetadata,
+      Map<String, Struct> filterMetadata, @Nullable BackendMetricPropagation backendMetricPropagation,
       @Nullable OutlierDetection outlierDetection, Object endpointLbConfig,
       LoadBalancerRegistry lbRegistry, Map<String,
       Map<Locality, Integer>> prioritizedLocalityWeights, List<DropOverload> dropOverloads) {
     Map<String, PriorityChildConfig> configs = new HashMap<>();
     for (String priority : prioritizedLocalityWeights.keySet()) {
       ClusterImplConfig clusterImplConfig =
           new ClusterImplConfig(cluster, edsServiceName, lrsServerInfo, maxConcurrentRequests,
-              dropOverloads, endpointLbConfig, tlsContext, filterMetadata);
+              dropOverloads, endpointLbConfig, tlsContext, filterMetadata, backendMetricPropagation);
       LoadBalancerProvider clusterImplLbProvider =
           lbRegistry.getProvider(XdsLbPolicies.CLUSTER_IMPL_POLICY_NAME);
       Object priorityChildPolicy = GracefulSwitchLoadBalancer.createLoadBalancingPolicyConfig(

diff --git a/xds/src/main/java/io/grpc/xds/ClusterResolverLoadBalancerProvider.java b/xds/src/main/java/io/grpc/xds/ClusterResolverLoadBalancerProvider.java
@@ -137,6 +137,8 @@ static final class DiscoveryMechanism {
       @Nullable
       final OutlierDetection outlierDetection;
       final Map<String, Struct> filterMetadata;
+      @Nullable
+      final  BackendMetricPropagation backendMetricPropagation;
 
       enum Type {
         EDS,
@@ -146,7 +148,8 @@ enum Type {
       private DiscoveryMechanism(String cluster, Type type, @Nullable String edsServiceName,
           @Nullable String dnsHostName, @Nullable ServerInfo lrsServerInfo,
           @Nullable Long maxConcurrentRequests, @Nullable UpstreamTlsContext tlsContext,
-          Map<String, Struct> filterMetadata, @Nullable OutlierDetection outlierDetection) {
+          Map<String, Struct> filterMetadata, @Nullable OutlierDetection outlierDetection,
+          @Nullable BackendMetricPropagation backendMetricPropagation) {
         this.cluster = checkNotNull(cluster, "cluster");
         this.type = checkNotNull(type, "type");
         this.edsServiceName = edsServiceName;
@@ -156,27 +159,30 @@ private DiscoveryMechanism(String cluster, Type type, @Nullable String edsServic
         this.tlsContext = tlsContext;
         this.filterMetadata = ImmutableMap.copyOf(checkNotNull(filterMetadata, "filterMetadata"));
         this.outlierDetection = outlierDetection;
+        this.backendMetricPropagation = backendMetricPropagation;
       }
 
       static DiscoveryMechanism forEds(String cluster, @Nullable String edsServiceName,
           @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
           @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
-          OutlierDetection outlierDetection) {
+          OutlierDetection outlierDetection, @Nullable BackendMetricPropagation backendMetricPropagation) {
         return new DiscoveryMechanism(cluster, Type.EDS, edsServiceName, null, lrsServerInfo,
-            maxConcurrentRequests, tlsContext, filterMetadata, outlierDetection);
+            maxConcurrentRequests, tlsContext, filterMetadata, outlierDetection, backendMetricPropagation);
       }
 
       static DiscoveryMechanism forLogicalDns(String cluster, String dnsHostName,
           @Nullable ServerInfo lrsServerInfo, @Nullable Long maxConcurrentRequests,
-          @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata) {
+          @Nullable UpstreamTlsContext tlsContext, Map<String, Struct> filterMetadata,
+          @Nullable BackendMetricPropagation backendMetricPropagation) {
         return new DiscoveryMechanism(cluster, Type.LOGICAL_DNS, null, dnsHostName,
-            lrsServerInfo, maxConcurrentRequests, tlsContext, filterMetadata, null);
+            lrsServerInfo, maxConcurrentRequests, tlsContext, filterMetadata, null,
+            backendMetricPropagation);
       }
 
       @Override
       public int hashCode() {
         return Objects.hash(cluster, type, lrsServerInfo, maxConcurrentRequests, tlsContext,
-            edsServiceName, dnsHostName, filterMetadata, outlierDetection);
+            edsServiceName, dnsHostName, filterMetadata, outlierDetection, backendMetricPropagation);
       }
 
       @Override