add javadoc comment, rename for readability, rename UNKNOWN to DO_NOT…

…_SEND for clarity.

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

@@ -31,13 +31,26 @@
 
 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"),
-  UNKNOWN("unknown");
+  DO_NOT_SEND("do not send type to metrics");
 
   private String label;
 

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

@@ -45,7 +45,7 @@ public abstract class Credentials implements Serializable {
 
   public static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
 
-  private CredentialTypeForMetrics credentialTypeForMetrics = CredentialTypeForMetrics.UNKNOWN;
+  private CredentialTypeForMetrics credentialTypeForMetrics = CredentialTypeForMetrics.DO_NOT_SEND;
 
   /**
    * A constant string name describing the authentication technology.
@@ -72,11 +72,24 @@ public String getUniverseDomain() throws IOException {
     return GOOGLE_DEFAULT_UNIVERSE;
   }
 
-  public CredentialTypeForMetrics getCredentialType() {
+  /**
+   * Gets the credential type used for internal metrics header.
+   *
+   * @return a enum value for credential type
+   */
+  public CredentialTypeForMetrics getMetricsCredentialType() {
     return this.credentialTypeForMetrics;
   }
 
-  public void setCredentialType(CredentialTypeForMetrics 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;
   }
 

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

@@ -135,7 +135,7 @@ public class ComputeEngineCredentials extends GoogleCredentials
    */
   private ComputeEngineCredentials(ComputeEngineCredentials.Builder builder) {
     super(builder);
-    this.setCredentialType(CredentialTypeForMetrics.VM_CREDENTIALS);
+    this.setMetricsCredentialType(CredentialTypeForMetrics.VM_CREDENTIALS);
     this.transportFactory =
         firstNonNull(
             builder.getHttpTransportFactory(),
@@ -351,7 +351,8 @@ private HttpResponse getMetadataResponse(String url, RequestType requestType) th
           .getHeaders()
           .set(
               MetricsUtils.API_CLIENT_HEADER,
-              MetricsUtils.getGoogleCredentialsMetricsHeader(requestType, getCredentialType()));
+              MetricsUtils.getGoogleCredentialsMetricsHeader(
+                  requestType, getMetricsCredentialType()));
     }
 
     request.setThrowExceptionOnExecuteError(false);
@@ -458,7 +459,7 @@ private static boolean pingComputeEngineMetadata(
             .set(
                 MetricsUtils.API_CLIENT_HEADER,
                 MetricsUtils.getGoogleCredentialsMetricsHeader(
-                    RequestType.METADATA_SERVER_PIN, CredentialTypeForMetrics.UNKNOWN));
+                    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

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

@@ -454,7 +454,7 @@ public ImpersonatedCredentials createWithCustomCalendar(Calendar calendar) {
 
   private ImpersonatedCredentials(Builder builder) {
     super(builder);
-    this.setCredentialType(CredentialTypeForMetrics.IMPERSONATED_CREDENTIALS);
+    this.setMetricsCredentialType(CredentialTypeForMetrics.IMPERSONATED_CREDENTIALS);
     this.sourceCredentials = builder.getSourceCredentials();
     this.targetPrincipal = builder.getTargetPrincipal();
     this.delegates = builder.getDelegates();
@@ -516,7 +516,7 @@ public AccessToken refreshAccessToken() throws IOException {
         .set(
             MetricsUtils.API_CLIENT_HEADER,
             MetricsUtils.getGoogleCredentialsMetricsHeader(
-                RequestType.ACCESS_TOKEN_REQUEST, getCredentialType()));
+                RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType()));
 
     HttpResponse response = null;
     try {
@@ -567,7 +567,7 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
         targetAudience,
         includeEmail,
         ImmutableMap.of("delegates", this.delegates),
-        getCredentialType());
+        getMetricsCredentialType());
   }
 
   @Override

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

@@ -87,14 +87,35 @@ public String getLabel() {
     }
   }
 
