Product Documentation

APIを使ったデータアクセス

Mar 25, 2016

以下の種類のデータは、Monitor Service APIを介して使用できます。

  • 接続エラーに関するデータ
  • エラー状態のマシン
  • セッションの使用
  • ログオン処理時間
  • 負荷分散データ
  • マシンに適用されたHotfix
  • ホストされたアプリケーションの使用

データオブジェクトの説明について詳しくは、http://blogs.citrix.com/2013/08/27/xendesktop-7-monitor-service-what-data-is-available/を参照してください。

Monitor Service OData APIを使用するには、XenAppまたはXenDesktopの管理者である必要があります。 APIを呼び出すには、読み取り専用の特権が必要です。ただし、返されるデータは、その管理者の役割と権限によって異なる場合があります。 たとえば、デリバリーグループ管理者はMonitor Service APIを呼び出すことができますが、取得可能なデータはCitrix Studioでセットアップされるデリバリーグループアクセスにより制御されます。 XenApp/XenDesktop管理者の役割と権限について詳しくは、「管理権限の委任」を参照してください。

データのクエリ

Monitor Service APIは、ODataコンシューマーでアクセスできるRESTベースのAPIです。 ODataコンシューマーは、ODataプロトコルで公開されたデータを消費するアプリケーションを指します。 シンプルなWebブラウザーからODataプロトコルのすべての機能を実行できるカスタムアプリケーションまでさまざまなODataコンシューマーがあります。 ODataコンシューマーについて詳しくは、http://www.odata.org/ecosystem#consumersを参照してください(英文)。

Monitor Serviceデータモデルのすべての部分はアクセス可能で、URL上でフィルタリングできます。 ODataでは、URL形式のクエリ言語を使用してサービスからエントリを抽出できます。 詳しくは、http://msdn.microsoft.com/ja-jp/library/ff478141.aspxを参照してください。

クエリはサーバー側で処理され、クライアント側でODataプロトコルを使ってさらに詳細にフィルタリングできます。

取得されるデータは、集計データ(サマリーテーブル)、オブジェクト(マシン、セッションなど)の現在の状態、およびログデータ(接続イベントなどの履歴)の3つのカテゴリに分類されます。

注:ODataプロトコルでは列挙(enum)はサポートされず、整数(integer)が使用されます。 Monitor Service OData APIによって返される値については、http://support.citrix.com/help/monitorserviceapi/7.6/を参照してださい。

データ値の集計

Monitor Serviceは、ユーザーセッション使用状況、ユーザーログオンの処理性能の詳細、セッションの負荷分散の詳細、および接続とマシンのエラー情報を含む、さまざまなデータを収集します。 データはカテゴリにより異なる方法で集計されます。 OData Method APIを使って示されたデータ値の集計を理解することは、データの解釈に不可欠です。 次に例を示します。

  • 接続セッション(Connected Session)やマシン障害(Machine Failure)は一定の期間の状態を示すため、その期間内の最大値として公開されます。
  • ログオン処理時間(LogOn Duration)は時間の長さを示す指標であるため、期間内の平均として公開されます。
  • ログオン数(LogOn Count)および接続障害(Connection Failure)は一定の期間に発生した数を示し、期間内の合計値として公開されます

同時接続データの評価

重複しているセッションは同時発生していると考える必要があります。 ただし、間隔として1分を指定した場合、1分以内に発生するすべてのセッションは(重複しているかしていないかに関係なく)すべて同時であるとみなされます。つまり、間隔のサイズが非常に小さいため、精度の計算に関係するパフォーマンス上のオーバーヘッドを考慮する必要はありません。 2つのセッションがその1時間内の別々の1分間に発生する場合、それらは重複しているとはみなされません。

サマリーテーブルと生データの相関関係

データモデルでは、以下の2つの方法でメトリックスが示されます。
  • サマリーテーブルでは、分単位、時間単位、および日単位のメトリックスを集計したものが示されます。
  • 生データは、セッション、接続、アプリケーション、およびそのほかのオブジェクト内で記録された個々のイベントまたは現在の状態を示します。

