Adds BrokerPerformanceMetrics class and integrate performance metrics into token acquisition flow.

prsaminathan · Prvnkmr337 · commit 59b88e2f91a1 · 2025-12-15T20:31:00.000-08:00
- Added BrokerPerformanceMetrics.java to hold broker request latency data.
- AcquireTokenResult and BaseException hold instance of BrokerPerformanceMetrics for the related Broker request and response.
- MsalBrokerResultAdapter updated to read BrokerPerformanceMetrics data from Broker result bundle to be populated in AcquireTokenResult and BaseException.
diff --git a/common/src/main/java/com/microsoft/identity/common/internal/result/MsalBrokerResultAdapter.java b/common/src/main/java/com/microsoft/identity/common/internal/result/MsalBrokerResultAdapter.java
@@ -22,6 +22,8 @@
 //  THE SOFTWARE.
 package com.microsoft.identity.common.internal.result;
 
+import static com.microsoft.identity.common.java.AuthenticationConstants.Broker.BROKER_REQUEST_RECEIVED_TIMESTAMP;
+import static com.microsoft.identity.common.java.AuthenticationConstants.Broker.BROKER_RESPONSE_GENERATION_TIMESTAMP;
 import static com.microsoft.identity.common.adal.internal.AuthenticationConstants.Broker.BROKER_ACCOUNTS;
 import static com.microsoft.identity.common.adal.internal.AuthenticationConstants.Broker.BROKER_ACCOUNTS_COMPRESSED;
 import static com.microsoft.identity.common.adal.internal.AuthenticationConstants.Broker.BROKER_ACTIVITY_NAME;
@@ -58,6 +60,7 @@
 import com.microsoft.identity.common.internal.request.AuthenticationSchemeTypeAdapter;
 import com.microsoft.identity.common.internal.util.GzipUtil;
 import com.microsoft.identity.common.java.authorities.AzureActiveDirectoryAudience;
+import com.microsoft.identity.common.java.broker.BrokerPerformanceMetrics;
 import com.microsoft.identity.common.java.cache.CacheRecord;
 import com.microsoft.identity.common.java.cache.ICacheRecord;
 import com.microsoft.identity.common.java.commands.AcquirePrtSsoTokenBatchResult;
