Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalA post-call diagnostic tool for your Video API sessions
Use InspectorThis 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 Vonage Video API 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.
At the top of Inspector, select the time zone you want to display session data in. The time zone selector is labeled "Time shown in," on the right side of the Inspector banner at the top of the page.
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.
The Meetings Statistics panel includes the following information:
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 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.
Click the See more details link at the right of the listing to view more information about the user's streams and connections. For each connection, this includes the following:
For each stream, the additional details include the following:
The Users table displays a unique GUID (globally unique identifier) for each user. This GUID is reused to identify the same user in multiple connections to a session. For example, if a user of the web client SDK reconnects to a session in multiple browser sessions, Inspector lists the separate connections under the same user listing in the Users table. Use the connection ID to identify the client's connection to the session. (You can use the client SDKs to obtain the connection ID for a user.)
SIP clients are indentified as "SIP" in the table (for example, "SIP1" and "SIP2"). Click the expand arrow ( > ) to the left of the listed SIP client to see additional details. And click the See more details link to see the SIP call ID, conference ID, SIP URI, and more.
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:
Note: The Quality Metrics module shows data for non-SIP clients only. To view quality data for SIP clients, see SIP Interconnect Quality Metrics.
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, along with the combined bitrate. Mouse over any point on a plotted line to see these bitrates at any given time, along with the video codec, resolution, and frame rate (for a stream that includes video). 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 filter which data displays based on the checkboxes above the graph: Show Video, Show Audio, Publishers, and Subscribers. You can also filter by users using the Filter options in the left-hand side of the page.
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 SIP Interconnect Quality Metrics module provides bitrate, packet loss, latency, and MOS (Mean Opinion Score) data over time for each SIP client in the session. The quality metrics are from the SIP call, not the webRTC stream.
Inspector only shows the SIP Interconnect Quality Metrics module for sessions that include SIP clients.
In each graph, you can mouse over any point on a plotted line to see each value at any given time. The ConnectionID shown corresponds to the connection ID of the SIP client in the Vonage Video API session. This connection ID is returned in the REST API call to initate a SIP connection in the Video API session (or in the corresponding calls in the Vonage Video API server SDKs).
Bitrate — This represents the amount of bits (data) being sent and received from the Vonage Video API SIP gateway. You can toggle between audio and video bitrate. While the bitrate can’t be directly linked to quality, very low bitrates can generally be associated with poor quality.
Packet Loss — SIP data is sent in units called packets. This graph shows packet loss (as a percentage) for each SIP connection in the session. The packet loss shown is for sent and received data from the Vonage Video API SIP gateway.
Latency — This represents the latency for SIP data sent and received from the Vonage Video API SIP gateway. Any latency higher than 300ms is likely to have a negative effect on quality.
MOS — The Mean Opinion Score (MOS) is an objective measure of the overall call quality experienced by the user. The scale ranges from 1, representing bad call quality, to 5, meaning excellent call quality. Generally MOS scores will range from 3-4.5 for acceptable quality. This number can depend on a few factors, including the codec that is used in the call.
You can click and drag on the chart to zoom in on a specific section of the graph. You can filter which data displays based on the checkboxes above the graph: Show Video and Show audio. You can also filter by SIP users using the Filter options in the left-hand side of the page.
The Broadcast Information module provides information on broadcasts in the session. If there are multiple broadcasts, select the ID for the broadcast you are interested in, in the right-hand side of the Broadcast Information header. Click the arrow ( > ) on the left-hand side of the header to view the information, including the resolution of the broadcast, the type of broadcast (HLS and/or RTMP), the duration of the broadcast, and the total number of bytes served.
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.
You can view connection IDs and their associated streams in the User Data section of Inspector. You can also view the quality of each connection in the Quality Metrics section of Inspector.
Important — known issue: With the introduction of adaptive media routing,
Inspector erroneously displays clientDisconnection events for the first two users in a routed session, when they transition
from peer-to-peer streaming to use of the OpenTok Media Router.
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:
Connection Summary
This section provides a visual timeline of the connection attempts, successes, and failures in the session.
Subscriber Summary
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.
By default, you can inspect sessions for up to 20 days from the end of a session (see Data Retention and Latency). Within this 20-day retention period, you can save a session and continue to inspect the session for up to 24 months.
To save a session, view the session in Inspector and click the (Save) button in the header of the page. Provide a name for the saved session (required) and provide up to three custom tags (optional).
Note: We recommend using the session name field as a descriptive way to differentiate between your sessions. Use tags to keep track of specific characteristics about sessions. These characteristics could include errors, distinctive network characteristics, and quality attributes experienced during this session.
To view a saved session, go to the Session Dashboard and click the Saved Sessions tab.
You can save up to 1,000 sessions for an account.
To edit the name or tag for a session, view the session in Inspector and click the (Edit) button in the header of the page.
If a session is saved and still within Inspector’s 20 day retention period, you can overwrite the previously saved session data with updated information by viewing the Inspector page for that session and clicking the (Save) button in the header of the page.
To delete a session from the saved sessions list:
Note: Saved sessions are stored for up to 24 months and Vonage reserves the right to delete any saved sessions older than 24 months.
Known issue: Sessions saved between December 5, 2022 to March 2, 2023 were not retained (and cannot be inspected). We have fixed this bug.
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.
You can save a session to view its data after the 20-day data retention period. See Saving Sessions.The following updates are added to Inspector:
The following updates are added to Inspector:
The following updates are added to Inspector:
