Product Documentation

使用 API 访问数据

Mar 17, 2016

以下类型的数据可通过 Monitor Service API 获得:

  • 与连接故障相关的数据
  • 处于故障状态的计算机
  • 会话使用情况
  • 登录持续时间
  • 负载平衡数据
  • 应用于计算机的修补程序
  • 托管应用程序的使用情况

要使用 Monitor Service OData API,您必须是 XenApp 或 XenDesktop 管理员。 要调用 API,您需要具有只读权限;但是,返回的数据由 XenApp 或 XenDesktop 管理员角色和权限决定。 例如,交付组管理员可以调用 Monitor Service API,但他们可以获取的数据由使用 Citrix Studio 设置的交付组访问权限控制。 有关 XenApp 或 XenDesktop 管理员角色和权限的详细信息,请参阅委派管理

查询数据

Monitor Service API 是一款基于 REST 的 API,可以使用 OData 使用者程序进行访问。 OData 使用者程序是占用使用 OData 协议显示的数据的应用程序。 从简单的 Web 浏览器到可利用 OData 协议的所有功能的自定义应用程序,OData 使用者程序的复杂程度各不相同。 有关 OData 使用者程序的详细信息,请参阅:http://www.odata.org/ecosystem#consumers

每一部分 Monitor Service 数据模型都可访问,并且可根据 URL 过滤。 OData 以 URL 格式提供查询语言,可用于从服务检索条目。 有关详细信息,请参阅:http://msdn.microsoft.com/en-us/library/ff478141.aspx

查询在服务器端进行处理,并且可以使用客户端上的 OData 协议进行进一步过滤。

建模数据分为以下三类:聚合数据(汇总表)、对象(计算机、会话等)的当前状态和日志数据,日志数据实际上是指历史事件(如连接)。

注意:OData 协议不支持枚举;在其位置使用整数。 要确定 Monitor Service OData API 返回的值,请参阅 http://support.citrix.com/help/monitorserviceapi/7.6/

数据值聚合

Monitor Service 收集多种数据,其中包括用户会话使用情况、用户登录性能详细信息、会话负载平衡详细信息,以及连接和计算机故障信息。 根据其类别,数据以不同的方式聚合。 了解使用 OData Method API 提供的数据值的聚合是解释数据的关键。 例如:

  • 一段时间内发生的连接会话故障和计算机故障,因此它们显示为一段时间内的最大值。
  • 登录持续时间是时间长度的度量,因此它们显示为一段时间内的平均值。
  • 登录计数和连接故障是一段时间内这类事件的计数,因此它们显示为一段时间内的总数。

并发数据评估

会话必须重叠才能视为并发。 但是,当时间间隔为 1 分钟时,该时间内的所有会话(无论会话是否重叠)都将被视为并发:由于时间间隔太小,计算精确度时所涉及的性能开销有些得不偿失。 如果会话发生在同一小时,但不同分钟内,则不会被视为重叠。

关联汇总表和行数据

数据模型以两种不同方式表示指标:
  • 汇总表以每分钟、每小时和每天的时间粒度表示指标的聚合视图。
  • 行数据表示单个事件或在会话、连接、应用程序或其他对象中跟踪到的当前状态。

尝试跨 API 调用或在数据模型自身内部关联数据时,必须理解以下概念和限制:

  • 不存在部分时间间隔的汇总数据。 指标汇总是为了洞察长时间内的历史趋势。 这些指标应该聚合到完整时间间隔的汇总表中。 不存在仅包含数据收集的开始时间(最早的可用数据)而不包含结束时间的部分时间间隔的汇总数据。 这意味着,当查看一天(时间间隔=1440)的聚合时,最早和最近的不完整日期将不包含数据。 尽管存在这些部分时间间隔的行数据,但不会汇总这些行数据。 对于特定时间粒度,可以通过从特定汇总表提取最小和最大 SummaryDate,确定最早和最近的聚合时间间隔。 SummaryDate 列表示时间间隔的开始时间。 Granularity 列表示聚合数据的时间间隔长度。
  • 按时间关联。 如上所述,指标聚合到完整时间间隔的汇总表中。 它们可以用于了解历史趋势,但是行事件的状态可能更新,不能通过汇总进行趋势分析。 基于时间比较汇总数据和行数据时,应注意不存在可能发生的任何部分时间间隔或时间段的开头和结尾部分的汇总数据。
  • 缺失的事件和延迟事件。 如果在聚合时间段有事件缺失或延迟,聚合到汇总表中的指标可能会略有误差。 尽管 Monitor Service 尝试维护准确的最新状态,但是它不会针对缺失或延迟的事件后退到过去重新计算汇总表中的聚合值。
  • 连接高可用性。 在连接 HA 期间,当前连接的汇总数据计数会存在误差,但是会话实例仍在行数据中运行。
  • 数据保留期限。 汇总表中的数据保留整理计划不同于行事件数据的计划。 由于数据已从汇总表或行表格加以整理,因此可能会有所缺失。 不同粒度的汇总数据的保留期限也有所差异。 粒度较低的数据(分钟)的整理速度高于粒度较高的数据(天)。 如果由于整理导致数据在某个粒度缺失,可以在更高的粒度找到此数据。 由于 API 调用仅返回所请求的指定粒度,接收不到某个粒度的数据并不表示同一时间段的数据在更高的粒度上也不存在。
  • 时区。 指标采用 UTC 时间戳存储。 汇总表按照小时时区边界聚合。 对于没有位于小时边界上的时区,数据聚合的时间可能会有所差异。

