Getting historical ECDN usage reports

ECDN historical usage reports

You can retrieve ECDN usage data for any duration in the past one year. You may submit your requests using REST APIs or via the web portal. All requests are handled asynchronously. Submissions are immediately acknowledged. Processing is queued up. When ready, you will get an email notification with a link to download the raw data file for the specified duration. Reports are available in CSV format.

Submit report requests via the web portal

 Click on "REPORTS" in the page header to bring up the "Request report" page.

Steps:

1.  Specify the data range for the duration of interest. You may enter custom values or select a preset from the dropdown. Default is "Today":
   
2. Specify the granularity of aggregating the usage data.
   • For date range duration of <= 24 hours, you may pick either Minute or Hour as the aggregation interval.
   • For date range duration > 24 hours, you can only pick Hour as the aggregation interval.
3. Specify whether you want data to be further aggregated by "Locations" (default), or you want to the data for all ECDN "Servers".
4. Specify "All metrics" (default) or pick specific ones from the dropdown:
   
5. Specify the email address to which the report should be sent when ready.
6. Click the "Request report" button to submit your request.

Your submission will be acknowledged and uniquely identified with a request id.

All report requests are processed asynchronously. When ready, and email will be sent to the specified address, which has a link to download the report. See below for example reports and how to interpret the data.

Submit report requests via REST API

This is a two step process:

1. Get an authentication token and store it in a cookie.
2. Submit request using the cookie for authentication.

This article has examples that use the command line tool curl to make the REST API calls. You may also use any other REST tool of your choice.

Authentication

The API uses session based authentication. To get a valid session, send a POST request to /login API giving your email, and password as input parameters. Note, these are the same credentials you use to login to the ECDN web portal.

$ curl -X POST -d 'email=yourEmailAddress&password=yourPassword' -H "Content-Type: application/x-www-form-urlencoded" https://api.deepcaching.com/login -c cookie.txt

{ "success": true }

Replace yourEmailAddress and yourPassword with your email address and password before making the call.

If successful, you will see {"success":true} response, and the API authentication token will be stored in the file cookie.txt in your local directory.

Submit request

The report request can be submitted by making a POST request to the /reports API as shown below. This call will retrieve all usage metrics for all servers with minute level granularity for the duration between midnight to 4pm GMT on 16 April 2018.

Don't forget to include the cookie file for authentication. Sample response is also shown.

$ curl -X POST -d '{"start": "2018-04-16T00:00:00Z", "end": "2018-04-16T16:00:00Z", "include": [], "outputFormat": "csv", "kind": "servers", "granularity":"minute", "email": "yourEmailAddress"}' https://api.deepcaching.com/reports -b cookie.txt

{ "reportID": "mr-fb34c3d12f9bf475c", "userID": 999, "customerID": 9999, "start": "2018-04-16T00:00:00Z", "end": "2018-04-16T16:00:00Z", "include": [], "kind": "servers", "granularity":"minute", "outputFormat": "csv", "email": "yourEmailAddress", "createdAt": "2018-04-16T19:53:04.365205705Z" }

The input parameters are:

As shown, the response contains the unique reportID assigned to this request.

Download the report

When processing of request is complete, you will receive an email with a link to file that has the usage data in it. You can click the Download report button to get the file.

This link to the report data file will be valid for 7 days. Beyond this time, you will have to submit a new request to get the usage data.

Example usage data in CSV format

The table below represents the usage data for an ECDN account that has one location Budapest, which has two ECDN server instances named server-001.ecdn-demo.ecdn-ustream.com, and server-002.ecdn-demo.ecdn-ustream.com.

Here's a description of what each metric represents:

A report with kind = "servers":

For each server there is one row of data for each minute.

A report with kind = "locations":

For each location there is one row of data for each minute.

Interpreting the data

How many viewers watched a broadcast via the ECDNs?

In the servers report take the maximum value of playingCount column for each server, and add them up.

In the locations report, take the maximum value of playingCount column for each location, and add them up.

Note: This sum is an approximation, as the peak viewership as seen in the server/locations data may not have happened at the same exact time.

How many viewers experienced buffering during the broadcast?

Similar to the previous calculation, in the servers report, take the maximum value of the bufferingCount column for each server, and add them up.

In the locations report, take the maximum value of the bufferingCount column for each location, and add them up.

Note: A sustained high value (> 5% of viewership) of bufferingCount usually warrants an investigation. It is not unusual for each site to report some buffering during a broadcast.

On buffering, the IBM Video Streaming player is designed to auto-switch to a lower resolution (bitrate) to provide the best viewing experience. The player can also auto-switch to a higher resolution video, if it detects a higher quality stream is available, and the WAN network has sufficient available bandwidth capacity to deliver this higher bitrate stream.

Viewers from how many locations experienced buffing during the broadcast?

In the locations report, identify all locations with non-zero values in the bufferingCount column. sort | uniq the data to remove duplicates.

Similarly, in the servers report, identify all servers with non-zero values in the bufferingCount column, and then sort | uniq the results. Next further process to eliminate the duplicate locationName values to get the answer.

How much WAN bandwidth was saved by using ECDNs?

Total the savedBw column values in either of the locations or servers report. The sum, in bytes, is the amount of network traffic over the WAN that was avoided by using ECDNs in distributing the video stream data to all the viewers.