Merge pull request #270506 from enricohuang/patch-23

Add troubleshooting guide for Azure Communication Services Web Calling SDK -  references

Author: JamesJBarnett

articles/communication-services/resources/troubleshooting/voice-video-calling/references/how-to-collect-browser-verbose-log.md

@@ -0,0 +1,37 @@
+---
+title: References - How to collect verbose log from browsers
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to collect verbose log from browsers.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 02/24/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# How to collect verbose log from browsers
+When an issue originates within the underlying layer, collecting verbose logs in addition to web logs can provide valuable information.
+
+To collect the verbose log from the browser, initiate a web browser session with specific command line arguments. You open your video application within the browser and execute the scenario you're debugging.
+Once the scenario is executed, you can close the browser.
+During log collection, ensure to keep only the necessary tabs open in the browser.
+
+To collect the verbose log of the Edge browser, open a command line window and execute:
+
+`"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --user-data-dir=C:\edge-debug  --enable-logging --v=0 --vmodule=*/webrtc/*=2,*/libjingle/*=2,*media*=4 --no-sandbox`
+
+For Chrome, replace the executable path in the command with `C:\Program Files\Google\Chrome\Application\chrome.exe`.
+
+Don’t omit the `--user-data-dir` argument. This argument is used to specify where the logs are saved.
+
+This command enables verbose logging and saves the log to chrome\_debug.log.
+It's important to have only the necessary pages open in the Edge browser, such as `edge://webrtc-internals` and the application web page.
+Keeping only necessary pages open ensure that logs from different web applications don't mix in the same log file.
+
+Log file is located at: `C:\edge-debug\chrome_debug.log`
+
+The verbose log is flushed each time the browser is opened with the specified command line.
+Therefore, after closing the browser, you should copy the log and check its file size and modification time to confirm that it contains the verbose log.

articles/communication-services/resources/troubleshooting/voice-video-calling/references/how-to-collect-client-logs.md