@@ -117,6 +120,7 @@ public class MsalBrokerResultAdapter implements IBrokerResultAdapter {
     private static final String TAG = MsalBrokerResultAdapter.class.getSimpleName();
     public static final Gson GSON = new Gson();
 
+    private static final Long INVALID_TIMESTAMP = -1L;
     private static final String DCF_NOT_SUPPORTED_ERROR = "deviceCodeFlowAuthRequest() not supported in BrokerMsalController";
     private static final String WEBAPPS_ENTRY_IS_NULL_ERROR = "WebApps entry in the bundle is null";
     interface IBooleanCallback {
@@ -401,15 +405,53 @@ public BaseException getBaseExceptionFromBundle(@NonNull final Bundle resultBund
         }
 
         final String exceptionType = brokerResult.getExceptionType();
+        final BrokerPerformanceMetrics metrics = getBrokerPerformanceMetricsFromBundle(resultBundle);
+        final BaseException baseException;
 
         if (!StringUtil.isNullOrEmpty(exceptionType)) {
-            return getBaseExceptionFromExceptionType(exceptionType, brokerResult);
+            baseException = getBaseExceptionFromExceptionType(exceptionType, brokerResult);
         } else {
             // This code is here for legacy purposes where old versions of broker (3.1.8 or below)
             // wouldn't return exception type in the result.
             Logger.info(methodTag, "Exception type is not returned from the broker, " +
                     "using error codes to transform to the right exception");
-            return getBaseExceptionFromErrorCodes(brokerResult);
+            baseException = getBaseExceptionFromErrorCodes(brokerResult);
+        }
+
+        // Attach broker performance metrics if available
+        if (metrics != null) {
+            baseException.setBrokerPerformanceMetrics(metrics);
+        }
+
+        return baseException;
+    }
+
+    /**
+     * Extracts broker performance metrics from the result bundle if available.
+     *
+     * @param resultBundle The result bundle returned from the broker.
+     * @return {@link BrokerPerformanceMetrics} if available, null otherwise.
+     */
+    @Nullable
+    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+    public BrokerPerformanceMetrics getBrokerPerformanceMetricsFromBundle(@NonNull final Bundle resultBundle) {
+        final long brokerRequestReceivedTimestamp = resultBundle.getLong(
+                BROKER_REQUEST_RECEIVED_TIMESTAMP,
+                INVALID_TIMESTAMP
+        );
+        final long brokerResponseGenerationTimestamp = resultBundle.getLong(
+                BROKER_RESPONSE_GENERATION_TIMESTAMP,
+                INVALID_TIMESTAMP
+        );
+
+        if (brokerRequestReceivedTimestamp != INVALID_TIMESTAMP && brokerResponseGenerationTimestamp != INVALID_TIMESTAMP) {
+            return new BrokerPerformanceMetrics(
+                    brokerRequestReceivedTimestamp,
+                    brokerResponseGenerationTimestamp
+            );
+        } else {
+            Logger.warn(TAG, "Broker performance metrics not found in the result bundle.");
+            return null;
         }
     }
 
@@ -867,7 +909,11 @@ AcquireTokenResult getAcquireTokenResultFromResultBundle(@NonNull final Bundle r
             acquireTokenResult.setLocalAuthenticationResult(
                     resultAdapter.authenticationResultFromBundle(resultBundle)
             );
-
+            // Set broker performance metrics if available
+            final BrokerPerformanceMetrics brokerPerformanceMetrics = resultAdapter.getBrokerPerformanceMetricsFromBundle(resultBundle);
+            if (brokerPerformanceMetrics != null) {
+                acquireTokenResult.setBrokerPerformanceMetrics(brokerPerformanceMetrics);
+            }
             return acquireTokenResult;
         }
 
diff --git a/common/src/test/java/com/microsoft/identity/common/internal/request/MsalBrokerResultAdapterTests.kt b/common/src/test/java/com/microsoft/identity/common/internal/request/MsalBrokerResultAdapterTests.kt
@@ -381,4 +381,46 @@ class MsalBrokerResultAdapterTests {
         assertEquals(mockErrorCode, receivedException.errorCode)
         assertEquals(mockErrorMessage, receivedException.message)
     }
+
+    @Test
+    fun testGetBrokerPerformanceMetricsFromBundle_WithValidTimestamps() {
+        val mockRequestReceivedTimestamp = 123456789L
+        val mockResponseGenerationTimestamp = 987654321L
+        val resultAdapter = MsalBrokerResultAdapter()
+
+        val resultBundle = android.os.Bundle().apply {
+            putLong(
+                com.microsoft.identity.common.java.AuthenticationConstants.Broker.BROKER_REQUEST_RECEIVED_TIMESTAMP,
+                mockRequestReceivedTimestamp
+            )
+            putLong(
+                com.microsoft.identity.common.java.AuthenticationConstants.Broker.BROKER_RESPONSE_GENERATION_TIMESTAMP,
+                mockResponseGenerationTimestamp
+            )
+        }
+
+        val metrics = resultAdapter.getBrokerPerformanceMetricsFromBundle(resultBundle)
+
+        assertNotNull(metrics)
+
+        // Validate timestamp values
+        assertEquals(mockRequestReceivedTimestamp, metrics!!.brokerRequestReceivedTimestamp)
+        assertEquals(mockResponseGenerationTimestamp, metrics.brokerResponseGenerationTimestamp)
+
+        // Validate calculated broker handling time
+        val expectedBrokerHandlingTime = mockResponseGenerationTimestamp - mockRequestReceivedTimestamp
+        assertEquals(expectedBrokerHandlingTime, metrics.brokerHandlingTime)
+
+        // Validate response latency (should be >= 0)
+        assertNotNull(metrics.responseLatency)
+        assertTrue(metrics.responseLatency >= 0)
+    }
+
+    @Test
+    fun testGetBrokerPerformanceMetricsFromBundle_WithoutTimestamps() {
+        val resultAdapter = MsalBrokerResultAdapter()
+        val resultBundle = android.os.Bundle() // Empty bundle, no timestamps
+        val metrics = resultAdapter.getBrokerPerformanceMetricsFromBundle(resultBundle)
+        assertNull(metrics)
+    }
 }
