# Troubleshooting and debugging Amazon Chime SDK meetings Use the following topics to help diagnose and troubleshoot issues that you encounter when working with the Amazon Chime SDK. **Topics** + [ # Understanding the system requirements for Amazon Chime SDK meetings ](ts-supported-browsers.md) + [ # Setting up logging and monitoring for Amazon Chime SDK meetings ](ts-log-monitor.md) + [ # Troubleshooting Amazon Chime SDK meetings ](self-troubleshooting.md) + [ # Understanding common issues with Amazon Chime SDK meetings ](common-issues.md) # Understanding the system requirements for Amazon Chime SDK meetings Understanding the system requirements As part of troubleshooting, make sure you code for supported browsers. For a current list of supported browsers, versions, and operating systems, see [Amazon Chime SDK system requirements](meetings-sdk.md#mtg-browsers). The [developer guide and FAQs on Github](https://github.com/aws/amazon-chime-sdk-js/issues/1059) address browser and other compatibility issues. Also, familiarize yourself with the [known browser issues](https://aws.github.io/amazon-chime-sdk-js/modules/faqs.html#known-browser-issues) on GitHub and any workarounds. If you just started with Amazon Chime SDK Meetings, the [Amazon Chime SDK’s Builder Journey](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/20_Builders_Journey.md) provides a step-by-step guide for building with the Amazon Chime SDK, plus the tools needed for troubleshooting. # Setting up logging and monitoring for Amazon Chime SDK meetings Setting up logging and monitoring Logging helps you collect information such as server-side meeting events and client-side browser console logs. The Amazon Chime SDK provides server-side meeting events that you can send to Amazon EventBridge and Amazon CloudWatch Events logs. You can create CloudWatch metrics and insights, and use them in your dashboard for monitoring. The [Server-side Logging and Monitoring of Amazon Chime SDK events](https://aws.amazon.com/blogs/business-productivity/server-side-logging-and-monitoring-of-amazon-chime-sdk-events/) blog post explains how to enable the CloudWatch Metrics, Insights and Dashboard. The Amazon Chime SDK provides client-side events for audio and video quality, network bandwidth, and connectivity issues. The [Monitoring and troubleshooting with Amazon Chime SDK Meeting events](https://aws.amazon.com/blogs/business-productivity/monitoring-and-troubleshooting-with-amazon-chime-sdk-meeting-events/) blog post explains how to enable CloudWatch Metrics, Insights and Dashboard for join failures, audio quality issues, and microphone and camera setup failures. For additional information about meeting events, see [Meeting Events](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/06_Meeting_Events.md) on Github. ## Options for troubleshooting metrics You have the following options for collecting troubleshooting events. + Send metrics at every event + Batch events every N seconds + Send metrics at end of the meeting + Logging level for browser console logs ## Recommended metrics At a minimum, you should collect and log the following metrics. + SDK platform and version + Browser and version + Operating system + Logical cores + Meeting started + Meeting ended + Attendee joined + Attendee left + Attendees dropped Additionally, depending on the issues you face, the following metrics can provide information about connectivity, bandwidth, and quality issues. You can log every occurrence of these metrics, or just count them. Counting can provide a summarized view of the underlying issues: + connectionDidSuggestStopVideo + connectionDidBecomeGood + connectionDidBecomePoor + Attendee join time > t seconds + MeetingStartFailed + MeetingFailed ## Enabling client-side logging You can enable `INFO`-level browser logs by passing `LogLevel.INFO` to the `ConsoleLogger` object. ``` const logger = new ConsoleLogger('MyLogger', LogLevel.INFO);const meetingSession = new DefaultMeetingSession(configuration,logger,deviceController); ``` You can also use the `POSTLogger` component in the Amazon Chime SDK for JavaScript to capture browser logs in your back end, such as Amazon CloudWatch Logs. `POSTLogger` makes `HTTP POST` requests to upload browser logs to the given URL in the [POSTLogger constructor](https://aws.github.io/amazon-chime-sdk-js/classes/postlogger.html). For example, the [Amazon Chime SDK serverless demo on GitHub](https://github.com/aws/amazon-chime-sdk-js/blob/main/demos/browser/app/meetingV2/meetingV2.ts#L1773) uses the `POSTLogger` to send browser logs to Amazon CloudWatch Logs for future investigation. ## Enabling server-side logging The Amazon Chime SDK for JavaScript also calls the `eventDidReceive` observer method with key meeting events, such as `MeetingStartFailed` and `MeetingFailed`. Meeting events often includes specific reasons for failures. For example, say that a large group of customers experience failures. Your web application can collect those meeting events, and then share them with us to troubleshoot the root cause. For more information about meeting events, see the [meeting event guide on GitHub](https://aws.github.io/amazon-chime-sdk-js/modules/meetingevents.html), and the [ Monitoring and troubleshooting with Amazon Chime SDK meeting events](https://aws.amazon.com/blogs/business-productivity/monitoring-and-troubleshooting-with-amazon-chime-sdk-meeting-events/) blog post. # Troubleshooting Amazon Chime SDK meetings Troubleshooting Amazon Chime SDK meetings The sections in this topic explain several ways to self-troubleshoot Amazon Chime SDK meetings. **Topics** + [ ## Checking FAQs and known issues ](#check-faqs) + [ ## Verifying network access ](#net-acess) ## Checking FAQs and known issues Check these FAQs and lists of known issues on GitHub for troubleshooting and debugging advice. + [Amazon Chime SDK – JavaScript - Meetings](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#meetings) + [Amazon Chime SDK – JavaScript - Media](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#media) + [Amazon Chime SDK – JavaScript - Networking](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#networking) + [Amazon Chime SDK – - Audio and Video](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#audio-and-video) ## Verifying network access Enterprises often have network firewalls that restrict access to specific ports, or connections to IP address ranges out of their network. The following sections explain some of the ways you can verify network access. **Topics** + [ ### Validating AWS SDK and Amazon Chime SDK subnets and ports ](#subnets-ports) + [ ### Using demo apps to reproduce issues ](#repro-on-demo-apps) + [ ### Using the Meeting Readiness Checker ](#ready-checker) ### Validating AWS SDK and Amazon Chime SDK subnets and ports Applications that use the Amazon Chime SDK utilize two tiers, server and client. The server tier uses the AWS SDK and has server-side meeting handlers. The client tier uses client SDKs. The AWS SDK is used to call server APIs such as [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html). Such APIs connect to the AWS global service endpoints in the `us-east-1`, `us-west-2`, `ap-southeast-1`, `eu-central-1`, `us-gov-east-1`, and `us-gov-west-1` Regions. The [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) page in the *AWS General Reference* lists the IP address ranges for each Region. For information about service endpoints and quotas, see the [Amazon Chime SDK endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html). Client SDKs, such as the Amazon Chime SDK for JavaScript, connect to service endpoints in the `*.chime.aws` domain. Use the following validations to ensure that you have network permissions: + Run the [Amazon Chime SDK Meeting Readiness Checker](https://github.com/aws/amazon-chime-sdk-js#meeting-readiness-checker) on GitHub to verify that you can reach your network and ports. + Verify you can resolve \$1.chime.aws domain from your network or your end user’s network. + Ensure that your firewall allows connections to the AWS IP range via TCP Port 443 for control commands and UDP Port 3478 for media. ### Using demo apps to reproduce issues As a best practice, start the debugging process by trying to reproduce your issue in one of demo apps. That enables the service team to locate where the issue might be. If you can't reproduce the issue with a demo app, you can review the app's code to see how it implemented the relevant use case. | Amazon Chime SDK | Feature | Demo app resources | | --- | --- | --- | | JavaScript SDK | Meetings | [Demo instructions](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/serverless), [Source code](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/browser) | | React components | Meetings | [Demo instructions](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/meeting) [Source code](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/meeting/src) | | Meeting chat | Messaging | [Blog post](https://aws.amazon.com/blogs/business-productivity/build-meeting-features-into-your-amazon-chime-sdk-messaging-application/), [Demo instructions](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat), [Source code](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat/src) | | iOS/Android | Meetings | (Blog post) [ Building a Meeting Application on Android using the Amazon Chime SDK](https://aws.amazon.com/blogs/business-productivity//building-a-meeting-application-on-android-using-the-amazon-chime-sdk/) (Blog post) [ Building a Meeting Application on iOS using the Amazon Chime SDK](https://aws.amazon.com/blogs/business-productivity/building-a-meeting-application-on-ios-using-the-amazon-chime-sdk/) | | PSTN audio | Inbound calling | [Blog post](https://github.com/aws-samples/amazon-chime-sma-update-call) [Source code](https://github.com/aws-samples/amazon-chime-sma-update-call) | ### Using the Meeting Readiness Checker Use the [Amazon Chime SDK Meeting Readiness Checker](https://github.com/aws/amazon-chime-sdk-js#meeting-readiness-checker) on GitHub. The checker helps verify audio and video devices, and user connections. You can present the results to your end users with by using pass/fail statues that expose the root cause of any issues. # Understanding common issues with Amazon Chime SDK meetings Understanding common issues The following sections provide troubleshooting methods for common meeting issues. **Topics** + [ ## Connectivity issues ](#connectivity-issues) + [ ## Audio and video quality issues ](#a-v-quality) + [ # Verifying SDK quotas and API throttling for Amazon Chime SDK meetings ](quotas-throttling.md) + [ # Opening support cases for Amazon Chime SDK meetings ](open-support-cases.md) ## Connectivity issues Connectivity issues For connectivity issues, see [Verifying network access](self-troubleshooting.md#net-acess). ## Audio and video quality issues Audio and video quality issues Audio and video quality issues can have several causes. Two main reasons for sub optimal audio/video quality are network bandwidth, and device performance. For detailed information on different challenges and how these impact audio/video quality, see [Quality, Bandwidth, and Connectivity](https://aws.github.io/amazon-chime-sdk-js/modules/qualitybandwidth_connectivity.html) on *GitHub*. This article describes different events and metrics that can be monitored to detect bandwidth issues and potential mitigations. You can choose a Media Region that is closer to the audience of the target meeting session. To understand how to choose an optimal media region, see Using meeting Regions (https://docs.aws.amazon.com/chime-sdk/latest/dg/chime-sdk-meetings-regions.html). Depending on the bandwidth available for a meeting attendee, the Amazon Chime SDK adjusts the video quality of the video being received/uploaded. To understand how you can control the video quality for different video layouts, visit Managing Video Quality for different Video Layouts (https://aws.github.io/amazon-chime-sdk-js/modules/videolayout.html). This article describes video lifecycle management and uplink/downlink policies. **Video resolution considerations** + Default resolution for uploading video is 540p and 15fps at 1400 kbps. Depending on bandwidth, you can reduce that resolution and frame rate. + Based on receiver bandwidth available, determine how many video tiles to show. Don’t overshoot 6Mbps for all video tiles and content sharing. End users see black video tiles when they don't have enough bandwidth. **Using video uplink and downlink bandwidth policies** The Amazon Chime SDK provides the following bandwidth policies. + NScaleVideoUplinkBandwidthPolicy – Implements capture and encoding parameters that nearly equal those used by the desktop, web, and mobile clients. + AllHighestVideoBandwidthPolicy – Always subscribes to the highest quality video stream. + NoVideoDownlinkBandwidthPolicy – Disables video when bandwidth drops below a given threshold. + VideoPriorityBasedPolicy – Prioritizes audio over video in cases of low bandwidth. + VideoAdaptiveProbePolicy # Verifying SDK quotas and API throttling for Amazon Chime SDK meetings Verifying SDK quotas and API throttling The [Amazon Chime SDK endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html) page lists the service quotas, API rates, and whether you can adjust them. Use the [AWS Console Service Quota](https://console.aws.amazon.com/servicequotas/home/services/chime/quotas) page to request quota adjustments. **Fine tuning your API rates** Applications that exceed their API rates receive HTTP Status Code 429 and `ThrottledClientException` messages. You can adjust your API rates, but before you do, check your application for bugs that may exhaust those rates. For example, you may create meetings in a loop, or create meetings and not clean up. Depending on how you create meetings, you might need to modify your code. For example, you can replace `CreateMeeting` and `CreateAttendee` with: + [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html) – Creates up to 10 attendees per meeting. + [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html) – Creates up to 100 attendees per meeting. You can store created attendees in a database, pull attendee information as invitees join the meeting, and then associate them with the pre-created attendees. # Opening support cases for Amazon Chime SDK meetings Opening support cases If you have more questions, or require support for your business, you can reach out to [AWS Customer support](https://pages.awscloud.com/GLOBAL-aware-GC-Amazon-Chime-SDK-2020-reg.html). For more information about our support plans, see the [Compare support plans](https://aws.amazon.com/premiumsupport/plans/?nc=sn) page. When creating a support case, always open it under the account that has the problem. Include console browser logs, meeting and attendee IDs, and any related support cases or GitHub issues.