.. _GET Service ostor-usage:

GET Service ostor-usage
-----------------------

Description
~~~~~~~~~~~

Lists existing statistics objects or queries information contained in a specified object.

Requests
~~~~~~~~

Syntax
^^^^^^

::

    GET /?ostor-users HTTP/1.1
    Host: s3.amazonaws.com
    Date: <date>
    Authorization: <authorization_string>

::
    
    GET /?ostor-users&obj=object name
    HTTP/1.1
    Host: s3.amazonaws.com
    Date: <date>
    Authorization: <authorization_string>

Parameters
^^^^^^^^^^

The parameter is specified by the ``obj`` subresource. If the ``obj`` subresource is undefined, the response contains information about all existing statistics objects. Otherwise information from the specified object ``obj`` is returned.

+------------------+-------------------------------------------------------+----------+
| Parameter        | Description                                           | Required |
+==================+=======================================================+==========+
| ``obj``          | Statistics object name.                               | No       |
|                  |                                                       |          |
|                  | Type: string.                                         |          |
|                  |                                                       |          |
|                  | Default value: none.                                  |          |
+------------------+-------------------------------------------------------+----------+

Headers
^^^^^^^

This implementation uses only common request headers.

Responses
~~~~~~~~~

Headers
^^^^^^^

This implementation uses only common response headers.

Body
^^^^

If ``obj`` is unspecified:

::

    { "nr_items": number of statistics objects,
      "truncated": true if a list is truncated,
      "items": [ //list of statistics objects
       "first object's name",
       "s3-usage-obj1",
       "s3-usage-obj2",
       "s3-usage-obj3",
       ...
    ]
    }
 
If ``obj`` is specified:

::

    { "fmt_version": version of response format,
      "service_id": idof a service that collected statistics,
      "start_ts": timestamp of statistics upload,
      "period": statistics upload period in seconds,
      "nr_items": number of counters, 
      "items": [//list of usage counters
      {
           "key": { "bucket": "bucket-name", "epoch":bucket's epoch, "user_id": "user id", "tag": "statistics object tag" },
           "counters": {
                   "ops": { "put":count of put ops, "get": count of get ops, "list": count of list ops, "other": count of other ops },
                   "net_io": { "uploaded":number of uploaded bytes during the period,
                   "downloaded": number of downloaded bytes during the period }
           }
      },
      ...
     ]
    }
 
Examples
~~~~~~~~

Sample Request #1
^^^^^^^^^^^^^^^^^

The following request returns information about all statistics objects.

::

    GET /?ostor-usage /HTTP1.1
 Date : Mon, 11 Apr 2016 16:43:16 GMT+3:00
 Host : ostor-test-1
 Authorization : <authorization_string>

Sample Response #1
^^^^^^^^^^^^^^^^^^

::

    HTTP/1.1 200 OK
    x-amz-req-time-micros : 404
    Transfer-encoding : chunked
    Server : nginx/1.8.1
    Connection : keep-alive
    x-amz-request-id : 80000000000000030006b6be3b0ae378
    Date : Mon, 11 Apr 2016 13:43:16 GMT
    Content-type : application/json
    
    { "nr_items": 9,
      "truncated": false,
      "items": [
       "s3-usage-8000000000000003-2016-04-11T13:10:29.000Z-1800",
       "s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:13:23.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:15:53.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:16:23.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:31:54.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:33:25.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30",
       "s3-usage-8000000000000003-2016-04-11T13:34:25.000Z-30"
    ]
    }
 
Sample Request #2
^^^^^^^^^^^^^^^^^

The following request returns information from the object ``s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30``.

::

    GET /?ostor-usage&obj=s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30 /HTTP1.1
    Date: Mon, 11 Apr 2016 17:48:21 GMT+3:00
    Host: ostor-test-1
    Authorization: <authorization_string>
 
Sample Response #2
^^^^^^^^^^^^^^^^^^

::

    HTTP/1.1 200 OK
    X-amz-req-time-micros : 576
    Transfer-encoding : chunked
    Server : nginx/1.8.1
    Connection : keep-alive
    X-amz-request-id : 80000000000000030006b6bf23c77f09
    Date : Mon, 11 Apr 2016 14:48:21 GMT
    Content-type : application/json
    
    { "fmt_version": 1, "service_id":8000000000000003,
      "start_ts":1460380373, "period": 30, "nr_items":2, 
      "items": [
      {
           "key": { "bucket": "bucket", "epoch":16394, "user_id": "f82c23f7823589eb", "tag": "" },
           "counters": {
                   "ops": { "put":15, "get":0, "list":1, "other":0 },
                   "net_io": { "uploaded":99785, "downloaded":0 }
           }
      },
      {
           "key": { "bucket": "", "epoch":0, "user_id": "f82c23f7823589eb", "tag": "" },
           "counters": {
                   "ops": { "put":0, "get":2, "list":0, "other":0 },
                   "net_io": { "uploaded":0, "downloaded":0 }
           }
      } 
     ]
    }