Querying Access Stats

Querying a User's Access Statistics

Unreleased Feature

Access stats are tracked on a per-user basis, as rollups for slices of time. Querying these stats is done via the /usage/$USER_KEY_ID resource.

For information about access stats are logged, please read Logging Access Stats.

Choosing the Result Format

Results are available as either JSON or XML. Request the appropriate one by using the HTTP Accept header.

Specifying the User

Access stats are provided on a per-user basis. Specify which user's stats you want by providing that user's key_id in the URL. For example, to get access stats for the user key 1FF+PA1RZ+QM/FCVET64, use the URL /usage/1FF%2bPA1RZ%2bQM%2fFCVET64. Notice that the + and / characters have been escaped.

An 404 code with an error message body will be returned if the user does not exist. For example, there is no ASDF user in my cluster, so fetching http://localhost:8080/usage/ASDF produces:

JSON:

HTTP/1.1 404 Object Not Found

{"error":{"message":"Unknown user"}}

XML (reformatted for easy reading):

HTTP/1.1 404 Object Not Found

<?xml version="1.0" encoding="UTF-8"?>
<Error><Messsage>Unknown user</Messsage></Error>

Enable Access Results

The usage HTTP resource provides both access and storage statistics. Since each of these queries can be taxing in its own right, they are both omitted from the result by default:

curl http://localhost:8080/usage/1FF%2bPA1RZ%2bQM%2fFCVET64

JSON:

{"access":"not_requested","storage":"not_requested"}

XML (reformatted for easy reading):

<?xml version="1.0" encoding="UTF-8"?>
<Usage>
    <Access>not_requested</Access>
    <Storage>not_requested</Storage>
</Usage>

To request that access results be included, pass the query parameter a to the resource (any true-ish value will work, including just the bare a, t, true, 1, y, and yes):

curl http://localhost:8080/usage/1FF%2bPA1RZ%2bQM%2fFCVET64?a

JSON (reformatted for easy reading):

{"access":[
    {"node":"[email protected]",
     "samples":[
         {"start_time":"20120131T200700Z",
          "end_time":"20120131T200800Z",
          "bytes_out":0,
          "in_bytes":8721}]}],
 "storage":"not_requested"}

XML (reformatted for easy reading):

<?xml version="1.0" encoding="UTF-8"?>
<Usage>
    <Access>
        <Node name="[email protected]">
            <Sample start="20120131T200700Z" end="20120131T200800Z">
                <BytesOut>0</BytesOut>
                <in_bytes>8721</in_bytes>
            </Sample>
        </Node>
    </Access>
    <Storage>not_requested</Storage>
</Usage>

Specifying the Time Span to Report

Request the time span you want data for by passing s (start) and e (end) query parameters to the resource. The slices for which data will be returned are all of those between s and e, as well as the slice including s and the slice including e.

For example, for slices A-I:

   A     B     C     D     E     F     G     H     I
|-----|-----|-----|-----|-----|-----|-----|-----|-----|
              s                  e

Specifying an s that falls somewhere in slice C and an e that falls somewhere in slice F means that data for slices C, D, E, and F will be returned.

Each should be provided in ISO8601 format (yyyymmddThhmmssZ). For example, the following values would request the span between 2 and 2:15pm (GMT) on January 30, 2012:

http://localhost:8080/usage/1FF%2bPA1RZ%2bQM%2fFCVET64?a&s=20120130T140000Z&e=20120130T141500Z

JSON:

{"access":[
    {"node":"[email protected]",
     "samples":[
         {"start_time":"20120130T140800Z",
          "end_time":"20120130T140900Z",
          "bytes_out":0,
          "in_bytes":8721},
         {"start_time":"20120130T140900Z",
          "end_time":"20120130T141000Z",
           "bytes_out":8721}]}],
     "storage":"not_requested"}

XML:

<?xml version="1.0" encoding="UTF-8"?>
<Usage>
    <Access>
        <Node name="[email protected]">
            <Sample start="20120130T140800Z" end="20120130T140900Z">
                <BytesOut>0</BytesOut>
                <in_bytes>8721</in_bytes>
            </Sample>
            <Sample start="20120130T140900Z" end="20120130T141000Z">
                <BytesOut>8721</BytesOut>
            </Sample>
        </Node>
    </Access>
    <Storage>not_requested</Storage>
</Usage>

The behavior of the resource when the s or e parameter is omitted may change, but is currently:

• omitting e will cause the resource to return only data for the slice in which s falls
• omitting s will cause the resource to return data for all slices from e through the current time

Or, more simply, the default s is "now" and the default e is equal to s.

Interpretting the Results

Results of the access query are grouped by node. That is, within the access field of the result will be one entry for each MOSS node that had data for the requested time span.

Each node entry will contain one or more "samples", one for each time slice that the user accessed that MOSS node. The sample will have a start time and end time describing what span the sample covers.

The other entries of each sample are sums of the named access type for that time slice. For example, the "bytes out" field is the total number of file bytes that the user downloaded from MOSS during that timeslice.

It's important to note that accesses are only logged with the webmachine request finishes. This means that, for example, an upload started in one time slice but ended in another will only add to the "bytes in" field for the time slice in which in finished, rather than splitting the stats between the slices in which they actually happened.

Current Sample Fields

The fields currently available in an access sample are (JSON Name / XML Name):

• in_bytes / in_bytes : The number of bytes that were uploaded to the user's files during this slice
• bytes_out / BytesOut : The number of bytes that were donwloaded from the user's files during this slice