ECDN historical usage reports

You can retrieve ECDN usage data for any duration in the past two years. You may submit your requests using REST APIs or via the web portal (to come later). 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. Two formats are supported: JSON (coming soon) or CSV.

Submit usage data 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.

For the ECDN beta environment use the API endpoint: https://beta-api.deepcaching.com/login

Submit request

The report request can be submitted by making a POST request to the /reports API as shown below. Don't forget to include the cookie file for authentication. Sample response is also shown.

$ curl -X POST -d '{"start": "2018-03-23T15:00:00Z", "end": "2018-03-23T16:00:00Z", "include": [], "outputFormat": "csv", "kind": "servers", "email": "yourEmailAddress"}' https://api.deepcaching.com/reports -b cookie.txt
{ "reportID": "mr-fb34c3d12f9bf475c", "userID": 67, "customerID": 99, "start": "2018-03-23T15:00:00Z", "end": "2018-03-23T15:30:00Z", "include": [], "kind": "servers", "outputFormat": "csv", "email": "yourEmailAddress", "downloadURL": "", "completed": false, "createdAt": "2018-03-23T15:53:04.365205705Z", "completedAt": null, "successful": null }

The input parameters are:

Parameter name Description
start Start date and time in RFC3339 format. This represents the start time of the usage data interval that you are interested in.
end End date and time in RFC3339 format. This represents the end time of the usage data interval that you are interested in.
include This represents the list of metrics that you are interested in. If empty [], then response will include all metrics. The valid values are: buffering, playing, savedBw, rx, tx. To retrieve select metrics, specify a list such as ["rx", "tx", "savedBw"]. See the example below for a description of each of these metrics.
outputFormat Format in which the raw data will be returned. Use "csv" for CSV format, and use "json" for JSON format.
kind This specifies whether you want usage data aggregated for every location, or for each individual ECDN server. Valid values are: locations, and servers.
email This is the email address where the completion email will be sent after this request is processed. The email will contain the URL to download the file with the usage data.

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:

timestamp Time of the measurement in UTC.
hostname Hostname of the server.
hostId Host identifier.
locationName Name of the server's location as seen in the ECDN web portal.
locationId Location identifier
playing Number of viewers connected to this server. It represents the concurrency in this time interval ie the number of connections to a specific server, or in case of the locations report it the aggregation of number of connections across all servers configured in that location. Note: ECDN servers cannot identify which employee watched the video stream by connecting to it. It only knows the IP address of machine that connected to it.
buffering Number of viewers experiencing buffering.
rx Received bytes per minute. This represents the WAN traffic.
tx Transferred bytes per minute. This represents the LAN traffic.
savedBw This is the difference: tx - rx in bytes. A positive value, seen during playback, represents that a video chunk was downloaded once over the WAN, and then distributed to all the viewers over the LAN, thereby saving WAN bandwidth. A negative value usually seen when the ECDN servers are idle, and represents the network traffic due to ECDN servers uploading their metrics and health heartbeats. An aggregate of all these values gives a measure of the amount of WAN bandwidth saved by deploying ECDN servers.

A report with kind = "servers":

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

timestamp hostname hostId locationName locationId playing buffering rx tx savedBw
2018-03-23T20:31:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2419 1602 -817
2018-03-23T20:31:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 0 0 2694 2339 -355
2018-03-23T20:32:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2282 1530 -752
2018-03-23T20:32:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 165189 190873 25684
2018-03-23T20:33:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2496 1624 -872
2018-03-23T20:33:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 435119 805249 370130
2018-03-23T20:34:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 1694 1277 -417
2018-03-23T20:34:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 433732 801739 368007
2018-03-23T20:35:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2349 1549 -800
2018-03-23T20:35:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 433963 802286 368323
2018-03-23T20:36:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2442 1607 -835
2018-03-23T20:36:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 432888 802216 369328
2018-03-23T20:37:00Z server-001.ecdn-demo.ecdn-ustream.com 455 Budapest 17 0 0 2277 1516 -761
2018-03-23T20:37:00Z server-002.ecdn-demo.ecdn-ustream.com 467 Budapest 17 2 0 433578 802535 368957

A report with kind = "locations":

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

timestamp locationName locationId playing buffering rx tx savedBw
2018-03-23T20:31:00Z Budapest 17 0 0 7284 5278 -2006
2018-03-23T20:32:00Z Budapest 17 2 0 170337 194037 23700
2018-03-23T20:33:00Z Budapest 17 2 0 440121 808363 368242
2018-03-23T20:34:00Z Budapest 17 2 0 438270 804624 366354
2018-03-23T20:35:00Z Budapest 17 2 0 438297 805072 366775
2018-03-23T20:36:00Z Budapest 17 2 0 438163 805453 367290
2018-03-23T20:37:00Z Budapest 17 2 0 438417 805576 367159

Interpreting the data

How many viewers watched a broadcast via the ECDNs?

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

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

How many viewers experienced buffering during the broadcast?

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

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

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

On buffering, the IBM Cloud Video 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 buffering column. sort | uniq the data to remove duplicates.

Similarly, in the servers report, identify all servers with non-zero values in the buffering 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.

Powered by Zendesk