HLS Analyzer Monitoring Overview
HLSAnalyzer.com is an online HLS analyzer and monitoring service. Streams are individually added to the monitoring system (Master or Media playlists), after which they can be configured for monitoring and alerting. Alerts can be delivered via email, or HTTP callback POSTs. HLSAnalyzer.com generates both stream delivery outages alerts as well as ad-insertion (SCTE-35) cue stoppage alerts. The monitoring engine downloads every segment and playlist, and logs the primary characteristics of the stream delivery process for subsequent evaluation and processing. Summary reports for SCTE-35 cues as measured by the system, as well as an overview of all alert events can be downloaded for up to 90 days.
There are two primary ways of interacting with our system: a browser-based UI interface that allows access to most features of the analyzer, as well as an HTTP REST-based API that facilitates integration with automated pipelines. For examples on integrating our APIs with real-world applications, refer to our sample code available on Github.
The HLSAnalyzer.com browser-based UI can be used to add and remove streams, check the current API status, add files from a .csv file, and configure alert parameters. The interface utilizes the same API calls that are documented in the next section, ensuring a consistent experience while interacting with the HLS Analyzer monitoring server. The browser can also be used to monitor the state of all links associated with an API key in real-time.
For the best experience, the use of Google Chrome, Firefox, or Microsoft Edge is recommended.
Description: All streams associated with the particular API key will be available for inspection, via an interface similar to the following:
All of the important parameters of the API can be monitored, including the current alert configuration state.
HLS streams can be added and removed from this interface. LinkIDs may be supplied for each stream, to make their identification easier. When not supplied, LinkIDs will automatically be assigned by the server when adding streams. Stream outage alerts as well as SCTE-35 outage alerts (disabled by default) may be individually enabled or disabled for each stream.
Global alert parameters can be configured via this panel. The outage and clear settings apply globally to all streams, with delivery stream outages being specified in units of seconds and SCTE-35 outages in units of minutes. Alerts may be globally enabled or disabled from this panel as well. One or both alert types (email and HTTP Post callback) can be filled or left blank.
Batch processing functions perform functions that involve a large set of streams:
http://www.example.com/playlist.m3u8, mylinkID2, 0, 1
http://www.example.com/playlist3.m3u8, mylinkID3, 1
There are two types of logs: summary logs and detailed logs. Summary logs can be selected for up to 7 days, while detailed logs up to 24 hours. The following logging functions can be performed by the system:
Logs will be available for up to 30 days in the past.
The monitoring service supports two types of outage alerts: stream delivery outages, and SCTE-35 cue outages. SCTE-35 alerts are disabled by default and must be enabled via the browser-based UI or the REST-APIs. Global alerts must be enabled before either stream outage alerts or SCTE-35 cue outage alerts are monitored.
When playlists or segments are not delivered on time, then alerts may be received according to configuration parameters. Media playlists may be in any of the following states:
Media Playlist State
Playlist does not have an ENDLIST and is progressing by adding new segments.
New segments are not added to the playlist (stale playlist).
The playlist cannot be downloaded due to HTTP errors.
The steam was in Live state, but has transitioned to ENDLIST. When in this state, no segment monitoring will be performed until the playlist returns to Live state again.
The stream was never in Live state and has an ENDLIST.
The starting state of the stream, which will transition to any of the states described above.
When either media playlist or segments arrive at a slower rate than the expected time duration, the playlist buffer will be depleted and eventually reach zero, which would indicate a rebuffering event at the player. There are 3 sensitivity modes for alerting, starting with most sensitive to the least:
A stream must be in outage condition for a minimum amount of time before an alert is generated. After the alert condition has been resolved, the clear condition must continue for a minimum amount of time before the clear condition is recognized by the system. This is shown in the next diagram:
The sensitivity setting only applies to media playlist outages. Alerts for SCTE-35 outages and master playlists utilize a binary condition: whether the asset is present or not. In case of SCTE-35, alerts are raised when cues are not observed for the API-specified duration. We recommend customers evaluate the alert sensitivity settings before determining a level suitable for their system. Alerts may be programmed to report the inconsistent delivery times, as well as when those conditions have been cleared. Alert email messages will generally have the following format:
Subject: OUTAGE: HLSAnalyzer Outage Alert for 5fa1ab24559c
This is an alert update from HLSAnalyzer.com for:
[5fa1ab24559c] Outage Time (UTC): 1610541723.00, Alert Condition Duration: 125.00 (sec), Total Accumulated Stream Outage: 128.3 (sec), Status: Stalled , Variant: https://example.com/example.m3u8
[5fa1ab24559c] This stream experienced inconsistent delivery for 125.00 seconds.
Subject: OK: HLSAnalyzer Clear Alert for 5fa1ab24559c
This is an alert update from HLSAnalyzer.com for:
[5fa1ab24559c] Outage Time (UTC): 1610542123.00, Alert Condition Duration: 305.00 (sec), Total Accumulated Stream Outage: 386.0 (sec), Status: Live , Variant: https://example.com/example.m3u8
[5fa1ab24559c] This stream's alert condition has been cleared after a consistent delivery period of 305.00 seconds.
The HLSAnalyzer.com service is a fully managed and monitored solution that provides high service availability for our customers. The health of our system is monitored by:
Our list of internal monitoring tools is always expanding to ensure that our service remains up and available and continuously monitors our clients’ HLS streams.
General Error or Warning
Link quota limit reached
Invalid API Key
This feature requires a paid subscription
API Key has expired
Error condition with a specific text message
Warning condition with a specific text message
Invalid or missing LinkID
Invalid alert limit value specified
Invalid alert setup value specified
Media playlist has become a master playlist
A URI previously associated with a media playlist has become a master playlist. This is generally an unexpected condition.
An unusually large jump in media playlist progression
Media sequence numbers are expected to increase by 1, per RFC 8216 Section 6.2.2.
Media sequence wraparound
According to RFC 8216 Section 6.2.2, media sequence numbers MUST not wrap.
Negatively increasing media sequence
According to RFC 8216 Section 6.2.2, media sequence numbers MUST not decrease.
Extra player buffer accumulation
This error indicates the arrival of new segments faster than in real-time. This condition may eventually lead to skipped segment playback.
Negative segment duration
Segment duration must always be greater than zero.
Segment duration is greater than the target duration
Segment duration is greater than the target duration by more than 150%.
An unusually large segment duration
Any segment duration greater than 120 seconds is considered to be an error condition.
Invalid target or segment duration
The server could not decipher the segment or target duration in the playlist.
Bandwidth parameter not specified for media Playlist
According to RFC 8216 Section 18.104.22.168: “ Every EXT-X-STREAM-INF tag MUST include the BANDWIDTH attribute.”
The ratio of measured Peak Bitrate exceeds the specified bitrate
The measured peak bitrate must be less than the specified bitrate from the Master playlist
Could not download the segment
The segment specified by the media playlist could not be downloaded
Playlist and stream mismatch
The parameter specified in the Master playlist does not match the stream’s characteristic
Could not download the playlist
An HTTP error is reported by the operating system when trying to read the link
Additional HLS conformance errors
A specific error was encountered; refer to the error message for details
Some operations, such as downloading high-bitrate streams, require a subscription
A rebuffering event was experienced by the monitoring server, due to the slow arrival of media playlist segments.
Slow segment download time
Downloading of the segment took longer than the specified segment duration.
Media sequence number increment mismatch
Media sequence number differences do not match the expected segment counts in a live playlist.
Master playlist feature not supported
Media playlists that change resolution or are added or removed are not yet supported.
Copyright © 2022 Task One, LLC. All Rights Reserved.