Report usage of stripe_client

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 addUsage(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#addUsage(String)} instead. */
+  @Deprecated
+  public void setUsage(List<String> usage) {
+    this.usage = usage;
   }
 }

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

@@ -48,7 +48,6 @@ public StripeResponseStream requestStream(StripeRequest request) throws StripeEx
   private interface RequestSendFunction<R> {
     R apply(StripeRequest request) throws StripeException;
   }
-
   /**
    * @param request the request
    * @return the response

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

@@ -16,6 +16,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.lang.reflect.Type;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 
@@ -31,15 +32,16 @@ private interface RequestSendFunction<R> {
   }
 
   private <T extends AbstractStripeResponse<?>> T sendWithTelemetry(
-      StripeRequest request, RequestSendFunction<T> send) throws StripeException {
+      StripeRequest request, List<String> usage, RequestSendFunction<T> send)
+      throws StripeException {
 
     Stopwatch stopwatch = Stopwatch.startNew();
 
     T response = send.apply(request);
 
     stopwatch.stop();
 
-    requestTelemetry.maybeEnqueueMetrics(response, stopwatch.getElapsed());
+    requestTelemetry.maybeEnqueueMetrics(response, stopwatch.getElapsed(), usage);
 
     return response;
   }
@@ -89,7 +91,8 @@ public <T extends StripeObjectInterface> T request(ApiRequest apiRequest, Type t
       throws StripeException {
 
     StripeRequest request = toStripeRequest(apiRequest);
-    StripeResponse response = sendWithTelemetry(request, r -> httpClient.requestWithRetries(r));
+    StripeResponse response =
+        sendWithTelemetry(request, apiRequest.getUsage(), r -> httpClient.requestWithRetries(r));
 
     int responseCode = response.code();
     String responseBody = response.body();
@@ -120,7 +123,8 @@ public <T extends StripeObjectInterface> T request(ApiRequest apiRequest, Type t
   public InputStream requestStream(ApiRequest apiRequest) throws StripeException {
     StripeRequest request = toStripeRequest(apiRequest);
     StripeResponseStream responseStream =
-        sendWithTelemetry(request, r -> httpClient.requestStreamWithRetries(r));
+        sendWithTelemetry(
+            request, apiRequest.getUsage(), r -> httpClient.requestStreamWithRetries(r));
 
     int responseCode = responseStream.code();
 

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;
@@ -51,14 +53,25 @@ public Optional<String> pollPayload() {
     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;
     }
@@ -71,7 +84,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);
   }
 
@@ -88,5 +105,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/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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("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.addUsage("stripe_client");
     return getResponseGetter().request(request, BalanceTransaction.class);
   }
 }

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

@@ -48,6 +48,7 @@ public BankAccount verify(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.addUsage("stripe_client");
     return getResponseGetter().request(request, BankAccount.class);
   }
 }

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

@@ -60,6 +60,7 @@ public StripeCollection<Capability> list(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.addUsage("stripe_client");
     return getResponseGetter()
         .request(request, new TypeToken<StripeCollection<Capability>>() {}.getType());
   }
@@ -93,6 +94,7 @@ public Capability retrieve(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.addUsage("stripe_client");
     return getResponseGetter().request(request, Capability.class);
   }
   /**
@@ -137,6 +139,7 @@ public Capability update(
             ApiRequestParams.paramsToMap(params),
             options,
             ApiMode.V1);
+    request = request.addUsage("stripe_client");
     return getResponseGetter().request(request, Capability.class);
   }
 }