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;
   }
@@ -75,7 +77,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());
     if (telemetryHeaderValue.isPresent()) {
       request =
           request.withAdditionalHeader(RequestTelemetry.HEADER_NAME, telemetryHeaderValue.get());
@@ -89,7 +92,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 +124,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/StripeRequest.java

@@ -15,6 +15,7 @@
 import java.util.UUID;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
+import lombok.Getter;
 import lombok.Value;
 import lombok.experimental.Accessors;
 
@@ -51,20 +52,26 @@ public class StripeRequest {
   /** The special modifiers of the request. */
   RequestOptions options;
 
+  /** List of tracked behaviors associated with this request. */
+  @Getter(AccessLevel.PACKAGE)
+  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 +80,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 +93,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 +116,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.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);
   }
 }