+  /**
+   * Formulates metrics header string.
+   *
+   * <p>For UserCredentials access token or id token requests, no request type is specified, metric
+   * header string takes format: “gl-java/JAVA_VERSION auth/LIB_VERSION cred-type/u”
+   *
+   * <p>For MDS pin, credentials type should not include in header, metric header string takes
+   * format: “gl-java/JAVA_VERSION auth/LIB_VERSION auth-request-type/mds”
+   *
+   * <p>For ServiceAccountCredentials, ComputeEngineCredentials and ImpersonatedCredentials access
+   * token or id token requests, metric header string takes format “gl-java/JAVA_VERSION
+   * auth/LIB_VERSION auth-request-type/[it/at] cred-type/[mds/sa/imp]”
+   *
+   * @param requestType
+   * @param credentialTypeForMetrics
+   * @return
+   */
   static String getGoogleCredentialsMetricsHeader(
       RequestType requestType, CredentialTypeForMetrics credentialTypeForMetrics) {
+    // format for UserCredentials requests
     if (requestType == RequestType.UNSPECIFIED) {
       return String.format(
           "%s %s/%s",
-          MetricsUtils.getLanguageAndAuthLibraryVersions(), "cred-type", credentialTypeForMetrics.getLabel());
+          MetricsUtils.getLanguageAndAuthLibraryVersions(),
+          "cred-type",
+          credentialTypeForMetrics.getLabel());
     }
-    if (credentialTypeForMetrics == CredentialTypeForMetrics.UNKNOWN) {
+    // format for MDS pin
+    if (credentialTypeForMetrics == CredentialTypeForMetrics.DO_NOT_SEND) {
       return String.format(
           "%s %s/%s",
           MetricsUtils.getLanguageAndAuthLibraryVersions(),

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

@@ -512,7 +512,7 @@ public AccessToken refreshAccessToken() throws IOException {
         .set(
             MetricsUtils.API_CLIENT_HEADER,
             MetricsUtils.getGoogleCredentialsMetricsHeader(
-                RequestType.ACCESS_TOKEN_REQUEST, getCredentialType()));
+                RequestType.ACCESS_TOKEN_REQUEST, getMetricsCredentialType()));
     if (this.defaultRetriesEnabled) {
       request.setNumberOfRetries(OAuth2Utils.DEFAULT_NUMBER_OF_RETRIES);
     } else {
@@ -600,7 +600,7 @@ private IdToken getIdTokenOauthEndpoint(String targetAudience) throws IOExceptio
         .set(
             MetricsUtils.API_CLIENT_HEADER,
             MetricsUtils.getGoogleCredentialsMetricsHeader(
-                RequestType.ID_TOKEN_REQUEST, getCredentialType()));
+                RequestType.ID_TOKEN_REQUEST, getMetricsCredentialType()));
 
     HttpResponse httpResponse = executeRequest(request);
 
@@ -1030,11 +1030,11 @@ private Map<String, List<String>> getRequestMetadataForGdu(URI uri) throws IOExc
     if ((!createScopedRequired() && !useJwtAccessWithScope)
         || isConfiguredForDomainWideDelegation()) {
       // assertion token flow
-      this.setCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_AT);
+      this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_AT);
       return super.getRequestMetadata(uri);
     }
     // self-signed JWT flow
-    this.setCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT);
+    this.setMetricsCredentialType(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT);
     return getRequestMetadataWithSelfSignedJwt(uri);
   }
 

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

@@ -98,7 +98,7 @@ private UserCredentials(Builder builder) {
     Preconditions.checkState(
         builder.getAccessToken() != null || builder.refreshToken != null,
         "Either accessToken or refreshToken must not be null");
-    this.setCredentialType(CredentialTypeForMetrics.USER_CREDENTIALS);
+    this.setMetricsCredentialType(CredentialTypeForMetrics.USER_CREDENTIALS);
   }
 
   /**
@@ -273,7 +273,7 @@ private GenericData doRefreshAccessToken() throws IOException {
     additionalHeaders.set(
         MetricsUtils.API_CLIENT_HEADER,
         MetricsUtils.getGoogleCredentialsMetricsHeader(
-            RequestType.UNSPECIFIED, getCredentialType()));
+            RequestType.UNSPECIFIED, getMetricsCredentialType()));
     request.setHeaders(additionalHeaders);
     request.setParser(new JsonObjectParser(JSON_FACTORY));
     HttpResponse response;

oauth2_http/javatests/com/google/auth/oauth2/ServiceAccountCredentialsTest.java

@@ -1609,7 +1609,9 @@ public void getRequestMetadata_withScopes_selfSignedJWT() throws IOException {
 
     // Verify credentialType is correctly set. This is used for token usage metrics.
     // Self signed jwt flow doesn’t call any token endpoint, thus no token request metrics.
-    assertEquals(CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT, credentials.getCredentialType());
+    assertEquals(
+        CredentialTypeForMetrics.SERVICE_ACCOUNT_CREDENTIALS_JWT,
+        credentials.getMetricsCredentialType());
   }
 
   @Test