Report usage of stripe_client

build.gradle

@@ -50,6 +50,10 @@ tasks.withType(JavaCompile) {
       // com.stripe.param.AccountUpdateParams.Individual.Address] within this file.)
       // We should fix this by having autogen use the fully-qualified class to eliminate ambiguity.
       check("SameNameButDifferent", net.ltgt.gradle.errorprone.CheckSeverity.OFF)
+
+      // InlineMe (https://errorprone.info/docs/inlineme) seems neat, but in order to add these annotations
+      // we would be imposing another dependency on `errorprone` to our users, not worth it.
+      check("InlineMeSuggester", net.ltgt.gradle.errorprone.CheckSeverity.OFF)
     }
 }
 

src/main/java/com/stripe/net/ApiRequest.java

@@ -1,20 +1,49 @@
 package com.stripe.net;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import lombok.Getter;
 
 @Getter
 public class ApiRequest extends BaseApiRequest {
   private Map<String, Object> params;
 
+  private ApiRequest(
+      BaseAddress baseAddress,
+      ApiResource.RequestMethod method,
+      String path,
+      RequestOptions options,
+      ApiMode apiMode,
+      List<String> usage,
+      Map<String, Object> params) {
+    super(baseAddress, method, path, options, apiMode, usage);
+    this.params = params;
+  }
+
   public ApiRequest(
       BaseAddress baseAddress,
       ApiResource.RequestMethod method,
       String path,
       Map<String, Object> params,
       RequestOptions options,
       ApiMode apiMode) {
-    super(baseAddress, method, path, options, apiMode);
-    this.params = params;
+    this(baseAddress, method, path, options, apiMode, null, params);
+  }
+
+  public ApiRequest withAddedUsage(String usage) {
+    List<String> newUsage = new ArrayList<>();
+    if (this.getUsage() != null) {
+      newUsage.addAll(this.getUsage());
+    }
+    newUsage.add(usage);
+    return new ApiRequest(
+        this.getBaseAddress(),
+        this.getMethod(),
+        this.getPath(),
+        this.getOptions(),
+        this.getApiMode(),
+        newUsage,
+        this.getParams());
   }
 }

src/main/java/com/stripe/net/BaseApiRequest.java

@@ -1,29 +1,25 @@
 package com.stripe.net;
 
 import java.util.List;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
 import lombok.Getter;
-import lombok.Setter;
 
 @Getter
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
 class BaseApiRequest {
-  private BaseAddress baseAddress;
-  private ApiResource.RequestMethod method;
-  private String path;
-  private RequestOptions options;
-  private ApiMode apiMode;
+  private final BaseAddress baseAddress;
+  private final ApiResource.RequestMethod method;
+  private final String path;
+  private final RequestOptions options;
+  private final ApiMode apiMode;
 
-  @Setter private List<String> usage;
+  // TODO (major): Remove setter and make final
+  private List<String> usage;
 
-  public BaseApiRequest(
-      BaseAddress baseAddress,
-      ApiResource.RequestMethod method,
-      String path,
-      RequestOptions options,
-      ApiMode apiMode) {
-    this.baseAddress = baseAddress;
-    this.method = method;
-    this.path = path;
-    this.options = options;
-    this.apiMode = apiMode;
+  /** @deprecated Use {@link com.stripe.net.ApiRequest#withAddedUsage(String)} instead. */
+  @Deprecated
+  public void setUsage(List<String> usage) {
+    this.usage = usage;
   }
 }

src/main/java/com/stripe/net/HttpClient.java

@@ -67,7 +67,7 @@ private <T extends AbstractStripeResponse<?>> T sendWithTelemetry(
 
     stopwatch.stop();
 
-    requestTelemetry.maybeEnqueueMetrics(response, stopwatch.getElapsed());
+    requestTelemetry.maybeEnqueueMetrics(response, stopwatch.getElapsed(), request.usage());
 
     return response;
   }

src/main/java/com/stripe/net/LiveStripeResponseGetter.java

@@ -50,7 +50,8 @@ private StripeRequest toStripeRequest(ApiRequest apiRequest) throws StripeExcept
         apiRequest.getMethod(),
         fullUrl,
         apiRequest.getParams(),
-        RequestOptions.merge(this.options, apiRequest.getOptions()));
+        RequestOptions.merge(this.options, apiRequest.getOptions()),
+        apiRequest.getUsage());
   }
 
   @Override

