A post-call diagnostic tool for your Video API sessionsUse Inspector
This page includes the following sections:
Note: Please click here for information on data retention and latency.
Inspector is a tool to help understand what happened in specific OpenTok sessions. Users can either enter a session ID or use the Session Dashboard to access the following information about a session:
Inspector is primarily used for debugging problematic sessions that have occured in your OpenTok application. You must be logged into your TokBox account to access Inspector, and you can only view sessions created from API Keys associated with your account.
Before diving into the detailed info about a session, you first need to find the session. The best way to do this is to log the session ID of each session created in your app for easy debugging. However, if you do not know the ID of the session, you can use the Session Dashboard to view recently active sessions as well as recently inspected sessions.
After selecting or searching for a unique session, you’ll be taken to the session view of Inspector, where you’ll be able to view data about that session. The session view is broken out into various sections, which are outlined below:
At the top of the view are the Summary and Statistics sections. These sections provide a high-level overview of what happened in a session. This data can be helpful for developing a quick understanding of the session topology, length, and diversity. It’s also helpful for verifying that you’re looking at the correct session when debugging.
In some cases, you may want to drill down to specific meetings within a larger session — to do this, simply click the Meeting Selector in the top right corner and select the meeting segment you’re interested in viewing. In cases where a session includes many distinct meetings, this can help simplify the view for easier debugging.
When debugging a problematic session, it’s usually helpful to understand “who is who” in Inspector. For example, one of the session participants may have experienced connectivity issues, so you would want to view data about that specific user in Inspector to better understand why the issue may have occurred. To help with this identification, the User Data module provides some high level information about each user, including their location, device, SDK, and the number of errors they experienced.
You can also click on a user to reveal more information about that user, including details about their connections and streams they published. This view is especially helpful for understanding who successfully subscribed to any given stream, which you can see in the right-most column of the stream list.
For more about how clients connect, publish, and subscribe, see Video API Basics.
If any errors occured in the session, they will display in the Error Log section. This section also displays the failure rate for connection, publish, and subscribe attempts in the session or meeting. This rate is calculated by dividing the number of failures by the total number of attempts.
The Quality Metrics module is useful for understanding bitrate, packet loss, and latency over time for each user. While these statistics can not directly determine subjective quality experienced by your app’s users, they can help to understand what may have contributed to poor quality. You can find a brief explanation of each of these concepts below:
Bitrate — this represents the amount of bits (data) being sent over the user’s connection. The Quality Metrics chart includes both audio and video bitrate — you can mouse over any point on a plotted line to see each value at any given time. While the bitrate can’t be directly linked to quality, very low bitrates (less than 150kbps for video and less than 25kbps for audio) can generally be associated with poor quality. To get a better understanding of what quality to expect based on these bitrate, see our Help Center article.
Packet Loss — in a video call, data is sent in units called packets. In many situations, some of these packets are lost in transit, meaning they are not received by the user endpoint. Packet loss is calculated as a percentage of packets lost out of packets sent. For example, if 100 packets are sent and only 99 are received, there is a 1% packet loss. A small amount of packet loss is expected in a video call without causing quality issues, but if it exceeds 3-5% there is a good chance that quality may suffer.
Latency — this represents the amount of time it takes for a packet of data to get from one endpoint to another. Any latency higher than 300ms is likely to have a negative effect on quality.
You can click and drag on the chart to zoom in on a specific section of the graph. You can also filter which data displays based on the checkboxes above the graph and the Inspector sidebar filters.
Note: For a stream that does not use scalable video (such as a stream in a relayed session), the publisher adapts the published video to accommodate the subscriber with the worst network conditions. Inspector will show quality information based on this worst-performing subscriber. So the reported publisher video quality might not reflect the actual video quality experienced by all subscribers to the stream.
For a stream that uses scalable video, Inspector shows video quality information based on the link between the stream's publisher and the OpenTok Media Router.
Publisher audio quality always reflects what the worst subscriber reports. This means that the reported publisher audio quality might not reflect the actual audio quality experienced by all subscribers to the stream.
Please see this article for more information on scalable video.
The Event Log lists events related to connecting, publishing, and subscribing that occured in the session or meeting you’re inspecting. This is helpful for understanding the context of connect, publish, or subscribe failures, and can also be useful for quickly seeing why users disconnect, unpublish, or unsubscribe.
You can filter events using the text filter in the top left in two ways:
You can also filter by user with the Inspector sidebar filters.
All OpenTok interactions occur within a session (for more on this, see Video API Basics) — you can think of a session as a “room”. Sessions are created using the OpenTok Server SDKs or REST API, and every session is associated with a session ID.
Although we recommend generating a new session for every “meeting” between participants — for example, if a team joins together for a group conference — but sometimes session IDs are reused across multiple “meetings.” This reuse of sessions can cause problems when debugging a session in Inspector, as its difficult to pinpoint a user or problem when viewing multiple meetings at once.
To make it easier to debug these types of sessions, Inspector automatically breaks down sessions into multiple meetings. When all participants disconnect from a session, a meeting is considered “ended”, and if new (or the same) participants join the session at a later time, a new meeting is created and displayed in Inspector.
By default, Inspector shows all meetings when a new session is loaded. In order to drill down to a specific meeting, use the meeting dropdown in the top right-hand corner of Inspector.
Connections and streams are part of the core functionality of OpenTok. This section will outline how these objects (along with the “user” object) are referenced in Inspector, but if you would like a more comprehensive overview of these concepts, see Video API Basics.
In order to participate in an OpenTok session, a connection must be made between a client and the OpenTok platform (except in a relayed session, where clients connect directly). This connection is associated with a unique connection ID. The connection ID is important when debugging a session in Inspector, as any stream published to the session is associated with the connection that it was published from. For more about how clients connect, publish, and subscribe, see Video API Basics.
In order to more easily correlate connections with actual end-users in a session, Inspector also includes a user object. The user is associated with a unique client endpoint — for example, an end-user’s browser or mobile device — tracked via cookies. While an end-user can have multiple connections (if they disconnect and reconnect multiple times), they will always be associated with only one user in Inspector.
The user object in Inspector includes a few properties for more easily identifying who is who:
This is especially helpful when trying to debug that affected only a specific user. After identifying the user in Inspector based on location/device, you can then examine connections and streams for that user to identify quality or connectivity problems.
It’s important to note that a user can have multiple connections, but a connection cannot have multiple users. You can view user info as well as their associated connections and streams in the User Data section of Inspector.
Once connected to a session, a user can publish a stream and subscribe to other streams published in the session. Each stream is associated with a Stream ID, which can be used in Inspector to see who in a session successfully published and subscribed to a stream. Inspector provides a variety of information about streams:
If a session includes more than 100 subscribers, the type of information displayed in Inspector will change, including the addition of two modules, outlined below:
This section provides a visual timeline of the connection attempts, successes, and failures in the session.
This section provides a visual timeline of the subscribe attempts, successes, and failures in the session.
It's also important to note that subscribers are not viewable in the Quality Metrics section for large sessions. This was implemented to improve load time for large sessions — if Inspector attempted to load quality visualizations for 100+ subscribers, the tool would take up to an hour or more to load all of the data, significantly affecting usability.
Data retention: 20 days
Note:The retention period is based on the created-at time of a meeting within the session. Meetings can only be queried within a 7-day period within the session. It is best practice to create a new session ID for each distinct video chat in your application.
Expected Latency: 5 minutes
Note: A single session may have multiple meetings. A new meeting is set when the session is out of use for 10 minutes. Please refer to the section on Sessions vs. Meetings for more information.