Using RESTful API to Export SAU and SAtU Values
The historical SAU and SAtU values can be exported by the use of RESTful APIs published at both the Mediation Engine (ME) layer and at the Aggregation Engine (AE) layer (by the Mediation Engine Connector product). The ME and the AE and MEC interfaces are identical, only the prefix is different.
For the ME, the API is found under:
http://<ip-address>/me/r/sau/
For the MEC (on the Aggregation Engine), the API is found under:
http://<ip-address>/mec/r/sau/
Note:
Session Monitor RESTful APIs are available both over HTTP and HTTPS. Oracle recommends always using the HTTPS version, except for the development and testing phase.The Session Monitor RESTful APIs uses digest authentication with the admin user credentials. See Operations Monitor User's Guide for the default value of the admin password and for how to change the password for production use.
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 } ] }
Note:
If a "404 Not supported" error is returned when calling this URL, it means that the SAU module is not enabled. It needs to be enabled in the setup configuration wizard (see "About Installing SAU Extension").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.
Note:
The currently measured interval is available by use of the RESTful API at most 30 minutes after it is finished.