Merge branch 'dev' into remove-debug-msal-common

Author: jasonnutter

change/@azure-msal-browser-62540013-2853-4e3a-b65e-04222e69e2cb.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add performance telemetry API #4570",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-30d5fe02-e6aa-43c1-bd77-10c3a52bbbf2.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add performance telemetry API #4570",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-c6c7d65f-1194-4c39-8711-3e23b6311db0.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Use IGuidGenerator interface for GuidGenerator class #4570",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-react-a23c0995-33e5-4b68-a222-fd8dfc0efa0d.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Use React 17 for dev deps #4570",
+  "packageName": "@azure/msal-react",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/docs/performance.md

@@ -50,3 +50,82 @@ const msalInstance = new msal.PublicClientApplication({
     }
 });
 ```
+
+## Measuring performance
+
+Applications that want to measure the performance of authentication flows in MSAL.js can do so manually, or consume the performance measures taken by the library itself.
+
+### addPerformanceCallback
+
+Since version `@azure/[email protected]`, applications can register a callback to receive performance measurements taken by the library. These measurement will include end-to-end measurements for top-level APIs, as well as measurements for important internal APIs.
+
+**Note for MSFT first-party applications**: We will be publishing an internal build of `@azure/msal-browser` that is already instrumented to capture this telemetry. Contact us for more details.
+
+#### Example
+
+```typescript
+const msalInstance = new PublicClientApplication(config);
+
+msalInstance.addPerformanceCallback((events: PerformanceEvent[]) => {
+    events.forEach(event => {
+        console.log(event);
+    });
+});
+```
+
+Example event:
+
+```typescript
+const event: PerformanceEvent = {
+    correlationId: "03cad3ff-6682-4e3d-a0b4-d517b531c718",
+	durationMs: 1873,
+	endPageVisibility: "hidden",
+	fromCache: false,
+	name: "acquireTokenSilent",
+	startPageVisibility: "visible",
+	startTimeMs: 1636414041888,
+	success: true,
+    silentCacheClientAcquireTokenDurationMs: 0,
+    silentRefreshClientAcquireTokenDurationMs: 150,
+    silentIframeClientAcquireTokenDurationMs: 0
+    cryptoOptsGetPublicKeyThumbprintDurationMs: 200,
+    cryptoOptsSignJwtDurationMs: 8,
+    clientId: "b50703d7-d12b-4ddc-8758-91053fe0aba4",
+    authority: "https://login.microsoftonline.com/common",
+    libraryName: "@azure/msal-browser-1p",
+    libraryVersion: "2.22.2-beta.2",
+    appName: "my-application",
+    appVersion: "1.0.0"
+}
+```
+
+The complete details for `PerformanceEvents` objects can be found [here](../../msal-common/src/telemetry/performance/PerformanceEvent.ts). Below is a list of some notable properties:
+
+| **Property**                       | Type      | Description                                                            |
+| ---------------------------------- | --------- | ---------------------------------------------------------------------- |
+| `name`                             | `string`  | Name of the operation, usually matches the top-level API name (e.g. `acquireTokenSilent`, `acquireTokenByCode`, `ssoSilent`). |
+| `durationMs`                       | `number`  | End-to-end duration in milliseconds for the operation.                 |
+| `success`                          | `boolean` | Whether the operation was successful or not.                           |
+| `fromCache`                        | `boolean` | Whether the operation retrieved the result from the cache.             |
+| `correlationId`                    | `string`  | Correlation ID used for the operation (preferably unique per request). |
+| `libraryVersion`                   | `string`  | Version of MSAL.js used for the operation.                             |
+| `authority`                        | `string`  | Authority used for the operation.                                      |
+| `<internalFunctionName>DurationMs` | `number`  | Duration in milliseconds for an internal operation.                    |
+
+### removePerformanceCallback
+
+The `addPerformanceCallback` API will return a callback id, which an application can pass to `PublicClientApplication.removePerformanceCallback` to unregister that callback from receiving performance events. It will return a boolean indicating whether or not the callback was successfully removed.
+
+#### Example
+
+```typescript
+const msalInstance = new PublicClientApplication(config);
+
+const callbackId: string = msalInstance.addPerformanceCallback((events: PerformanceEvent[]) => {
+    events.forEach(event => {
+        console.log(event);
+    });
+});
+
+const removed: boolean = msalInstance.removePerformanceCallback(callbackId);
+```