Querying Storage Stats

Querying a User's Storage Statistics

Storage 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.

Note: Storage stats are not calculated by default. Please read Logging Storage Stats for details about how to enable storage calculation archival.

The basics of querying storage statistics, including the URL used and the parameters for specifying the time slice, are the same as they are for Querying Access Stats. Please refer to the descriptions there for more details.

Enable Storage 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/8NK4FH2SGKJJM8JIP2GU

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 storage results be included, pass the query parameter b to the resource (any true-ish value will work, including just the bare b, t, true, 1, y, and yes):

curl http://localhost:8080/usage/8NK4FH2SGKJJM8JIP2GU?b

JSON (reformatted for easy reading):

{"Access":"not_requested",
 "Storage":[{"Errors":[]}]}

XML (reformatted for easy reading):

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

There are no stats included in this report because the default time span is "now", which is not available in the archives.

S3 Object-style Access

As described in Querying Access Stats, these stats are also available as S3 objects. To add storage statistics to the result, add the character b to the Options portion of the object's path. For example, the following command would produce storage statistics in XML format:

s3cmd get s3://usage/8NK4FH2SGKJJM8JIP2GU/bx/20120315T140000Z/20120315T160000Z

You may also pass both b and a as Options to fetch both types of stats, as in:

s3cmd get s3://usage/8NK4FH2SGKJJM8JIP2GU/abx/20120315T140000Z/20120315T160000Z

Interpretting the Results

The result of the storage query is one or more "samples" for each time slice in which storage was calculated for the user. The sample will have a start time and end time describing what span the sample covers.

The other entries of each sample are the buckets the user owned during the sampled time. Bucket stats are provided as rollups including each of the following fields:

• Objects -- the number of active (not deleted, and not incompletely uploaded) files in the bucket
• Bytes -- the total of number of bytes stored in the files of the bucket

For example, a user that owns two buckets, foo and bar, where foo contains one 32MB file, and bar contains 4 32MB files, would have a sample similar to the following.

JSON (reformatted for easy reading):

{"Access":"not_requested",
 "Storage":[{"StartTime":"20120316T123318Z",
             "EndTime":"20120316T123319Z",
             "foo":{"Objects":1,"Bytes":32505856},
             "bar":{"Objects":4,"Bytes":130023424}},
            {"Errors":[]}]}

XML (reformatted for easy reading):

<?xml version="1.0" encoding="UTF-8"?>
<Usage>
  <Access>not_requested</Access>
  <Storage>
    <Sample StartTime="20120316T123318Z" EndTime="20120316T123319Z">
      <Bucket name="hooray">
        <Objects>1</Objects>
        <Bytes>32505856</Bytes>
      </Bucket>
      <Bucket name="foo6">
        <Objects>4</Objects>
        <Bytes>130023424</Bytes>
      </Bucket>
    </Sample>
    <Errors/>
  </Storage>
</Usage>