3 RESTful API

Retrieving the SAU and SAtU Values

SAU KPI values are available under the r/sau/active/ URL path. The SAtU KPI values are available under the r/sau/attached/ URL path. Querying these HTTP resources with a GET request without any parameters will return the available one hour intervals for the last 24 hours.

curl --digest -u admin:secret 'http://ip-address/me/r/sau/active'
  

returns:

{
   "data": [
      {
            "duration": 3600,
            "errors": {
                "-1": []
            },
            "kpi_name": "sim_attached_users",
            "start_interval": 1374303600,
            "value": 210888
      },
      {
            "duration": 3600,
            "errors": {
                "-1": [
                    {
                        "error_code": "write_fails",
                        "failed_writes_count": 10
                    }
                ]
            },
            "kpi_name": "sim_attached_users",
            "start_interval": 1374307200,
            "value": 234320
       },
   ...
   ],
   "success": true
}

In the response, the success key indicates whether the API call was successful or if there were any exceptions while retrieving the values.

The data key is an array of JSON objects, each representing a measured interval and its properties and its value. Each of the JSON objects has the following keys:

• kpi_name: Valid values are sim_active_users for the Simultaneous Active Users KPI and sim_attached_users for the Simultaneous Attached Users KPI.

• start_interval: The Unix timestamp (UTC) of the start of the interval.

• duration: The interval duration. Valid values are the following multiples of 3600: 3600, 7200, 10800, 14400, 21600.

• value: The value of the KPI for the given interval in number of users.

• errors: A JSON object that has as keys the IDs of all the Mediation Engines from the setup and as values arrays with the errors objects detected during the interval. In case the query is executed against a Mediation Engine (typically in a setup with the Aggregation Engine), a single key is present "-1", representing the local ME. The error objects always contain a key called error_code with one of the following values:

  • discontinuous: There was an error calculating this interval. The result might be smaller than in reality.

  • unfinished: There was an error calculating this interval. The result might be smaller than in reality.

  • overload: The Session Monitor system was overloaded during this interval. Results may be inaccurate.

  • write_fails: There was a problem writing the KPI to the database. The result can be missing.

  • late_packets: The packets from the interval have arrived after the interval was finished and were not included in the KPI calculation. The KPI value might be slightly smaller than in reality. Session Monitor includes in the current interval packets that are late at most 20 seconds. Packets that are processed by the Session Monitor system more than 20 seconds after the interval has finished but less than 5 minutes after the interval is finished are not taken into account for the SAU calculation and will result in this error. Packets that are processed more than 5 minutes after the interval is finished are completely ignored.

The r/sau/active and r/sau/attached resources support the following filtering parameters, which are passed as GET query parameters. If more parameters are specified in the query, they are combined with a logical AND.

• start: Only interval objects with a start_interval value bigger than or equal to this parameter will be returned. The accepted format is UTC unix timestamp (seconds since the epoch).

  Default value is the current UTC timestamp minus 24 hours.

• stop: Only interval objects with a start_interval value strictly smaller than this parameter will be returned. The accepted format is UTC unix timestamp (seconds since the epoch).

  Default value is the current UTC timestamp.

• interval_length: Only interval objects with the duration key equal with this parameter will be returned. Only the following values are supported: 3600, 7200, 10800, 14400, 21600.

  Default value is 3600.

Query the One Hour Intervals

Query URL:

http://ip-address/me/r/sau/active?interval_length=3600&start=1375221600&stop=1375232400
  

Response:

{
   "data": [
      {
            "kpi_name": "sim_active_users",
            "duration": 3600,
            "start_interval": 1375221600,
            "errors": {
                "-1": []
            },
            "value": 310
      },
      {
            "kpi_name": "sim_active_users",
            "duration": 3600,
            "start_interval": 1375225200,
            "errors": {
                "-1": []
            },
            "value": 422
      },
      {
            "kpi_name": "sim_active_users",
            "duration": 3600,
            "start_interval": 1375228800,
            "errors": {
                "-1": []
            },
            "value": 731
      },
],
"success": true
}

Query the Three Hour Intervals from the Same Time Period

Query URL:

http://ip-address/me/r/sau/active?interval_length=10800&start=1375221600&stop=1375232400
  

Response:

{
   "data": [
      {
            "kpi_name": "sim_active_users",
            "duration": 10800,
            "start_interval": 1375221600,
            "errors": {
                "-1": []
            },
            "value": 1463
      },
      {
            "kpi_name": "sim_active_users",
            "duration": 10800,
            "start_interval": 1375225200,
            "errors": {
                "-1": []
            },
            "value": 1273
      },
      {
            "kpi_name": "sim_active_users",
            "duration": 10800,
            "start_interval": 1375228800,
            "errors": {
                "-1": []
            },
            "value": 1101
      }
   ],
   "success": true
}