RAMS traffic resource

Overview

The RAMS traffic resource allows any user to retrieve traffic-related statistics, regarding the usage of his files or live-streams on the Rambla CDN. These may include, depending on the type of traffic and your advanced analytics settings:

• the amount of bytes being streamed or downloaded (= volume in gigabytes)
• the number of hits
• the date and time at which a file or directory on the CDN was last downloaded or streamed
• the number of end-users that streamed or downloaded a certain percentage of a file (requires the 'User Behaviour' analytics layer)
• the number of end-users that have watched a certain stream (live or on-demand) during a given number of seconds (requires the 'User Behaviour' analytics layer)
• the average number of seconds that a certain stream (live or on-demand) was played by end-users (requires the 'User Behaviour' analytics layer)
• the total number of seconds that a certain stream (live or on-demand) was played by end-users (requires the 'User Behaviour' analytics layer)

The traffic resource now supports two different ways to determine the period of time for which data is requested:

• through time units, which may be a single or multiple units (hour, day, week, month, year) or a range (inside a single year).
• through a date range, which is the period in between a given 'from' date and a given 'until' date

Statistics are ordered by the type of delivery method. For each delivery method, RAMS will return a separate (set of) result(s).

All statistics are attached to a specified location. The location can refer to an actual file, a live-stream or a virtual file. It is also possible to retrieve traffic statistics for a directory on the CDN: this will return the sum of the data for all files located inside the directory and its sub-directories (= recursive scan).

Actions

• GET http://rams.mon01.rambla.be/traffic/[location] : get a list of traffic entries for a file or directory.

Content

The traffic resource always responds with a list (= feed). This list contains one or multiple entries: a separate entry is returned for each type of traffic and for each kind of filesystem-item (see this example).

Attributes

To further specify its content, each 'entry' element contains two additional attributes:

• raws:type = the type of delivery that this entry concerns (see RAMS types for possible values).
• raws:kind = the kind of filesystem-item, for which the traffic was recorded (see RAMS kinds for possible values).

Parameters

A traffic entry's content consists of a number of parameters, each containing statistical data or information about the resource. Some parameter values will always be set (= required), while others may be empty depending on the user's configuration settings and/or the type of traffic (= optional).

required params

• path : the location of this entry on the CDN, relative to the user's root-directory on the CDN (= relative path). See RAWS locations for details.
• volume : total amount of traffic in gigabyte
• hits : total number of hits
• last_modified : timestamp identifying the time at which the most recent change to the entry's statistics occurred
• last_request : timestamp identifying the last time at which the file or stream was successfully requested
• updated : timestamp identifying the date and time at which (this part of) the request was processed by RAMS

optional params

For these parameters to be set, the 'User Behaviour' analytics layer must be turned on for your user account (contact Rambla support for more info):

• pct_0_10, pct_10_20, pct_20_30, pct_30_40, pct_40_50, pct_50_60, pct_60_70, pct_70_80, pct_80_90, pct_90_100, pct_unknown : the number of HTTP or RTMP client connections that were streaming or downloading a given percentage of a file. See the "percentages" section below for details.
• time0, time1, time2, time3, time4, time5, time6, time7, time8, time9 : the number of RTMP client connections that were playing a stream during a given period of time. See the "streamed time" section below for details.
• sec_avg : the average number of seconds that a stream was played continuously.
• sec_total : the total number of seconds that were streamed.

Content Details

percentages

HTTP or RTMP requests may be cancelled by the client before the complete file has been streamed or downloaded. In that case, only a certain percentage of the file has been streamed or downloaded from the CDN. The "percentage" params identify the total number of requests that streamed or downloaded a given percentage of a file. For example, when the pct_10_20 param contains a value of "75" for a 100 Mb file, this means that 75 requests were interrupted by the client after downloading/streaming 10 Mb and before downloading/streaming 20 Mb.

Percentage data can only be recorded for HTTP requests and on-demand RTMP requests. Other types of file access will not show up in the percentage statistics. In the exceptional case that the server was unable to determine the percentage for a HTTP or on-demand RTMP request, the connection will be added to the pct_unknown parameter.

streamed time

In case of RTMP requests, the server is capable of recording the number of seconds that a stream was played continuously. The "time" params identifies the number of viewers playing a stream during a given number of seconds. The pre-defined values for the "time" params are:

• time0 => 0 to 1 seconds
• time1 => 1 to 10 seconds
• time2 => 10 to 60 seconds
• time3 => 60 to 300 seconds
• time4 => 300 to 900 seconds
• time5 => 900 to 1800 seconds
• time6 => 1800 to 3600 seconds
• time7 => 3600 to 7200 seconds
• time8 => more than 7200 seconds

Action Details

URL path

GET http://rams.mon01.rambla.be/traffic/[location]

All "traffic" requests are GET requests that - if successful - return a list of one or multiple traffic entries. The location part of the URL path should point to the resource for which traffic data needs to be retrieved.

An alternative way to describe the URL path is: http://rams.mon01.rambla.be/traffic/[{dirname}...]/[{filename}/].

Query-String Arguments

Overview

