Overview for Troubleshooting with Aternity REST API v2 (OData) (Beta)

Use deep-dive device-level REST API queries described in this article to extract high resolution raw data and troubleshoot issues for a specific device.

You can send REST API queries to directly extract Aternity's data collected for a single device without using Aternity dashboards and troubleshoot that device issues. It displays 2-minute summaries (aggregations), allowing a deep analysis of top processes at any given minute.
Access data by sending a URL to a browser, Excel or PowerBI

You can combine the data with other data sources if needed, or transform it as required, then view it in Microsoft Excel, Power BI, or your own data application.

For example, you can automatically load the data into Microsoft Excel or Power BI by entering the URL in the format of OData version 4 (Aternity supports only some of OData's parameters). Then select Refresh to update with the latest data. Alternatively, a programmer can send an OData URL request directly from the source code to retrieve the data, and then process it in the application as required.

The set of REST APIs described in this article is available in v2 only. Use one of the URL structures to access REST API:
  • <base_url>/v2/API_NAME?$filter=

  • <base_url>/v2.0/API_NAME?$filter=

  • <base_url>/latest/API_NAME?$filter=

To view an Aternity REST API, enter into a browser, Excel or PowerBI the base URL from User icon > REST API Access, followed by the name of the API and device_name as part of the URL:
https://<base_url>/latest/RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS?$filter=device_name eq 'name'

Each entry from the API represents a single device access and provides details about that device for the selected timeframe.

The list of all APIs is as follows:

REST API Name Description
RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS

Use RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS to view the resource usage of the top processes of each session of a single virtual app server at two-minute resolution, along with application, user, and process details.

Note

The Agent for End User Devices reports a device's highest resource consumers (top processes) only if one of the HRC measurements exceeds its predefined threshold. Not every process is being recorded, only those that breach the threshold. For example, if the CPU usage threshold is 50% (default) and the total CPU usage for all the processes on the device is at 80%, this API will return the five top processes which consume the most CPU.

Each entry from RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS represents measurements for the top process utilization for each session running on the selected virtual app server for a 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days)
RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVERS

Use RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVERS to view the resource usage of the process of a single server at one-minute resolution, along with application, user, and device details. Use this API to troubleshoot a server by getting all sessions that run on this server and their processes,

Note

The Agent for End User Devices reports a device's highest resource consumers (top processes) only if one of the HRC measurements exceeds its predefined threshold. Not every process is being recorded, only those that breach the threshold. For example, if the CPU usage threshold is 50% (default) and the total CPU usage for all the processes on the device is at 80%, this API will return the five top processes which consume the most CPU.

Each entry from RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVERS represents measurements for the top process utilization for a 2-min time slot during the defined timeframe for the selected virtual app server.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVERS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days)
RAW_DATA_TOP_PROCESSES

Use RAW_DATA_TOP_PROCESSES to troubleshoot a desktop. View the resource usage of the top processes for a single device, along with application, user, and device details.

Note

The Agent for End User Devices reports a device's highest resource consumers (top processes) only if one of the HRC measurements exceeds its predefined threshold. Not every process is being recorded, only those that breach the threshold. For example, if the CPU usage threshold is 50% (default) and the total CPU usage for all the processes on the device is at 80%, this API will return the five top processes which consume the most CPU.

Each entry from RAW_DATA_TOP_PROCESSES represents measurements for the top process utilization for a 2-min time slot during the defined timeframe for the selected desktop.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES?$filter=device_name%20eq%20%27JPEMBER1-W7%27
RAW_DATA_CPU_MEMORY

Use RAW_DATA_CPU_MEMORY to view raw data regarding CPU and memory usage by a single physical device without aggregation mechanism.

Each entry from RAW_DATA_CPU_MEMORY represents a CPU and memory utilization for every 2-min time slot during the defined timeframe for the selected device.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_CPU_MEMORY?$filter=device_name%20eq%20%27JPEMBER1-W7%27
RAW_DATA_WIFI_NETWORK

Use RAW_DATA_WIFI_NETWORK to troubleshoot the WiFi network of a device. For example, check the WiFi signal strength of a device

Each entry from RAW_DATA_WIFI_NETWORK represents a WiFi signal strength on the selected device for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_WIFI_NETWORK?$filter=device_name%20eq%20%27JPEMBER1-W7%27
RAW_DATA_CPU_MEMORY_IO_VIRTUAL_APP_SERVER_SESSIONS

Use RAW_DATA_CPU_MEMORY_IO_VIRTUAL_APP_SERVER_SESSIONS to view data regarding CPU and memory usage by sessions (HRC, not the usage by one application).

Each entry from RAW_DATA_CPU_MEMORY_IO_VIRTUAL_APP_SERVER_SESSIONS represents a CPU, memory, and IO utilization for each session running on the selected virtual app server every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_CPU_MEMORY_IO_VIRTUAL_APP_SERVER_SESSIONS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days)
RAW_DATA_BATTERY

Use RAW_DATA_BATTERY to troubleshoot the battery usage level for the selected device for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_BATTERY?$filter=device_name%20eq%20%27Patsy_Pfaff_Tablet%27
RAW_DATA_STORAGE

Use RAW_DATA_STORAGE to troubleshoot the free space of a device.

Each entry from RAW_DATA_STORAGE represents the amount of available storage for the selected device for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_STORAGE?$filter=device_name%20eq%20%27Patsy_Pfaff_Tablet%27
RAW_DATA_IO

Use RAW_DATA_IO to troubleshoot the read/write capabilities of a disk and network for the selected device.

Each entry from RAW_DATA_IO represents the IO for a disk and IO for the network for the selected device for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_IO?$filter=device_name%20eq%20%27JPEMBER1-W7%27
RAW_DATA_MAX_CPU_CORE_UTILIZATION

Use RAW_DATA_MAX_CPU_CORE_UTILIZATION to troubleshoot the core with maximum utilization for a selected device.

Each entry from RAW_DATA_MAX_CPU_CORE_UTILIZATION displays the individual CPU core processor with the highest percentage usage for the selected device for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_MAX_CPU_CORE_UTILIZATION?$filter=device_name%20eq%20%27JPEMBER1-W7%27
RAW_DATA_DISKS_VIRTUAL_APP_SERVERS

Use RAW_DATA_DISKS_VIRTUAL_APP_SERVERS to troubleshoot the used resources of any disk on the selected virtual app server.

Each entry from RAW_DATA_DISKS_VIRTUAL_APP_SERVERS represents disk's IO and queue length for each drive on the selected virtual app server for every 2-min time slot during the defined timeframe.

The URL example:

https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_DISKS_VIRTUAL_APP_SERVERS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days)
RAW_DATA_RESOURCES_SUMMARY_VIRTUAL_APP_SERVERS

Use RAW_DATA_RESOURCES_SUMMARY_VIRTUAL_APP_SERVERS to view the summary of all resources utilization for all sessions for the selected virtual app server, calculated from data that Aternity aggregates every two minutes.

Each entry from RAW_DATA_RESOURCES_SUMMARY_VIRTUAL_APP_SERVERS represents host resources utilization for every 2-min time slot for all sessions running on the selected virtual app server during the defined timeframe.

The URL example:
https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_RESOURCES_SUMMARY_VIRTUAL_APP_SERVERS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days
RAW_DATA_MOBILE_NETWORK

Use RAW_DATA_MOBILE_NETWORK to troubleshoot the mobile network of a device. For example, check the signal strength of a device and check the theory if signal strength depends on the cellular carrier to which the device is connected.

Each entry from RAW_DATA_MOBILE_NETWORK represents a mobile carrier signal strength for every 2-min time slot during the defined timeframe for the selected device.

The URL example:
https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_MOBILE_NETWORK?$filter=device_name%20eq%20%27Patsy_Pfaff_Tablet%27

The retention period for these REST APIs is seven days. Each entry row provides data , calculated from data that Aternity aggregates every two minutes.

Tip

Special characters must be encoded in a percent-encoding format, meaning as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits. For example, %20 is the percent-encoding for the space character, and %27 for the single-apostrophe character. That is the basic URL encoding (https://tools.ietf.org/html/rfc3986#section-2.1) that applies to REST API in general. If you use a browser, Excel or PowerBI, they will automatically encode any special character for you. But if you copy examples from the articles, make sure to manually add the encoding for spaces and apostrophes. Otherwise, your query might fail.

Before you begin

Ensure you have the following:

  • To send a REST API query in Excel, PowerBI or a browser, enter the URL of the REST API, your Aternity username (must have the OData REST API role) and its password. You can find this by selecting User icon > REST API Access. SSO users must generate (once) and use a special password, as Aternity's REST API does not authenticate with your enterprise's identity provider.

  • If you have a legacy Microsoft Excel 2010 or 2013, download and add the Microsoft Power Query plug-in (only available for Windows only, not Mac). It adds a Power Query tab in Excel 2010 or 2013, which understands the latest OData standard.

    If you have Excel 2016 or later, there is no need for an extra plugin, as this functionality is built-in.

  • Define with what time zone you want to work, Aternity Management Server's or your local. The default time zone is time zone of the Aternity Management Server. It is possible to change the timezone to a local timezone of your account. Administrator of Aternity can set it in the My Account screen.

  • Ensure you are well familiar with the URL link structure. Add parameters to the URL to filter the returned data, by adding a question mark (?) followed by a parameter and value, such as <base_url/version/API_Name?$filter=device name or ID optional filters or commands>

    (for example,
    https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES?$filter=device_name eq 'Adam_Covert_VDI'
    )
  • Read carefully the tips on how to create a query. The URL of the REST API must include filters as described in the tables below:
    • The first filter is MANDATORY ($filter=) and must be one of the following:

      Field Description
      device_name eq

      $filter=device_name eq 'name'

      No parenthesis.

      For example:
      https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_CPU_MEMORY?$filter=device_name%20eq%20%27JPEMBER1-W7%27
      (device_name eq 'A' or device_name eq 'B')

      $filter=(device_name eq 'nameA' or device_name eq 'nameB')

      A single parenthesis surrounding the whole list.

      Use $filter= to insert conditions that narrow down the data, to return only entries where those conditions are true.

    • The second filter is OPTIONAL and can be added AFTER the first filter with AND condition (first_filter and second_filter).
    • The second filter must be one of the following:

      Field Description
      measurement_start_timestamp gt/ge 'value'

      gt: Greater than

      ge: Greater than or equal

      Use the filter with the following syntax:
      measurement_start_timestamp lt/le 'value'

      lt: Less than

      le: Less than or equal

      Use the filter with the following syntax:

      A combination of the above two filters with and between them

      and: Logical and

      For example, COL1 eq 'value1' and COL2 ne 'value2'

      Use the filter with the following syntax:

      relative_time(…)

      Use the filter with the following syntax:
      and relative_time(last_x_hours) and
      or
      and relative_time(last_x_days) and
      Foe example:
      https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS?$filter=device_name%20eq%20%27At-WVD-Pool1-0%27%20and%20relative_time(last_4_days)

      Possible values are:

      • last_x_hours (like last_6_hours or last_24_hours): Displays data starting from exactly this time several hours ago, displaying it summarized (aggregated) according to the timeframe view you selected.

      • today: Displays data starting from 00:00AM today according to the time zone of the account.

      • yesterday: Displays data starting from 00:00AM yesterday according to the time zone of the account.

      • last_x_days (like last_7_days): Displays data starting from 00:00AM several days ago in the time zone of the Aternity Management Server, displaying it summarized (aggregated) according to the timeframe view you selected.

      • this_week: Displays data for this week, beginning from 00:00 AM on Sunday morning according to the time zone of the Aternity Management Server, until the current time.

      • last_week: Displays data from 00:00AM on Sunday morning to 23:59 on the most recent Saturday night, displaying it summarized (aggregated) according to the timeframe view you selected.. Use this view to compare consistent weekly results.

      Alternatively, you can limit the scope of a query to the period between two static times, by creating a filter of a timeframe greater than or equal to (ge) the start time and less than or equal to (le) the end time.

    • (OPTIONAL) Add $select= to the URL to return only specific columns (attributes). You can use $select= to return some of the fields, but it will not cause the data to be aggregated by the selected fields, because there is no aggregation for these REST APIs. For example:
      https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_CPU_MEMORY?$filter=device_name%20eq%20%27JPEMBER1-W7%27&$select=MEASUREMENT_START_TIMESTAMP,HRC_CPU_UTIL
    • (OPTIONAL) Use $top= (lower case only) when you are initially testing the response of the API by returning the first few entries. For example:
      https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_CPU_MEMORY?$filter=device_name%20eq%20%27JPEMBER1-W7%27&$select=MEASUREMENT_START_TIMESTAMP,HRC_CPU_UTIL&$top=3
    • This set of REST APIs does NOT split large results into pages, all data is returned in one page (there is no Next link).

    • This set of REST APIs can return up to one million entries (rows) and all in one page. Over that, you will get the error message Response exceeds the max number of record.

Procedure

  1. Step 1 (Optional) As a simple test to preview the raw data in XML or JSON format, enter the request URL in a browser.

    For example, enter http://my-demo-odata.aternity.com/aternity.odata/v2/$metadata

    Previewing the raw REST API response in a browser
    Tip

    If you cannot connect, try the CONNECTION_TEST API, which does not require you to sign in. Depending on your region, try this for my-odata, us2-odata, eu-odata, or any other environment. For example, enter http://my-demo-odata.aternity.com/aternity.odata/CONNECTION_TEST

    Some browsers default to XML format, others to JSON. You can force the format by adding $format=XML in the URL.

  2. Step 2 Open Excel and select From OData Feed.

    In Excel 2010 or 2013, select Power Query > From Other Sources > From OData Feed.

    Use Power Query plugin to access REST API

    In Excel 2016, select Data > New Query > From Other Sources > From OData Feed.

    Access REST API in Excel 2016

    If you use Microsoft 365, select Data > Get Data > From Other Sources > From OData Feed.

    Alternatively, if you use Microsoft Power BI, select Get Data > OData Feed.

  3. Step 3 Enter the URL of the OData API which you want to retrieve.

    Use any of the available APIs. For example, to retrieve a list of top processes of a VDI session for the user Adam: https://my-demo-odata.aternity.com/aternity.odata/latest/RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS?$filter=device_name eq 'Adam_Covert_VDI'

    Pay attention to the syntax rules:
    • Use https to connect to Aternity

    • Use $filter= as explained above

    • device_name is mandatory in the URL

    • Add %20 instead of spaces.

    • Add value(s) as in the sample: 'Adam_Covert_VDI'

    Enter the URL of the OData interface you want to retrieve
  4. Step 4 If you need to enter credentials, select Basic in the sidebar.
    Enter credentials to access OData APIs
    Field Description
    Username / Password

    Enter your Aternity username and password.

    To send a REST API query in Excel, PowerBI or a browser, enter the URL of the REST API, your Aternity username (must have the OData REST API role) and its password. You can find this by selecting User icon > REST API Access. SSO users must generate (once) and use a special password, as Aternity's REST API does not authenticate with your enterprise's identity provider.

  5. Step 5 Select Connect to display a preview of the data to be loaded.

    To change the API parameters or merge it with other queries, select Edit.

  6. Step 6 Select Load to insert the data into the spreadsheet.
    View data retrieved from the OData interface
    Tip

    To refresh the data in Excel from the same URL, select Design > Refresh.

    The columns of data depend on the API request you sent.

    REST API Name Dimensions and Measurements Description
    RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVER_SESSIONS

    The returned columns are:

    Account_IDApplication_NameApplication_Version,Measurement_Start_Timestamp,PRC_CPU_Util_Avg,PRC_IO_Read_Rate,PRC_IO_Write_Rate,PRC_Physical_Memory_Util_Avg,PRC_Virtual_Memory_Util_Avg,Processes_Count,Process_IDProcess_Name,Session_ID,Session_Start_Time,Username,User_Domain,Device_Name
    Tip

    Aternity records only those processes that exceeded their predefined threshold. There are many other processes running on the server at the same timeframe and not all of them are represented in the database; thus, any summaries (aggregations) will bring wrong results and should not apply to this API.

    RAW_DATA_TOP_PROCESSES_VIRTUAL_APP_SERVERS

    The returned columns are:

    Account_IDApplication_NameApplication_Version,Measurement_Start_Timestamp,PRC_CPU_Util_Max,PRC_CPU_Util_Total,PRC_IO_Read_Rate_Max,PRC_IO_Read_Rate_Total,PRC_IO_Write_Rate_Max,PRC_IO_Write_Rate_Total,PRC_Physical_Memory_Util_Max,PRC_Physical_Memory_Util_Total,PRC_Virtual_Memory_Util_Max,PRC_Virtual_Memory_Util_Total,Process_IDProcess_Name,Processes_Count,Sessions_CountDevice_Name
    Tip

    Aternity records only those processes that exceeded their predefined threshold. There are many other processes running on the server at the same timeframe and not all of them are represented in the database; thus, any summaries (aggregations) will bring wrong results and should not apply to this API.

    RAW_DATA_TOP_PROCESSES

    The returned columns are:

    Account_IDApplication_NameApplication_Version,Measurement_Start_Timestamp,PRC_CPU_Util_Avg,PRC_IO_Read_Rate,PRC_IO_Write_Rate,PRC_Physical_Memory_Util_Avg,PRC_Virtual_Memory_Util_Avg,Process_IDProcess_Name,Username,Device_Name

    Tip

    Aternity records only those processes that exceeded their predefined threshold. There are many other processes running on the server at the same timeframe and not all of them are represented in the database; thus, any summaries (aggregations) will bring wrong results and should not apply to this API.

    RAW_DATA_CPU_MEMORY

    The returned columns are:

    Account_ID,HRC_CPU_Util_Avg,HRC_Physical_Memory_Util_Avg,HRC_Virtual_Memory_Util_Avg,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_WIFI_NETWORK

    The returned columns are:

    Account_ID,Measurement_Start_Timestamp,Wifi_BSSID,Wifi_Channel,Wifi_MAC_Address,Wifi_Noise_Level_Avg, Wifi_Noise_Level_Max, Wifi_Noise_Level_Min,Wifi_Signal_Strength_Avg, Wifi_Signal_Strength_Max, Wifi_Signal_Strength_Min,Wifi_SNR_Avg, Wifi_SNR_Max, Wifi_SNR_Min,Wifi_SSID,Wifi_Transmission_Speed_Avg, Wifi_Transmission_Speed_Max, Wifi_Transmission_Speed_Min,Device_Name

    RAW_DATA_CPU_MEMORY_IO_VIRTUAL_APP_SERVER_SESSIONS

    The returned columns are:

    Account_ID,Application_Remote_Display_Latency_Avg,Client_IP_Address,HRC_CPU_Util_Avg.HRC_IO_Read_Rate_Avg,HRC_IO_Write_Rate_Avg,HRC_Physical_Memory_Util_Avg,HRC_Virtual_Memory_Util_Avg,Is_Monitored,Measurement_Start_Timestamp,Received_KB_Total, Sent_KB_Total,Session_ID,Session_Start_Time,Session_State,User_Domain,Username,Device_Name

    RAW_DATA_BATTERY

    The returned columns are:

    Account_ID,HRC_Mobile_Battery_Level_Max,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_STORAGE

    The returned columns are:

    Account_ID,Free_Space_MEGABYTES,Free_Space_PERCENT,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_IO

    The returned columns are:

    Account_ID,HRC_Disk_Queue_Length,HRC_IO_Read_Rate_Avg,HRC_IO_Write_Rate_Avg,Identifier,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_MAX_CPU_CORE_UTILIZATION

    The returned columns are:

    Account_ID,Device_CPU_ID,HRC_CPU_CORE_UTIL_MAX,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_DISKS_VIRTUAL_APP_SERVERS

    The returned columns are:

    Account_ID,Drive_Letter,HRC_Disk_IO_Read_Rate_Avg,HRC_Disk_IO_Write_Rate_Avg,HRC_Disk_Queue_Length,Measurement_Start_Timestamp,Device_Name

    RAW_DATA_RESOURCES_SUMMARY_VIRTUAL_APP_SERVERS

    The returned columns are:

    Account_ID,Active_Sessions_Count,Application_Remote_Display_Latency_Avg,HRC_CPU_Util_Avg,HRC_CPU_CORE_UTIL_MAX,HRC_Network_IO_Read_Rate_Avg,HRC_Network_IO_Write_Rate_Avg,HRC_Physical_Memory_Util_Avg,HRC_Virtual_Memory_Util_Avg,Measurement_Start_Timestamp,Total_Sessions_Count,Device_Name

    RAW_DATA_MOBILE_NETWORK

    The returned columns are:

    Account_ID,Device_Network_Type,Measurement_Start_Timestamp,Mobile_Carrier,Mobile_Signal_Strength,Device_Name