Product Documentation

Accessing data using the API

Jun 13, 2013

The following topic explains how to access data using the Monitor Service OData API.

The Monitor Service API is built on top of SQL Server databases using Windows Communication Foundation (WCF) Data Services that are populated during processing and consolidation. Two endpoints are exposed using WCF with wsHttpBinding. The base address is: http:// {dc-host}/Citrix/Monitor/OData/v1. You can also use SSL to secure endpoints; see Securing endpoints using SSL for more information.
  1. The Methods endpoint exposes service operations which are used by Citrix Director to retrieve data that requires complex grouping and high performance standards, such as queries on the Dashboard and Trends pages. The Methods API URI is: http://{dc-host}/Citrix/Monitor/OData/v1/Methods
  2. The Data endpoint exposes read-only access directly to the database entities and can be accessed using the OData query language. This endpoint allows highly flexible access in terms of filtering and column selection, but does not provide the same performance benefits associated with the highly specific service operations. The Data API URI is: http://{dc-host}/Citrix/Monitor/OData/v1/Data

Authentication

To use the Monitor Service OData API, you must be a XenApp or XenDesktop administrator. To call the API you require read-only privileges; however, the data returned is determined by XenApp or XenDesktop administrator roles and permissions. For example, Delivery Group Administrators can call the Monitor Service API but the data they can obtain is controlled by Delivery Group access set up using Citrix Studio. For more information about XenApp or XenDesktop administrator roles and permissions, see Delegated Administration.

Querying the Data

The Monitor Service API is a REST-based API that can be accessed using an OData consumer. OData consumers are applications that consume data exposed using the OData protocol. OData consumers vary in sophistication, from simple web browsers to custom applications that can take advantage of all the features of the OData Protocol. For more information about OData consumers, see: http://www.odata.org/ecosystem#consumers.

Every part of the Monitor Service data model is accessible and can be filtered on the URL. OData provides a query language in the URL format you can use to retrieve entries from a service. For more information, see: http://msdn.microsoft.com/en-us/library/ff478141.aspx

The query is processed on the server side and can be filtered further using the OData protocol on the client side.

Note: Enums are not supported in the OData protocol; integers are used in their place. To determine the values returned by the Monitor Service OData API, see Determine enum values.

Categories of Data

The Monitor Service collects a variety of data, including user session usage, user logon performance details, session load balancing details, and connection and machine failure information. Data is aggregated differently depending on its category. Understanding the aggregation of data values presented using the OData Method APIs is critical to interpreting the data. For example:

  • Connected Sessions and Machine Failures occur over a period of time, therefore they are exposed as maximums over a time period
  • LogOn Duration is a measure of length of time, therefore is exposed as an average over a time period
  • LogOn Count and Connection Failures are counts of occurrences over a period of time, therefore are exposed as sums over a time period

Concurrent Data Evaluation

Sessions must be overlapping to be considered concurrent. However, when the time interval is 1 minute, all sessions in that minute (whether or not they overlap) are considered concurrent i.e. the size of the interval is so small that the performance overhead involved in calculating the precision is not worth the value added. If the sessions occur in the same hour, but not in the same minute, they are not considered to overlap.