src/main/java/com/stripe/net/RequestTelemetry.java

@@ -4,6 +4,8 @@
 import com.google.gson.annotations.SerializedName;
 import com.stripe.Stripe;
 import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import lombok.Data;
@@ -45,14 +47,25 @@ public Optional<String> getHeaderValue(HttpHeaders headers) {
     return Optional.of(gson.toJson(payload));
   }
 
+  // TODO (major) remove this overload
+  /**
+   * @deprecated use {@link #maybeEnqueueMetrics(AbstractStripeResponse, Duration, List)} instead.
+   */
+  @Deprecated
+  public void maybeEnqueueMetrics(AbstractStripeResponse<?> response, Duration duration) {
+    maybeEnqueueMetrics(response, duration, new ArrayList<String>());
+  }
+
   /**
    * If telemetry is enabled and the queue is not full, then enqueue a new metrics item; otherwise,
    * do nothing.
    *
    * @param response the Stripe response
    * @param duration the request duration
+   * @param usage a list of tracked features used by the corresponding request
    */
-  public void maybeEnqueueMetrics(AbstractStripeResponse<?> response, Duration duration) {
+  public void maybeEnqueueMetrics(
+      AbstractStripeResponse<?> response, Duration duration, List<String> usage) {
     if (!Stripe.enableTelemetry) {
       return;
     }
@@ -65,7 +78,11 @@ public void maybeEnqueueMetrics(AbstractStripeResponse<?> response, Duration dur
       return;
     }
 
-    RequestMetrics metrics = new RequestMetrics(response.requestId(), duration.toMillis());
+    if (usage != null && usage.size() == 0) {
+      usage = null;
+    }
+
+    RequestMetrics metrics = new RequestMetrics(response.requestId(), duration.toMillis(), usage);
     prevRequestMetrics.add(metrics);
   }
 
@@ -82,5 +99,8 @@ private static class RequestMetrics {
 
     @SerializedName("request_duration_ms")
     private final long requestDurationMs;
+
+    @SerializedName("usage")
+    private final List<String> usage;
   }
 }

src/main/java/com/stripe/net/StripeRequest.java