データをAPIコール間またはそのデータモデル内で関連付けるときは、以下の概念および制限事項を考慮してください。

  • 未完の間隔にはサマリーデータがありません。 メトリックスサマリーは長時間での履歴傾向を示すためのものであり、 完結した間隔のサマリーテーブルに集計されます。 データ収集の開始時や終了時のサマリーデータはありません。 1日(間隔=1440)の集計値の場合、最初と最後の未完の1日にはデータがないことを意味します。 これらの未完の間隔に生データが存在しても、そのデータが集計されることはありません。 各データ粒度の最初と最後の集計間隔は、各サマリーテーブルから最小と最大のSummaryDateを取得することで決定できます。 SummaryDate列は、間隔の開始時を示します。 Granularity列はその集計データの間隔の長さを示します。
  • 時間による関連付け。 前述のように、メトリックスは完結した間隔のサマリーテーブルに集計されます。 これらの値は履歴傾向を知る目的で使用できますが、生イベントの方が集計された値よりも傾向分析に適切な状態を示している場合があります。 集計値と生データとを時間ベースで比較する場合、未完の間隔や間隔の最初と最後にサマリーデータがないことを考慮する必要があります。
  • 欠落イベントまたは潜在イベント 集計期間で欠落または潜在しているイベントがあると、サマリーテーブルに集計されたメトリックスが正確でない場合があります。 Monitor Serviceでは現在の状態の正確な維持が試行されますが、過去にさかのぼって欠落イベントや潜在イベントをサマリーテーブルに再集計することはありません。
  • 接続の高可用性。 接続の高可用性により、現在の接続のサマリーデータ数に差異が生じることがありますが、セッションインスタンスは生データ内で実行されています。
  • データの保持期間。 サマリーテーブルのデータは、生イベントデータとは異なるクリーンアップ(グルーミング)スケジュールで保持されます。 このため、サマリーテーブルまたは生テーブルのクリーンアップにより、データが消去されている場合があります。 データの保持期間は、サマリーデータの粒度によっても異なる場合があります。 低い粒度(分単位)のデータは、高い粒度(日単位)のデータよりも早くクリーンアップされます。 特定の粒度のデータが消去されていても、より高い粒度のデータが存在している場合があります。 APIコールでは指定した粒度のデータのみが返されるため、データを取得できない場合でもその期間内のより高い粒度では取得できることがあります。
  • タイムゾーン。 格納されるメトリックスのタイムスタンプではUTCが使用されます。 サマリーテーブルは1時間区切りのタイムゾーンごとに集計されます。 1時間区切りのタイムゾーンに属さない場合は、データの集計先に不整合が生じることがあります。

データの粒度と保持

Directorで取得される集計データの粒度は、要求された時間(T)の関数です。 以下の規則があります。
  • 0 < T <= 1時間の場合は分単位の粒度
  • 0 < T <= 30日の場合は時間単位の粒度
  • T > 31日の場合は日単位の粒度

集計データから取得されないデータを要求すると、生のセッション(Session)および接続(Connection)情報から取得されます。 このデータの量はすぐに大きくなるため、専用のスケジュールでクリーンアップされます。 クリーンアップにより、意味のあるデータのみが長期間保持されます。 これにより、レポートに必要な粒度を維持しながら良好なパフォーマンスが提供されます。 Platinum以外のエディションでは、8日目からクリーンアップが開始されます。 Platinum Editionでは、クリーンアップが開始されるまでの日数をカスタマイズできます。

クリーンアップは以下の設定により制御されます。

設定名 対象データ デフォルト値(日数) アクセス方法
GroomSessionsRetentionDays SessionレコードおよびSessionDetailレコード 非Platinumユーザーは7日、Platinumユーザーは90日 コマンドレット(set/get-monitorconfiguration)
GroomSummariesRetentionDays DesktopGroupSummaryレコード、FailureLogSummaryレコード、およびLoadIndexSummaryレコード。 集計データ(日単位) 非Platinumユーザーは7日、Platinumユーザーは90日 コマンドレット(set/get-monitorconfiguration)
GroomHourlyRetentionDays 集計データ(時間単位) 32日 Monitor.Configuration Database Table。 下記注を参照
GroomMinuteRetentionDays 集計データ(分単位) 3日 Monitor.Configuration Database Table。 下記注を参照
GroomFailuresRetentionDays MachineFailureLogレコードおよびConnectionFailureLogレコード 非Platinumユーザーは7日、Platinumユーザーは90日 コマンドレット(set/get-monitorconfiguration)
GroomLoadIndexesRetentionDays LoadIndexレコード 非Platinumユーザーは7日、Platinumユーザーは90日 コマンドレット(set/get-monitorconfiguration)
GroomDeletedRetentionDays LifecycleStateが「Deleted」であるMachineエンティティ、Catalogエンティティ、DesktopGroupエンティティ、およびHypervisorエンティティ。 関連するSessionレコード、SessionDetailレコード、Summaryレコード、Failureレコード、またはLoadIndexレコードも削除される 非Platinumユーザーは7日、Platinumユーザーは90日 コマンドレット(set/get-monitorconfiguration)
GroomMachineHotfixHistoryRetentionDays VDAマシンおよびControllerマシンに適用されたHotfix 非PlatinumユーザーおよびPlatinumユーザーの両方で90日 コマンドレット(set/get-monitorconfiguration)
注意:Monitor Serviceデータベースの値を変更した後でその値を適用するには、このサービスを再起動する必要があります。 Monitor Serviceデータベースの値の変更は、Citrixサポート担当者からの指示があった場合のみ行ってください。
データを長期間保持すると、テーブルのサイズについて以下の影響が発生することがあります。
  • 時間単位のデータ。 時間単位のデータを2年などの長期間保持すると、1000個のデリバリーグループがあるサイトではデータベースが以下の数式に基づいて増大します。

    「1000個のデリバリーグループ×24時間/日×365日/年×2年=17,520,000行のデータ」 集計テーブルのデータ量が多いため、パフォーマンスに大きな影響を及ぼします。 ダッシュボードのデータがこのテーブルから取得されることを考慮すると、データベースサーバーに対する要求は高くなります。 データ量が過度に多いと、パフォーマンスが大きく低下します。

  • セッションとイベントのデータ。 各セッションの開始時および接続/再接続時に収集されるデータです。 大規模サイト(100,000ユーザーなど)では、このデータの量が急速に増加します。 たとえば、これらのテーブルでは2年間で1TB以上のデータが保持され、高性能なエンタープライズレベルのデータベースが必要になります。