feat(observability): implement url.domain attribute (#12316)

This Pull Request implements the `url.domain` observability attribute in
the `gax-java` library. This attribute records the 'nominal' domain
where the request is intended to go (e.g., `service.googleapis.com`),
distinct from `server.address` which reflects the actual destination
(which could be `localhost` or a proxy).

The attribute is now recorded in both attempt-level spans and metrics
for both gRPC and HTTP/JSON transports, provided that the `serviceName`
is available in the `ClientContext`.

Author: diegomarquezp

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

@@ -152,7 +152,8 @@ public static Builder newBuilder() {
         .setTracerFactory(BaseApiTracerFactory.getInstance())
         .setQuotaProjectId(null)
         .setGdchApiAudience(null)
-        // Attempt to create an empty, non-functioning EndpointContext by default. This is
+        // Attempt to create an empty, non-functioning EndpointContext by default. This
+        // is
         // not exposed to the user via getters/setters.
         .setEndpointContext(EndpointContext.getDefaultInstance());
   }
@@ -185,8 +186,10 @@ public static ClientContext create(StubSettings settings) throws IOException {
     String settingsGdchApiAudience = settings.getGdchApiAudience();
     boolean usingGDCH = credentials instanceof GdchCredentials;
     if (usingGDCH) {
-      // Can only determine if the GDC-H is being used via the Credentials. The Credentials object
-      // is resolved in the ClientContext and must be passed to the EndpointContext. Rebuild the
+      // Can only determine if the GDC-H is being used via the Credentials. The
+      // Credentials object
+      // is resolved in the ClientContext and must be passed to the EndpointContext.
+      // Rebuild the
       // endpointContext only on GDC-H flows.
       endpointContext = endpointContext.withGDCH();
       // Resolve the new endpoint with the GDC-H flow
@@ -199,16 +202,20 @@ public static ClientContext create(StubSettings settings) throws IOException {
     }
 
     if (settings.getQuotaProjectId() != null && credentials != null) {
-      // If the quotaProjectId is set, wrap original credentials with correct quotaProjectId as
+      // If the quotaProjectId is set, wrap original credentials with correct
+      // quotaProjectId as
       // QuotaProjectIdHidingCredentials.
-      // Ensure that a custom set quota project id takes priority over one detected by credentials.
+      // Ensure that a custom set quota project id takes priority over one detected by
+      // credentials.
       // Avoid the backend receiving possibly conflict values of quotaProjectId
       credentials = new QuotaProjectIdHidingCredentials(credentials);
     }
 
     TransportChannelProvider transportChannelProvider = settings.getTransportChannelProvider();
-    // After needsExecutor and StubSettings#setExecutorProvider are deprecated, transport channel
-    // executor can only be set from TransportChannelProvider#withExecutor directly, and a provider
+    // After needsExecutor and StubSettings#setExecutorProvider are deprecated,
+    // transport channel
+    // executor can only be set from TransportChannelProvider#withExecutor directly,
+    // and a provider
     // will have a default executor if it needs one.
     if (transportChannelProvider.needsExecutor() && settings.getExecutorProvider() != null) {
       transportChannelProvider =
@@ -271,11 +278,13 @@ public static ClientContext create(StubSettings settings) throws IOException {
     if (watchdogProvider != null && watchdogProvider.shouldAutoClose()) {
       backgroundResources.add(watchdog);
     }
+
     ApiTracerContext apiTracerContext =
         ApiTracerContext.newBuilder()
             .setServerAddress(endpointContext.resolvedServerAddress())
             .setServerPort(endpointContext.resolvedServerPort())
             .setLibraryMetadata(settings.getLibraryMetadata())
+            .setUrlDomain(endpointContext.getUrlDomain())
             .setServiceName(endpointContext.serviceName())
             .build();
     ApiTracerFactory apiTracerFactory = settings.getTracerFactory();

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

@@ -140,6 +140,14 @@ public static EndpointContext getDefaultInstance() {
   @Nullable
   public abstract Integer resolvedServerPort();
 
+  @Nullable
+  String getUrlDomain() {
+    if (!Strings.isNullOrEmpty(serviceName()) && !Strings.isNullOrEmpty(resolvedUniverseDomain())) {
+      return serviceName() + "." + resolvedUniverseDomain();
+    }
+    return null;
+  }
+
   public abstract Builder toBuilder();
 
   public static Builder newBuilder() {

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

@@ -212,6 +212,9 @@ public Map<String, Object> getAttemptAttributes() {
       attributes.put(
           ObservabilityAttributes.DESTINATION_RESOURCE_ID_ATTRIBUTE, destinationResourceId());
     }
+    if (!Strings.isNullOrEmpty(urlDomain())) {
+      attributes.put(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE, urlDomain());
+    }
     return attributes;
   }
 
@@ -232,10 +235,10 @@ Map<String, Object> getMetricsAttributes() {
     if (!Strings.isNullOrEmpty(fullMethodName())) {
       attributes.put(ObservabilityAttributes.GRPC_RPC_METHOD_ATTRIBUTE, fullMethodName());
     }
+    if (!Strings.isNullOrEmpty(urlDomain())) {
+      attributes.put(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE, urlDomain());
+    }
     if (transport() == Transport.HTTP) {
-      if (!Strings.isNullOrEmpty(urlDomain())) {
-        attributes.put(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE, urlDomain());
-      }
       if (!Strings.isNullOrEmpty(httpPathTemplate())) {
         attributes.put(ObservabilityAttributes.URL_TEMPLATE_ATTRIBUTE, httpPathTemplate());
       }

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/rpc/EndpointContextTest.java

@@ -698,4 +698,29 @@ void endpointContextBuild_resolvesInvalidEndpointAndPort() throws Exception {
     Truth.assertThat(endpointContext.resolvedServerAddress()).isNull();
     Truth.assertThat(endpointContext.resolvedServerPort()).isNull();
   }
+
+  @Test
+  void getUrlDomain_success() throws IOException {
+    EndpointContext endpointContext = defaultEndpointContextBuilder.build();
+    Truth.assertThat(endpointContext.getUrlDomain()).isEqualTo("test.googleapis.com");
+  }
+
+  @Test
+  void getUrlDomain_nullServiceName() throws IOException {
+    EndpointContext endpointContext = defaultEndpointContextBuilder.setServiceName(null).build();
+    Truth.assertThat(endpointContext.getUrlDomain()).isNull();
+  }
+
+  @Test
+  void getUrlDomain_emptyServiceName() throws IOException {
+    EndpointContext endpointContext = defaultEndpointContextBuilder.setServiceName("").build();
+    Truth.assertThat(endpointContext.getUrlDomain()).isNull();
+  }
+
+  @Test
+  void getUrlDomain_nonGDUUniverseDomain() throws IOException {
+    EndpointContext endpointContext =
+        defaultEndpointContextBuilder.setUniverseDomain("random.com").build();
+    Truth.assertThat(endpointContext.getUrlDomain()).isEqualTo("test.random.com");
+  }
 }

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

@@ -186,6 +186,19 @@ void testGetAttemptAttributes_emptyStrings() {
     assertThat(attributes).isEmpty();
   }
 
+  @Test
+  void testGetAttemptAttributes_urlDomain() {
+    ApiTracerContext context =
+        ApiTracerContext.newBuilder()
+            .setLibraryMetadata(LibraryMetadata.empty())
+            .setUrlDomain("test-domain.com")
+            .build();
+    Map<String, Object> attributes = context.getAttemptAttributes();
+
+    assertThat(attributes)
+        .containsEntry(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE, "test-domain.com");
+  }
+
   @Test
   void testGetAttemptAttributes_serviceName() {
     ApiTracerContext context =
@@ -317,7 +330,8 @@ void testGetMetricsAttributes_urlDomain_notHttp() {
             .build();
     Map<String, Object> attributes = context.getMetricsAttributes();
 
-    assertThat(attributes).doesNotContainKey(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE);
+    assertThat(attributes)
+        .containsEntry(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE, "test-domain.com");
   }
 
   @Test

sdk-platform-java/java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelTracing.java

@@ -119,7 +119,6 @@ void testTracing_successfulEcho_grpc() throws Exception {
     SpanTracerFactory tracingFactory = new SpanTracerFactory(openTelemetrySdk);
 
     EchoSettings grpcEchoSettings = createEchoSettings(false);
-
     EchoStub stub = createStubWithServiceName(grpcEchoSettings, tracingFactory);
 
     try (EchoClient client = EchoClient.create(stub)) {
@@ -176,8 +175,12 @@ void testTracing_successfulEcho_grpc() throws Exception {
                   .getAttributes()
                   .get(AttributeKey.stringKey(ObservabilityAttributes.GRPC_RPC_METHOD_ATTRIBUTE)))
           .isEqualTo("google.showcase.v1beta1.Echo/Echo");
+      assertThat(
+              attemptSpan
+                  .getAttributes()
+                  .get(AttributeKey.stringKey(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE)))
+          .isEqualTo("showcase.googleapis.com");
       assertThat(attemptSpan.getInstrumentationScopeInfo().getName()).isEqualTo(SHOWCASE_ARTIFACT);
-      // {x-version-update-end}
     }
   }
 
@@ -186,7 +189,6 @@ void testTracing_successfulEcho_httpjson() throws Exception {
     SpanTracerFactory tracingFactory = new SpanTracerFactory(openTelemetrySdk);
 
     EchoSettings httpJsonEchoSettings = createEchoSettings(true);
-
     EchoStub stub = createStubWithServiceName(httpJsonEchoSettings, tracingFactory);
 
     try (EchoClient client = EchoClient.create(stub)) {
@@ -244,6 +246,11 @@ void testTracing_successfulEcho_httpjson() throws Exception {
                   .getAttributes()
                   .get(AttributeKey.stringKey(ObservabilityAttributes.HTTP_URL_TEMPLATE_ATTRIBUTE)))
           .isEqualTo("v1beta1/echo:echo");
+      assertThat(
+              attemptSpan
+                  .getAttributes()
+                  .get(AttributeKey.stringKey(ObservabilityAttributes.URL_DOMAIN_ATTRIBUTE)))
+          .isEqualTo("showcase.googleapis.com");
       assertThat(
               attemptSpan
                   .getAttributes()