@@ -51,20 +51,25 @@ public class StripeRequest {
   /** The special modifiers of the request. */
   RequestOptions options;
 
+  /** List of tracked behaviors associated with this request. */
+  List<String> usage;
+
   /**
    * Initializes a new instance of the {@link StripeRequest} class.
    *
    * @param method the HTTP method
    * @param url the URL of the request
    * @param params the parameters of the request
    * @param options the special modifiers of the request
+   * @param usage list of tracked behaviors associated with this request
    * @throws StripeException if the request cannot be initialized for any reason
    */
   public StripeRequest(
       ApiResource.RequestMethod method,
       String url,
       Map<String, Object> params,
-      RequestOptions options)
+      RequestOptions options,
+      List<String> usage)
       throws StripeException {
     try {
       this.params = (params != null) ? Collections.unmodifiableMap(params) : null;
@@ -73,6 +78,7 @@ public StripeRequest(
       this.url = buildURL(method, url, params);
       this.content = buildContent(method, params);
       this.headers = buildHeaders(method, this.options);
+      this.usage = usage;
     } catch (IOException e) {
       throw new ApiConnectionException(
           String.format(
@@ -85,6 +91,15 @@ public StripeRequest(
     }
   }
 
+  public StripeRequest(
+      ApiResource.RequestMethod method,
+      String url,
+      Map<String, Object> params,
+      RequestOptions options)
+      throws StripeException {
+    this(method, url, params, options, Collections.emptyList());
+  }
+
   /**
    * Returns a new {@link StripeRequest} instance with an additional header.
    *
@@ -99,7 +114,8 @@ public StripeRequest withAdditionalHeader(String name, String value) {
         this.content,
         this.headers.withAdditionalHeader(name, value),
         this.params,
-        this.options);
+        this.options,
+        this.usage);
   }
 
   private static URL buildURL(

src/main/java/com/stripe/net/StripeResponseGetterOptions.java

@@ -5,8 +5,7 @@
 
 /** Controls how the request is sent by {@link StripeResponseGetter} */
 public abstract class StripeResponseGetterOptions {
-
-  // When adding setting here keep them in sync with settings in RequestOptions and
+  // When adding settings here keep them in sync with settings in RequestOptions and
   // in the RequestOptions.merge method
   public abstract String getApiKey();
 

src/main/java/com/stripe/service/AccountLinkService.java

@@ -40,6 +40,7 @@ public AccountLink create(AccountLinkCreateParams params, RequestOptions options
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, AccountLink.class);
   }
 }

src/main/java/com/stripe/service/AccountService.java

@@ -55,6 +55,7 @@ public Account delete(String account, RequestOptions options) throws StripeExcep
     ApiRequest request =
         new ApiRequest(
             BaseAddress.API, ApiResource.RequestMethod.DELETE, path, null, options, ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
   /** Retrieves the details of an account. */
@@ -81,6 +82,7 @@ public Account retrieve(String account, AccountRetrieveParams params, RequestOpt
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
   /**
@@ -163,6 +165,7 @@ public Account update(String account, AccountUpdateParams params, RequestOptions
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
   /** Retrieves the details of an account. */
@@ -189,6 +192,7 @@ public Account retrieveCurrent(AccountRetrieveCurrentParams params, RequestOptio
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
   /**
@@ -231,6 +235,7 @@ public StripeCollection<Account> list(AccountListParams params, RequestOptions o
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter()
         .request(request, new TypeToken<StripeCollection<Account>>() {}.getType());
   }
@@ -293,6 +298,7 @@ public Account create(AccountCreateParams params, RequestOptions options) throws
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
   /**
@@ -323,6 +329,7 @@ public Account reject(String account, AccountRejectParams params, RequestOptions
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Account.class);
   }
 

src/main/java/com/stripe/service/AccountSessionService.java

@@ -40,6 +40,7 @@ public AccountSession create(AccountSessionCreateParams params, RequestOptions o
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, AccountSession.class);
   }
 }

src/main/java/com/stripe/service/ApplePayDomainService.java

@@ -32,6 +32,7 @@ public ApplePayDomain delete(String domain, RequestOptions options) throws Strip
     ApiRequest request =
         new ApiRequest(
             BaseAddress.API, ApiResource.RequestMethod.DELETE, path, null, options, ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, ApplePayDomain.class);
   }
   /** Retrieve an apple pay domain. */
@@ -60,6 +61,7 @@ public ApplePayDomain retrieve(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, ApplePayDomain.class);
   }
   /** List apple pay domains. */
@@ -87,6 +89,7 @@ public StripeCollection<ApplePayDomain> list(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter()
         .request(request, new TypeToken<StripeCollection<ApplePayDomain>>() {}.getType());
   }
@@ -106,6 +109,7 @@ public ApplePayDomain create(ApplePayDomainCreateParams params, RequestOptions o
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, ApplePayDomain.class);
   }
 }

src/main/java/com/stripe/service/ApplicationFeeService.java

@@ -58,6 +58,7 @@ public StripeCollection<ApplicationFee> list(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter()
         .request(request, new TypeToken<StripeCollection<ApplicationFee>>() {}.getType());
   }
@@ -99,6 +100,7 @@ public ApplicationFee retrieve(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, ApplicationFee.class);
   }
 

src/main/java/com/stripe/service/BalanceService.java

@@ -62,6 +62,7 @@ public Balance retrieve(BalanceRetrieveParams params, RequestOptions options)
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, Balance.class);
   }
 }

src/main/java/com/stripe/service/BalanceTransactionService.java

@@ -74,6 +74,7 @@ public StripeCollection<BalanceTransaction> list(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter()
         .request(request, new TypeToken<StripeCollection<BalanceTransaction>>() {}.getType());
   }
@@ -119,6 +120,7 @@ public BalanceTransaction retrieve(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.withAddedUsage("stripe_client");
     return getResponseGetter().request(request, BalanceTransaction.class);
   }
 }