@@ -0,0 +1,46 @@
+---
+title: References - How to collect client logs
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to collect client logs.
+author: sloanster
+ms.author: micahvivion
+
+services: azure-communication-services
+ms.date: 02/24/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# How to collect client logs
+The client logs can help when we want to get more details while debugging an issue.
+To collect client logs, you can use [@azure/logger](https://www.npmjs.com/package/@azure/logger), which is used by WebJS calling SDK internally.
+
+```typescript
+import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
+setLogLevel('info');
+let logger = createClientLogger('ACS');
+const callClient = new CallClient({ logger });
+// app logging
+logger.info('....');
+
+```
+
+[@azure/logger](https://www.npmjs.com/package/@azure/logger) supports four different log levels:
+
+* verbose
+* info
+* warning
+* error
+
+For debugging purposes, `info` level logging is sufficient in most cases.
+
+In the browser environment, [@azure/logger](https://www.npmjs.com/package/@azure/logger) outputs logs to the console by default.
+You can redirect logs by overriding `AzureLogger.log` method. For more information, see [@azure/logger](/javascript/api/overview/azure/logger-readme).
+
+Your app might keep logs in memory if it has a \'download log file\' feature.
+If that is the case, you have to set a limit on the log size.
+Not setting a limit might cause memory issues on long running calls.
+
+Additionally, if you send logs to a remote service, consider mechanisms such as compression and scheduling.
+If the client has insufficient bandwidth, sending a large amount of log data in a short period of time can affect call quality.

articles/communication-services/resources/troubleshooting/voice-video-calling/references/how-to-collect-diagnostic-audio-recordings.md

@@ -0,0 +1,32 @@
+---
+title: References - How to collect diagnostic audio recordings
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to collect diagnostic audio recordings.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 02/24/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# How to collect diagnostic audio recordings
+To debug some issue, you may need audio recordings, especially when investigating audio quality problems, such as distorted audio and echo issues.
+
+To collect diagnostic audio recordings, open the chrome://webrtc-internals(Chrome) or edge://webrtc-internals(Edge) page.
+
+When you click *Enable diagnostic audio recordings*, the browser prompts a dialog asking for the download file location.
+
+:::image type="content" source="./media/enable-diagnostic-audio-recordings.png" alt-text="Screenshot of diagnostic audio recordings settings.":::
+
+After you finish an ACS call, you should be able to see files saved in the folder you choose.
+
+:::image type="content" source="./media/diagnostic-audio-recordings.png" alt-text="Screenshot of diagnostic audio recording files.":::
+
+`*.output.N.wav` is the audio output sent to the speaker.
+
+`*.input.M.wav` is the audio input captured from the microphone.
+
+`*.aecdump` contains the necessary wav files for debugging audio after processed by the audio processing module in browsers.

articles/communication-services/resources/troubleshooting/voice-video-calling/references/how-to-collect-windows-audio-event-log.md

@@ -0,0 +1,25 @@
+---
+title: References - How to collect Windows audio event log
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to collect Windows audio event log.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 02/24/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# How to collect Windows audio event logs
+The Windows audio event log provides information on the audio device state around the time when the issue we're investigating occurred.
+
+To collect the audio event log:
+* open Windows Event Viewer
+* browse the logs in *Application and Services Logs > Microsoft > Windows > Audio > Operational*
+* you can either
+    * select logs within time range, right click and choose *Save Selected Events*.
+    * right click on Operational, and choose *Save All Events As*.
+
+:::image type="content" source="./media/windows-audio-event-log.png" alt-text="Screenshot of Windows Audio Event Log.":::

articles/communication-services/resources/troubleshooting/voice-video-calling/references/media/diagnostic-audio-recordings.png

@@ -0,0 +1,47 @@
+---
+title: Understanding cameraFreeze UFD - User Facing Diagnostics
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Overview and details reference for understanding cameraFreeze UFD.
+author: sloanster
+ms.author: micahvivion
+
+services: azure-communication-services
+ms.date: 03/27/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# cameraFreeze UFD
+A `cameraFreeze` UFD event with a `true` value occurs when the SDK detects that the input framerate goes down to zero, causing the video output to appear frozen or not changing.
+
+The underlying issue may suggest problems with the user's video camera, or in certain instances, the device may cease sending video frames.
+For example, on certain Android device models, you may see a `cameraFreeze` UFD event when the user locks the screen or puts the browser in the background.
+In this situation, the Android operating system stops sending video frames, and thus on the other end of the call a user may see a `cameraFreeze` UFD event.
+
+| cameraFreeze                          | Details                |
+| --------------------------------------|------------------------|
+| UFD type                              | MediaDiagnostics       |
+| value type                            | DiagnosticFlag         |
+| possible values                       | true, false            |
+
+## Example code to catch a cameraFreeze UFD event
+```typescript
+call.feature(Features.UserFacingDiagnostics).media.on('diagnosticChanged', (diagnosticInfo) => {
+    if (diagnosticInfo.diagnostic === 'cameraFreeze') {
+       if (diagnosticInfo.value === true) {
+           // show a warning message on UI
+       } else {
+           // The cameraFreeze UFD recovered, notify the user
+       }
+    }
+});
+```
+
+## How to mitigate or resolve
+Your calling application should subscribe to events from the User Facing Diagnostics.
+You should also consider displaying a message on your user interface to alert users of potential camera issues.
+The user can try to stop and start the video again, switch to other cameras or switch calling devices to resolve the issue.
+
+## Next steps
+* Learn more about [User Facing Diagnostics feature](../../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web).

articles/communication-services/resources/troubleshooting/voice-video-calling/references/media/enable-diagnostic-audio-recordings.png

@@ -0,0 +1,52 @@
+---
+title: Understanding cameraPermissionDenied UFD - User Facing Diagnostics
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Overview and details reference for understanding cameraPermissionDenied UFD.
+author: sloanster
+ms.author: micahvivion
+
+services: azure-communication-services
+ms.date: 03/27/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# cameraPermissionDenied UFD
+The `cameraPermissionDenied` UFD event with a `true` value occurs when the SDK detects that the camera permission was denied either at browser layer or at Operating System level.
+
+| cameraPermissionDenied                | Details                |
+| --------------------------------------|------------------------|
+| UFD type                              | MediaDiagnostics       |
+| value type                            | DiagnosticFlag         |
+| possible values                       | true, false            |
+
+## Example code to catch a cameraPermissionDenided UFD event
+```typescript
+call.feature(Features.UserFacingDiagnostics).media.on('diagnosticChanged', (diagnosticInfo) => {
+    if (diagnosticInfo.diagnostic === 'cameraPermissionDenied') {
+       if (diagnosticInfo.value === true) {
+           // show a warning message on UI
+       } else {
+           // The cameraPermissionDenied UFD recovered, notify the user
+       }
+    }
+});
+```
+## How to mitigate or resolve
+Your application should invoke `DeviceManager.askDevicePermission` before the call starts to check whether the permission was granted or not.
+If the permission to use the camera is denied, the application should display a message on your user interface.
+Additionally, your application should acquire camera browser permission before listing the available camera devices.
+If there's no permission granted, the application is unable to get the detailed information of the camera devices on the user's system.
+
+The camera permission can also be revoked during a call, so your application should also subscribe to events from the User Facing Diagnostics events to display a message on the user interface.
+Users can then take steps to resolve the issue on their own, such as enabling the browser permission or checking whether they disabled the camera access at OS level.
+
+> [!NOTE]
+> Some browser platforms cache the permission results.
+
+If a user denied the permission at browser layer previously, invoking `askDevicePermission` API doesn't trigger the permission UI prompt, but it can know the permission was denied.
+Your application should show instructions and ask the user to reset or grant the browser camera permission manually.
+
+## Next steps
+* Learn more about [User Facing Diagnostics feature](../../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web).

articles/communication-services/resources/troubleshooting/voice-video-calling/references/media/windows-audio-event-log.png

@@ -0,0 +1,42 @@
+---
+title: Understanding cameraStartFailed UFD - User Facing Diagnostics
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Overview and detailed reference of cameraStartFailed UFD
+author: sloanster
+ms.author: micahvivion
+
+services: azure-communication-services
+ms.date: 03/27/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# cameraStartFailed UFD
+The `cameraStartFailed` UFD event with a `true` value occurs when the SDK is unable to acquire the camera stream because the source is unavailable.
+This error typically happens when the specified video device is being used by another process.
+For example, the user may see this `cameraStartFailed` UFD event when they attempt to join a call with video on a browser such as Chrome while another Edge browser has been using the same camera.
+
+| cameraStartFailed                     | Details                |
+| --------------------------------------|------------------------|
+| UFD type                              | MediaDiagnostics       |
+| value type                            | DiagnosticFlag         |
+| possible values                       | true, false            |
+
+## Example
+```typescript
+call.feature(Features.UserFacingDiagnostics).media.on('diagnosticChanged', (diagnosticInfo) => {
+    if (diagnosticInfo.diagnostic === 'cameraStartFailed') {
+       if (diagnosticInfo.value === true) {
+           // show a warning message on UI
+       } else {
+           // cameraStartFailed UFD recovered, notify the user
+       }
+    }
+});
+```
+## How to mitigate or resolve
+The `cameraStartFailed` UFD event is due to external reasons, so your application should subscribe to events from the User Facing Diagnostics and display a message on the UI to alert users of camera start failures. To resolve this issue, users can check if there are other processes using the same camera and close them if necessary.
+
+## Next steps
+* Learn more about [User Facing Diagnostics feature](../../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web).