feat: add metric headers

credentials/java/com/google/auth/CredentialTypeForMetrics.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *    * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *
+ *    * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package com.google.auth;
+
+/**
+ * Defines the different types of credentials that can be used for metrics.
+ *
+ * <p>Each credential type is associated with a label that is used for reporting purposes. Add new
+ * enum constant only when corresponding configs established.
+ *
+ * <p>Credentials with type {@code CredentialTypeForMetrics.DO_NOT_SEND} is default value for
+ * credential implementations that do not set type specifically. It is not expected to send metrics.
+ *
+ * <p>
+ *
+ * @see #getLabel()
+ */
+public enum CredentialTypeForMetrics {
+  USER_CREDENTIALS("u"),
+  SERVICE_ACCOUNT_CREDENTIALS_AT("sa"),
+  SERVICE_ACCOUNT_CREDENTIALS_JWT("jwt"),
+  VM_CREDENTIALS("mds"),
+  IMPERSONATED_CREDENTIALS("imp"),
+  DO_NOT_SEND("dns");
+
+  private String label;
+
+  private CredentialTypeForMetrics(String label) {
+    this.label = label;
+  }
+
+  public String getLabel() {
+    return label;
+  }
+}

credentials/java/com/google/auth/Credentials.java

@@ -45,6 +45,8 @@ public abstract class Credentials implements Serializable {
 
   public static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
 
+  private CredentialTypeForMetrics credentialTypeForMetrics = CredentialTypeForMetrics.DO_NOT_SEND;
+
   /**
    * A constant string name describing the authentication technology.
    *
@@ -70,6 +72,27 @@ public String getUniverseDomain() throws IOException {
     return GOOGLE_DEFAULT_UNIVERSE;
   }
 
+  /**
+   * Gets the credential type used for internal metrics header.
+   *
+   * @return a enum value for credential type
+   */
+  public CredentialTypeForMetrics getMetricsCredentialType() {
+    return this.credentialTypeForMetrics;
+  }
+
+  /**
+   * Sets the credential type for metrics.
+   *
+   * <p>The default is {@code CredentialTypeForMetrics.DO_NOT_SEND}. For a credential that is
+   * established to track for metrics, this default should be overridden.
+   *
+   * @param credentialTypeForMetrics The credential type to be used for metrics.
+   */
+  public void setMetricsCredentialType(CredentialTypeForMetrics credentialTypeForMetrics) {
+    this.credentialTypeForMetrics = credentialTypeForMetrics;
+  }
+
   /**
    * Get the current request metadata, refreshing tokens if required.
    *

oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java

@@ -41,10 +41,12 @@
 import com.google.api.client.http.HttpStatusCodes;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialTypeForMetrics;
 import com.google.auth.Credentials;
 import com.google.auth.Retryable;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects.ToStringHelper;
@@ -133,7 +135,7 @@ public class ComputeEngineCredentials extends GoogleCredentials
    */
   private ComputeEngineCredentials(ComputeEngineCredentials.Builder builder) {
     super(builder);
-
+    this.setMetricsCredentialType(CredentialTypeForMetrics.VM_CREDENTIALS);
     this.transportFactory =
         firstNonNull(
             builder.getHttpTransportFactory(),
@@ -234,7 +236,7 @@ public String getUniverseDomain() throws IOException {
   }
 
   private String getUniverseDomainFromMetadata() throws IOException {
-    HttpResponse response = getMetadataResponse(getUniverseDomainUrl());
+    HttpResponse response = getMetadataResponse(getUniverseDomainUrl(), RequestType.UNTRACKED);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       return Credentials.GOOGLE_DEFAULT_UNIVERSE;
@@ -260,7 +262,8 @@ private String getUniverseDomainFromMetadata() throws IOException {
   /** Refresh the access token by getting it from the GCE metadata server */
   @Override
   public AccessToken refreshAccessToken() throws IOException {
-    HttpResponse response = getMetadataResponse(createTokenUrlWithScopes());
+    HttpResponse response =
+        getMetadataResponse(createTokenUrlWithScopes(), RequestType.ACCESS_TOKEN_REQUEST);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       throw new IOException(
@@ -325,7 +328,8 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
       }
     }
     documentUrl.set("audience", targetAudience);
-    HttpResponse response = getMetadataResponse(documentUrl.toString());
+    HttpResponse response =
+        getMetadataResponse(documentUrl.toString(), RequestType.ID_TOKEN_REQUEST);
     InputStream content = response.getContent();
     if (content == null) {
       throw new IOException("Empty content from metadata token server request.");
@@ -334,13 +338,20 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
     return IdToken.create(rawToken);
   }
 
-  private HttpResponse getMetadataResponse(String url) throws IOException {
+  private HttpResponse getMetadataResponse(String url, RequestType requestType) throws IOException {
     GenericUrl genericUrl = new GenericUrl(url);
     HttpRequest request =
         transportFactory.create().createRequestFactory().buildGetRequest(genericUrl);
     JsonObjectParser parser = new JsonObjectParser(OAuth2Utils.JSON_FACTORY);
     request.setParser(parser);
     request.getHeaders().set(METADATA_FLAVOR, GOOGLE);
+    // do not send metric header for getUniverseDomain and getAccount
+    if (requestType != RequestType.UNTRACKED) {
+      MetricsUtils.setMetricsHeader(
+          request,
+          MetricsUtils.getGoogleCredentialsMetricsHeader(requestType, getMetricsCredentialType()));
+    }
+
     request.setThrowExceptionOnExecuteError(false);
     HttpResponse response;
     try {
@@ -440,7 +451,10 @@ private static boolean pingComputeEngineMetadata(
             transportFactory.create().createRequestFactory().buildGetRequest(tokenUrl);
         request.setConnectTimeout(COMPUTE_PING_CONNECTION_TIMEOUT_MS);
         request.getHeaders().set(METADATA_FLAVOR, GOOGLE);
-
+        MetricsUtils.setMetricsHeader(
+            request,
+            MetricsUtils.getGoogleCredentialsMetricsHeader(
+                RequestType.METADATA_SERVER_PIN, CredentialTypeForMetrics.DO_NOT_SEND));
         HttpResponse response = request.execute();
         try {
           // Internet providers can return a generic response to all requests, so it is necessary
@@ -588,7 +602,7 @@ public byte[] sign(byte[] toSign) {
   }
 
   private String getDefaultServiceAccount() throws IOException {
-    HttpResponse response = getMetadataResponse(getServiceAccountsUrl());
+    HttpResponse response = getMetadataResponse(getServiceAccountsUrl(), RequestType.UNTRACKED);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       throw new IOException(

oauth2_http/java/com/google/auth/oauth2/IamUtils.java

@@ -44,9 +44,11 @@
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.ExponentialBackOff;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialTypeForMetrics;
 import com.google.auth.Credentials;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpCredentialsAdapter;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.io.BaseEncoding;
 import java.io.IOException;
 import java.io.InputStream;
@@ -178,6 +180,7 @@ private static String getSignature(
    * @param transport transport used for building the HTTP request
    * @param targetAudience the audience the issued ID token should include
    * @param additionalFields additional fields to send in the IAM call
+   * @param credentialTypeForMetrics credential type for credential making this call
    * @return IdToken issed to the serviceAccount
    * @throws IOException if the IdToken cannot be issued.
    * @see <a
@@ -189,7 +192,8 @@ static IdToken getIdToken(
       HttpTransport transport,
       String targetAudience,
       boolean includeEmail,
-      Map<String, ?> additionalFields)
+      Map<String, ?> additionalFields,
+      CredentialTypeForMetrics credentialTypeForMetrics)
       throws IOException {
 
     String idTokenUrl = String.format(ID_TOKEN_URL_FORMAT, serviceAccountEmail);
@@ -211,6 +215,11 @@ static IdToken getIdToken(
     request.setParser(parser);
     request.setThrowExceptionOnExecuteError(false);
 
+    MetricsUtils.setMetricsHeader(
+        request,
+        MetricsUtils.getGoogleCredentialsMetricsHeader(
+            RequestType.ID_TOKEN_REQUEST, credentialTypeForMetrics));
+
     HttpResponse response = request.execute();
     int statusCode = response.getStatusCode();
     if (statusCode >= 400 && statusCode < HttpStatusCodes.STATUS_CODE_SERVER_ERROR) {

oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java

@@ -43,9 +43,11 @@
 import com.google.api.client.http.json.JsonHttpContent;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialTypeForMetrics;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpCredentialsAdapter;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
 import com.google.common.collect.ImmutableMap;
@@ -452,6 +454,7 @@ public ImpersonatedCredentials createWithCustomCalendar(Calendar calendar) {
 
   private ImpersonatedCredentials(Builder builder) {
     super(builder);
+    this.setMetricsCredentialType(CredentialTypeForMetrics.IMPERSONATED_CREDENTIALS);
     this.sourceCredentials = builder.getSourceCredentials();
     this.targetPrincipal = builder.getTargetPrincipal();
     this.delegates = builder.getDelegates();
@@ -508,6 +511,10 @@ public AccessToken refreshAccessToken() throws IOException {
     HttpRequest request = requestFactory.buildPostRequest(url, requestContent);
     adapter.initialize(request);
     request.setParser(parser);
+    MetricsUtils.setMetricsHeader(
+        request,
+        MetricsUtils.getGoogleCredentialsMetricsHeader(
+            RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType()));
 
     HttpResponse response = null;
     try {
@@ -557,7 +564,8 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
         transportFactory.create(),
         targetAudience,
         includeEmail,
-        ImmutableMap.of("delegates", this.delegates));
+        ImmutableMap.of("delegates", this.delegates),
+        getMetricsCredentialType());
   }
 
   @Override

oauth2_http/java/com/google/auth/oauth2/MetricsUtils.java

@@ -31,12 +31,16 @@
 
 package com.google.auth.oauth2;
 
+import com.google.api.client.http.HttpRequest;
+import com.google.auth.CredentialTypeForMetrics;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Properties;
 
 class MetricsUtils {
   static final String API_CLIENT_HEADER = "x-goog-api-client";
+  static final String CRED_TYPE = "cred-type";
+  static final String AUTH_REQUEST_TYPE = "auth-request-type";
   private static final String authLibraryVersion = getAuthLibraryVersion();
   private static final String javaLanguageVersion = System.getProperty("java.version");
 
@@ -67,4 +71,50 @@ private static String getAuthLibraryVersion() {
     }
     return version;
   }
+
+  public enum RequestType {
+    ACCESS_TOKEN_REQUEST("at"),
+    ID_TOKEN_REQUEST("it"),
+    METADATA_SERVER_PIN("mds"),
+    UNSPECIFIED("unspecified"), // should not send request type info
+    UNTRACKED("untracked"); // should not add metric header
+
+    private String label;
+
+    private RequestType(String label) {
+      this.label = label;
+    }
+
+    public String getLabel() {
+      return label;
+    }
+  }
+
+  /**
+   * Formulates metrics header string. Header string takes format: “gl-java/JAVA_VERSION
+   * auth/LIB_VERSION auth-request-type/REQUEST_TYPE cred-type/CREDENTIAL_TYPE”. "auth-request-type"
+   * and "cred-type" can be omitted.
+   *
+   * @param requestType Auth request type to be specified in metrics, omit when {@code
+   *     RequestType.UNSPECIFIED}
+   * @param credentialTypeForMetrics Credential type to be included in metrics string, omit when
+   *     {@code CredentialTypeForMetrics.DO_NOT_SEND}
+   * @return metrics header string to send
+   */
+  static String getGoogleCredentialsMetricsHeader(
+      RequestType requestType, CredentialTypeForMetrics credentialTypeForMetrics) {
+    StringBuilder stringBuilder =
+        new StringBuilder(MetricsUtils.getLanguageAndAuthLibraryVersions());
+    if (requestType != RequestType.UNSPECIFIED) {
+      stringBuilder.append(String.format(" %s/%s", AUTH_REQUEST_TYPE, requestType.getLabel()));
+    }
+    if (credentialTypeForMetrics != CredentialTypeForMetrics.DO_NOT_SEND) {
+      stringBuilder.append(String.format(" %s/%s", CRED_TYPE, credentialTypeForMetrics.getLabel()));
+    }
+    return stringBuilder.toString();
+  }
+
+  static void setMetricsHeader(HttpRequest request, String metricsHeader) {
+    request.getHeaders().set(MetricsUtils.API_CLIENT_HEADER, metricsHeader);
+  }
 }

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java

@@ -51,11 +51,13 @@
 import com.google.api.client.util.GenericData;
 import com.google.api.client.util.Joiner;
 import com.google.api.client.util.Preconditions;
+import com.google.auth.CredentialTypeForMetrics;
 import com.google.auth.Credentials;
 import com.google.auth.RequestMetadataCallback;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.AuthHttpConstants;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.collect.ImmutableList;
@@ -505,6 +507,10 @@ public AccessToken refreshAccessToken() throws IOException {
     HttpRequestFactory requestFactory = transportFactory.create().createRequestFactory();
     HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(tokenServerUri), content);
 
+    MetricsUtils.setMetricsHeader(
+        request,
+        MetricsUtils.getGoogleCredentialsMetricsHeader(
+            RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType()));
     if (this.defaultRetriesEnabled) {
       request.setNumberOfRetries(OAuth2Utils.DEFAULT_NUMBER_OF_RETRIES);
     } else {
@@ -586,6 +592,12 @@ private IdToken getIdTokenOauthEndpoint(String targetAudience) throws IOExceptio
     UrlEncodedContent content = new UrlEncodedContent(tokenRequest);
 
     HttpRequest request = buildIdTokenRequest(tokenServerUri, transportFactory, content);
+    // add metric header
+    MetricsUtils.setMetricsHeader(
+        request,
+        MetricsUtils.getGoogleCredentialsMetricsHeader(
+            RequestType.ID_TOKEN_REQUEST, getMetricsCredentialType()));
+
     HttpResponse httpResponse = executeRequest(request);
 
     GenericData responseData = httpResponse.parseAs(GenericData.class);
@@ -1013,9 +1025,12 @@ private Map<String, List<String>> getRequestMetadataForGdu(URI uri) throws IOExc
     // configured then use scopes to get access token.
     if ((!createScopedRequired() && !useJwtAccessWithScope)
         || isConfiguredForDomainWideDelegation()) {
+      // assertion token flow
+      this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_AT);
       return super.getRequestMetadata(uri);
     }
-
+    // self-signed JWT flow
+    this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT);
     return getRequestMetadataWithSelfSignedJwt(uri);
   }