Query-string arguments serve a number of different purposes:

• determining the kind of request
• determining the requested period of time
• limiting the results to certain types of traffic
• handling pagination to limit the number of entries to be returned by a single request

API changes + backward compatibility

• For performance reasons, RAMS limits the number of entries that can be retrieved in a single request to 100. To retrieve more than 100 result, a RAMS client should use pagination. See the pagination section below for details.
• For reasons of transparancy, RAMS no longer returns multiple kinds of traffic in a single response. See the kind section below for details.

Nevertheless, RAMS v3 still supports requests made using the RAMS v2 API (= no pagination + all kinds are returned in a single response). This gives maintainers of existing client applications the chance to adapt their code where necessary.

• Note that support for RAMS v2 requests will be removed in the next version of RAMS. Adapting an existing client can easily be done by passing the "paginate_by" and "kind" arguments in the query-string of every request.
• Note also that pagination will be imposed and a single kind will be returned if any new RAMS v3 features are added to the RAMS v2 code (= by using query-string arguments that didn't exist in RAMS v2 - e.g. when including a "kind" or "from/until" argument in the query-string).

time units and date ranges

To specify the period for which RAMS needs to return traffic data, you can either use the existing time unit arguments or the new date range arguments. If no argument is passed, RAMS will return data for the current month (= default).

When using time units, the year and month arguments must always be part of the query-string (= required). The week, day and hour arguments are optional. For more details, see the time unit reference.

When using date ranges, both the 'from' and 'until' argument must be included in the query-string and must refer to a valid day. The date range argument can not be used to specify hours, minutes or seconds. For more details, see the date range reference.

kind

The 'kind' argument may contain one of these values: "root", "dir", "file" and "recursive"; see the RAMS kinds reference for more details. We recommend that you always include a kind argument as part of each 'traffic' request. If no 'kind' argument is passed, it defaults to "root".

Note: for backward compatibility, 'kind' currently still defaults to "all" (= combination of "root","dir" and "file") when a request is made in accordance with the RAMS v2 API. To get ready for RAMS v4, client application maintainers should adapt their "traffic" requests, so they contain a single 'kind' argument in the query-string. In RAMS v4, requests without a 'kind' argument will default to ("?kind=file").

type

One or multiple traffic types may be included in the 'traffic' response, depending on the value of the 'type' argument. If no 'type' argument is passed, RAMS will return data for all traffic types.

It is generally considered good practice to specify the 'type' value(s) in your RAMS request. Note that when requesting multiple types in a single RAMS request, RAMS may return entries referring to the same location but concerning a different traffic type in consecutive response pages.

pagination

A traffic feed may contain partial results, if more entries are available than the number of entries per page. The default number of entries per page is 50, but the client can tweak this number by including the paginate_by argument in the query-string. The maximum number of entries per page is 100. For more details about pagination in general, see the ATOM pagination reference.

Note: for backward compatibility, pagination is currently still omitted (= all results are returned in a single response) when a request is made in accordance with the RAMS v2 API. To get ready for RAMS v4, client application maintainers should adapt their "traffic" requests, so they contain a 'paginate_by' argument in the query-string. In RAMS v4, all requests without a 'paginate_by' argument will default to ("?paginate_by=50").

Partial results are ordered by RAMS first alphabetically and second by traffic type. For example, a query-string ?paginate_by=10;kind=file;type=all for a directory that contains 8 files, all of them having both ftp and http traffic, will result in 2 partial feeds being returned by RAMS:

• the first page will contain two entries (= 1 entry with type=http + 1 entry with type=ftp) for each of the first 5 files (= ordered alphabetically) => total = 10 entries
• the second page will contain two entries (= 1 entry with type=http + 1 entry with type=ftp) for each of the next 3 files => total = 6 entries

(iq)tag / (iq)meta

The "(iq)tag" and "(iq)meta" arguments allow you to query for traffic data based on the metadata of the files (which caused the traffic). All searches are recursive: so when including search arguments in your query-string, all files and/or directory below the URL path location will be returned if they meet the search criteria (and have resulted in traffic).

Limitations:

• "(iq)tag" and "(iq)meta" query-string arguments may not be combined in the same request.
• Pagination applies to the number of locations that were found, not to the number of traffic entries. Therefore, the actual number of entries could be less or more than the 'paginate_by' value.

For further details and examples, see the Search by tag and Search by meta sections.

Response

The traffic resource responds to a GET request with an atom (or xml) feed (see this example). The number of entries in the feed will depend on the query-string arguments that have been passed in the request. A request to the traffic resource succeeds if any traffic data is available (at least one entry can be returned).

Error Response

In case no traffic has been recorded for the location (passed via the URL), given the requested type(s), kind(s) and period of time (passed via the query-string), RAMS will respond with a 404 HTTP status code and a NoSuchResource or NoSuchItem Error Response.

• The NoSuchResource error indicates that some traffic data is available for the path, but that your query-string argument requires RAMS to exclude that data from the response.
• The NoSuchItem error indicates that the path doesn't point to an existing CDN location or that no traffic data has been recorded for this location during the requested time-unit.