From 4f02ae3446fbfdfe34fbb1e278863135b031815a Mon Sep 17 00:00:00 2001
From: lsocha <lsocha@box.com>
Date: Wed, 3 Jul 2024 15:47:55 +0200
Subject: [PATCH 1/4] feat: Allow overriding creation of OkHttp call

---
 src/main/java/com/box/sdk/BoxAPIConnection.java | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/box/sdk/BoxAPIConnection.java b/src/main/java/com/box/sdk/BoxAPIConnection.java
index 5a5d674cf..17ac3f884 100644
--- a/src/main/java/com/box/sdk/BoxAPIConnection.java
+++ b/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);
         }

From c6ebd1fa0c477dec9dec9c03022ae0e52b4bde32 Mon Sep 17 00:00:00 2001
From: lsocha <lsocha@box.com>
Date: Fri, 12 Jul 2024 16:17:36 +0200
Subject: [PATCH 2/4] Add docs about instrumenting OpenTelemetry

---
 doc/configuration.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/doc/configuration.md b/doc/configuration.md
index 0fac2bbe4..b377cd41c 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -290,3 +290,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 BoxCustomConnection(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.
\ No newline at end of file

From 15912e4cdf8e57448016539a868097ba7665e11f Mon Sep 17 00:00:00 2001
From: lsocha <lsocha@box.com>
Date: Fri, 12 Jul 2024 16:20:14 +0200
Subject: [PATCH 3/4] TOC update

---
 doc/configuration.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/configuration.md b/doc/configuration.md
index b377cd41c..a20a7b578 100644
--- a/doc/configuration.md
+++ b/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)` 

From bf231fe947c63d73e05dee79db79e6f9fe4ce7b5 Mon Sep 17 00:00:00 2001
From: lsocha <lsocha@box.com>
Date: Fri, 12 Jul 2024 16:35:54 +0200
Subject: [PATCH 4/4] fix example

---
 doc/configuration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/configuration.md b/doc/configuration.md
index a20a7b578..030b9d171 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -306,7 +306,7 @@ public class BoxAPIConnectionWithTelemetry extends BoxAPIConnection {
 
     private OkHttpTelemetry telemetry;
 
-    public BoxCustomConnection(String accessToken) {
+    public BoxAPIConnectionWithTelemetry(String accessToken) {
         super(accessToken);
     }