feat: Allow overriding creation of OkHttp Call (#1257)

doc/configuration.md

@@ -14,6 +14,7 @@
     - [Token URL](#token-url-deprecated)
     - [Revoke URL](#revoke-url-deprecated)
 - [SSL configuration](#ssl-configuration)
+- [Instrumenation of OpenTelemetry](#instrumenation-of-opentelemetry)
 
 # Proxy configuration
 
@@ -181,7 +182,7 @@ api.setReadTimeout(readTimeout);
 
 default value is `0` which mean API waits forever to read data from connection.
 
-## URLs configuration
+# URLs configuration
 
 ### Base URL
 The default base URL used for making API calls to Box can be changed by calling `BoxAPIConnection#setBaseURL(String)` 
@@ -290,3 +291,39 @@ BoxAPIConnection api = new BoxAPIConnection(...);
 X509TrustManager trustManager = ...
 api.configureSslCertificatesValidation(trustManager, BoxAPIConnection.DEFAULT_HOSTNAME_VERIFIER);
 ```
+
+# Instrumenation of OpenTelemetry
+
+OpenTelemetry is an observability framework and toolkit for creating and managing telemetry data, such as traces,
+metrics, and logs. The Box Java SDK can be instrumented with OpenTelemetry to collect telemetry data about the
+requests made by the SDK.  
+
+To start, add the [opentelemetry-okhttp-3.0](https://mvnrepository.com/artifact/io.opentelemetry.instrumentation/opentelemetry-okhttp-3.0) dependency to your project.
+Next, create a custom class that extends BoxAPIConnection and integrates telemetry in the overridden `createNewCall` method.
+Here's an example implementation:
+```java
+public class BoxAPIConnectionWithTelemetry extends BoxAPIConnection {
+
+    private OkHttpTelemetry telemetry;
+
+    public BoxAPIConnectionWithTelemetry(String accessToken) {
+        super(accessToken);
+    }
+
+    /**
+     * Add required constructors
+     */
+
+    public void setTelemetry(OpenTelemetry openTelemetry) {
+        this.telemetry = OkHttpTelemetry.builder(openTelemetry).build();
+    }
+
+    protected Call createNewCall(OkHttpClient httpClient, Request request) {
+        return this.telemetry.newCallFactory(httpClient).newCall(request);
+    }
+}
+
+```
+
+Please note that you should not modify either `httpClient` or `request` parameters in the createNewCall method.
+Altering these parameters can discard the BoxAPIConnection configuration and lead to unexpected behavior.

src/main/java/com/box/sdk/BoxAPIConnection.java

@@ -29,6 +29,7 @@
 import javax.net.ssl.TrustManager;
 import javax.net.ssl.X509TrustManager;
 import okhttp3.Authenticator;
+import okhttp3.Call;
 import okhttp3.Credentials;
 import okhttp3.OkHttpClient;
 import okhttp3.Request;
@@ -1253,9 +1254,13 @@ Response executeWithoutRedirect(Request request) {
         return executeOnClient(noRedirectsHttpClient, request);
     }
 
+    protected Call createNewCall(OkHttpClient httpClient, Request request) {
+        return httpClient.newCall(request);
+    }
+
     private Response executeOnClient(OkHttpClient httpClient, Request request) {
         try {
-            return httpClient.newCall(request).execute();
+            return createNewCall(httpClient, request).execute();
         } catch (IOException e) {
             throw new BoxAPIException("Couldn't connect to the Box API due to a network error. Request\n" + request, e);
         }