diff --git a/common4j/src/main/com/microsoft/identity/common/java/broker/BrokerPerformanceMetrics.java b/common4j/src/main/com/microsoft/identity/common/java/broker/BrokerPerformanceMetrics.java
@@ -0,0 +1,70 @@
+package com.microsoft.identity.common.java.broker;
+
+/**
+ * Holds broker performance metrics derived from timestamps in authentication flows.
+ * Calculates processing and latency durations at construction time.
+ */
+public class BrokerPerformanceMetrics {
+    /**
+     * Time spent by broker processing the request (in milliseconds).
+     * Calculated as: brokerResponseGenerationTimestamp - brokerRequestReceivedTimestamp
+     */
+    private final Long brokerHandlingTime;
+
+    /**
+     * Time for the response to reach and be processed by the client (in milliseconds).
+     * Calculated as: currentTime - brokerResponseGenerationTimestamp
+     */
+    private final Long responseLatency;
+
+
+    /**
+     * Timestamp when the broker received the authentication request (epoch milliseconds).
+     * Used to calculate broker handling time.
+     */
+    private final Long brokerRequestReceivedTimestamp;
+
+    /**
+     * Timestamp when the broker generated the authentication response (epoch milliseconds).
+     * Used to calculate both broker handling time and response latency.
+     */
+    private final Long brokerResponseGenerationTimestamp;
+
+    /**
+     * Creates broker performance metrics with calculated durations.
+     *
+     * @param brokerRequestReceivedTimestamp When broker received the request (epoch millis)
+     * @param brokerResponseGenerationTimestamp When broker generated the response (epoch millis)
+     */
+    public BrokerPerformanceMetrics(final Long brokerRequestReceivedTimestamp,
+                                    final Long brokerResponseGenerationTimestamp) {
+        this.brokerRequestReceivedTimestamp = brokerRequestReceivedTimestamp;
+        this.brokerResponseGenerationTimestamp = brokerResponseGenerationTimestamp;
+        this.brokerHandlingTime = brokerResponseGenerationTimestamp - brokerRequestReceivedTimestamp;
+        this.responseLatency = System.currentTimeMillis() - brokerResponseGenerationTimestamp;
+    }
+
+    public Long getBrokerHandlingTime() {
+        return brokerHandlingTime;
+    }
+
+    public Long getBrokerRequestReceivedTimestamp() {
+        return brokerRequestReceivedTimestamp;
+    }
+
+    public Long getBrokerResponseGenerationTimestamp() {
+        return brokerResponseGenerationTimestamp;
+    }
+
+    public Long getResponseLatency() {
+        return responseLatency;
+    }
+
+    @Override
+    public String toString() {
+        return "BrokerPerformanceMetrics{" +
+                "brokerHandlingTime=" + brokerHandlingTime +
+                ", responseLatency=" + responseLatency +
+                ", brokerRequestReceivedTimestamp=" + brokerRequestReceivedTimestamp ;
+    }
+}
diff --git a/common4j/src/main/com/microsoft/identity/common/java/exception/BaseException.java b/common4j/src/main/com/microsoft/identity/common/java/exception/BaseException.java
@@ -22,6 +22,7 @@
 // THE SOFTWARE.
 package com.microsoft.identity.common.java.exception;
 
+import com.microsoft.identity.common.java.broker.BrokerPerformanceMetrics;
 import com.microsoft.identity.common.java.telemetry.ITelemetryAccessor;
 import com.microsoft.identity.common.java.telemetry.Telemetry;
 import com.microsoft.identity.common.java.telemetry.events.ErrorEvent;
@@ -79,6 +80,8 @@ public class BaseException extends Exception implements IErrorInformation, ITele
 
     private final List<Map<String, String>> mTelemetry = new ArrayList<>();
 
+    private BrokerPerformanceMetrics brokerPerformanceMetrics;
+
     /**
      * {@link Exception#addSuppressed(Throwable)} requires API19 in Android, so we're creating our own.
      */
@@ -216,6 +219,15 @@ public String getUsername() {
         return mUsername;
     }
 
+    public void setBrokerPerformanceMetrics(final BrokerPerformanceMetrics brokerPerformanceMetrics) {
+        this.brokerPerformanceMetrics = brokerPerformanceMetrics;
+    }
+
+    @Nullable
+    public BrokerPerformanceMetrics getBrokerPerformanceMetrics() {
+        return brokerPerformanceMetrics;
+    }
+
     public void setUsername(@Nullable final String username) {
         this.mUsername = username;
     }
diff --git a/common4j/src/main/com/microsoft/identity/common/java/result/AcquireTokenResult.java b/common4j/src/main/com/microsoft/identity/common/java/result/AcquireTokenResult.java
@@ -23,10 +23,14 @@
 package com.microsoft.identity.common.java.result;
 
 import com.microsoft.identity.common.java.WarningType;
+import com.microsoft.identity.common.java.broker.BrokerPerformanceMetrics;
 import com.microsoft.identity.common.java.providers.oauth2.TokenResult;
 import com.microsoft.identity.common.java.providers.oauth2.AuthorizationResult;
 import com.microsoft.identity.common.java.result.ILocalAuthenticationResult;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
 public class AcquireTokenResult {
 
     private ILocalAuthenticationResult mLocalAuthenticationResult;
@@ -37,6 +41,8 @@ public class AcquireTokenResult {
 
     private Boolean mSucceeded = false;
 
+    private BrokerPerformanceMetrics mBrokerPerformanceMetrics;
+
     public void setLocalAuthenticationResult(ILocalAuthenticationResult result) {
         this.mLocalAuthenticationResult = result;
         this.mSucceeded = true;
@@ -54,6 +60,15 @@ public void setTokenResult(TokenResult tokenResult) {
         this.mTokenResult = tokenResult;
     }
 
+    public void setBrokerPerformanceMetrics(@Nonnull BrokerPerformanceMetrics mBrokerPerformanceMetrics) {
+        this.mBrokerPerformanceMetrics = mBrokerPerformanceMetrics;
+    }
+
+    @Nullable
+    public BrokerPerformanceMetrics getBrokerPerformanceMetrics() {
+        return mBrokerPerformanceMetrics;
+    }
+
     // Suppressing rawtype warnings due to the generic type AuthorizationResult
     @SuppressWarnings(WarningType.rawtype_warning)
     public AuthorizationResult getAuthorizationResult() {