数据粒度和保留

Director 检索的聚合数据粒度是所请求的时间 (T) 跨度的函数。 规则如下:
  • 0 < T <= 1 小时采用每分钟粒度。
  • 0 < T <= 30 天采用每小时粒度。
  • T > 31 天采用每天粒度。

非来源于聚合数据的请求数据来源于 Session and Connection 行信息。 此数据往往增长很快,因此具有自己的整理设置。 通过整理可确保仅长期保留相关数据。 这样可以确保实现更好的性能,同时维护报告所需的粒度。 对于未获得使用 Platinum Edition 许可的客户,不管默认整理保留期限如何,均从第 8 天开始整理。 Platinum 客户可以将整理保留期限更改为他们所需的保留天数,如未修改,将使用默认值。

采用以下设置控制整理:

设置名称 受影响的整理 默认值(天) 访问方法
GroomSessionsRetentionDays Session 和 SessionDetail 记录 对于非 Platinum 用户为 7;对于 Platinum 为 90 Cmdlet (set/get-monitorconfiguration)
GroomSummariesRetentionDays DesktopGroupSummary、FailureLogSummary 和 LoadIndexSummary records。 聚合数据 - 日粒度。 对于非 Platinum 用户为 7;对于 Platinum 为 90 Cmdlet (set/get-monitorconfiguration)
GroomHourlyRetentionDays 聚合数据 - 小时粒度 32 天 Monitor.Configuration Database Table。 请参阅下面的注释。
GroomMinuteRetentionDays 聚合数据 - 分钟粒度 3 天 Monitor.Configuration Database Table。 请参阅下面的注释。
GroomFailuresRetentionDays MachineFailureLog 和 ConnectionFailureLog 记录 对于非 Platinum 用户为 7;对于 Platinum 为 90 Cmdlet (set/get-monitorconfiguration)
GroomLoadIndexesRetentionDays LoadIndex 记录 对于非 Platinum 用户为 7;对于 Platinum 为 90 Cmdlet (set/get-monitorconfiguration)
GroomDeletedRetentionDays LifecycleState 状态为“Deleted”的 Machine、Catalog、DesktopGroup 和 Hypervisor 条目。 将删除任何相关的 Session、SessionDetail、Summary、Failure 或 LoadIndex 条目。 对于非 Platinum 用户为 7;对于 Platinum 为 90 Cmdlet (set/get-monitorconfiguration)
GroomMachineHotfixHistoryRetentionDays 应用至 VDA 和 Controller 计算机的修补程序 非 Platinum 和 Platinum 用户均为 90 Cmdlet (set/get-monitorconfiguration)
警告:修改 Monitor Service 数据库上的值需要重新启动此服务才能使新值生效。 建议仅在 Citrix 技术支持人员的指导下修改 Monitor Service 数据库。
长期保留数据会对表格大小产生以下影响:
  • 小时数据。 如果允许小时粒度的数据在数据库中最多保留两年,具有 1000 个交付组的站点将导致数据库按以下方式增长:

    1000 个交付组 x 24 小时/天 x 365 天/年 x 2 年 = 17,520,000 行数据。 聚合表中存在如此巨大的数据量对性能的影响是非常显著的。 如果从此表格提取控制板数据,将需要使用大型数据库服务器。 数据量过大会对性能造成巨大影响。

  • 会话和事件数据。 这是指每次启动会话和建立连接/重新连接时收集的数据。 对于大型站点(10 万个用户),此数据的增长速度非常快。 例如,这些表格经过两年时间将大于 TB 级数据,这将要求使用企业级高端数据库。