Product Documentation

Accès aux données à l'aide de l'API

Jun 20, 2017

Les types de données suivants sont disponibles par le biais de l'API Monitor Service :

  • des données liées à des échecs de connexion ;
  • des machines dans un état d’échec ;
  • l'utilisation de la session ;
  • Durée d'ouverture de session
  • les données d'équilibrage de charge ;
  • les corrections à chaud appliquées à une machine ;
  • l'utilisation de l'application hébergée.

Pour accéder à une description complète des objets de données, consultez la section http://blogs.citrix.com/2013/08/27/xendesktop-7-monitor-service-what-data-is-available/

Pour utiliser l'API Monitor Service OData, vous devez être un administrateur XenApp ou XenDesktop. Pour appeler l’API vous avez besoin des privilèges en lecture seule ; toutefois, les données retournées sont déterminées par les rôles et les permissions de l'administrateur XenApp ou XenDesktop. Par exemple, les administrateurs du groupe de mise à disposition peuvent appeler l’API du service Monitor, mais les données qu'ils peuvent obtenir sont contrôlées par l'accès au groupe de mise à disposition configuré à l'aide de Citrix Studio. Pour plus d'informations sur les rôles et les permissions de l'administrateur XenApp ou XenDesktop, consultez la section Délégation de l'administration.

Requête des données

L'API du service Monitor de l'API du service est un API REST qui peut être accédé à l'aide d'un consommateur OData. Les consommateurs OData sont des applications qui consomment des données exposées à l'aide du protocole OData. Les consommateurs OData varient en sophistication, d'un simple navigateur Web à des applications personnalisées qui peuvent bénéficier de toutes les fonctionnalités du protocole OData. Pour de plus amples informations sur les consommateurs OData, consultez : http://www.odata.org/ecosystem#consumers.

Chaque partie du modèle de données du service Monitor Service est accessible et peut être filtrée sur l'adresse URL. OData fournit un langage de requête au format de l'adresse URL que vous utilisez pour récupérer des entrées à partir d'un service. Pour de plus amples informations, veuillez consulter http://msdn.microsoft.com/en-us/library/ff478141.aspx.

La requête est traitée du côté serveur et peut être filtrée davantage en utilisant le protocole OData du côté client.

Les données modélisées peuvent être classées en trois catégories : les données agrégées (les tables de résumé), l'état actuel des objets (machines, sessions, etc.) et les données de journal, qui sont en fait des événements historiques (les connexions, par exemple).

Remarque : les énumérations ne sont pas prises en charge dans le protocole OData ; les entiers sont utilisés à la place. Pour déterminer les valeurs retournées par l'API Monitor Service OData, consultez la section http://support.citrix.com/help/monitorserviceapi/7.6/.

Agrégation des valeurs de données

Le service Monitor collecte les données, notamment l'utilisation de la session utilisateur, les détails des performances de l'ouverture de session utilisateur, les détails de l'équilibrage de charge de la session, et les informations de connexion et d'échec de machine. Les données sont agrégées différemment en fonction de leur catégorie. La compréhension de l'agrégation des valeurs de données présentées à l'aide de l'API OData Method est critique à l'interprétation des données. Par exemple :

  • Des sessions connectées et des échecs de machine se produisent sur une certaine période de temps, par conséquent, elles sont exposées en tant que maximum sur une période de temps.
  • LogOn Duration est une mesure de durée, par conséquent elle est exposée en tant que moyenne sur une période de temps.
  • LogOn Count et Connection Failures représentent des nombres d'occurrences sur une période de temps, et par conséquent sont exposés en tant que sommes sur une période de temps.

Évaluation de données simultanées

Les sessions doivent se chevaucher pour être considérées comme simultanées. Toutefois, lorsque l'intervalle de temps est de 1 minute, toutes les sessions de cette minute (si elles se chevauchent ou non) sont considérées comme simultanées, la taille de l'intervalle est si petite que la surcharge de performances impliquée dans le calcul de la précision ne vaut pas la valeur ajoutée. Si les sessions se produisent dans la même heure, mais pas dans la même minute, elles ne sont pas considérées comme se chevauchant.

Corrélation des tables de synthèse avec des données brutes

Le modèle de données représente des métriques de deux manières différentes :
  • Les tables de synthèse représentent des vues des mesures détaillées de l'agrégation par minute, heure et jour.
  • Les données brutes représentent des événements individuels ou l'état actuel de l'objet suivi dans la session, la connexion, l'application et autres objets.

Lorsque vous tentez de corréler les données dans les appels API ou dans le modèle de données lui-même, il est important de bien comprendre les concepts et les limitations suivantes :

  • Aucune données de synthèse pour les intervalles partiels. Des résumés de métriques sont conçus pour répondre aux besoins de tendances historiques sur de longues périodes. Les métriques sont agrégées dans la table de synthèse pour effectuer des intervalles. Il y aura pas de données de synthèse pour un intervalle partiel au début (les plus anciennes données disponibles) de la collection de données ni à la fin. Lorsque vous affichez les agrégations d'une journée (intervalle = 1 440), ceci signifie que la premier et le dernier jour incomplet ne possède pas de données. Bien que des données brutes puissent exister pour des intervalles partiels, elles ne seront jamais synthétisées. Vous pouvez déterminer le premier et le dernier intervalle d'agrégation pour une granularité de données particulière en extrayant les valeurs minimales et maximales de SummaryDate pour une table de synthèse particulière. La colonne SummaryDate représente le début de l'intervalle. La colonne Granularité représente la durée de l'intervalle pour les données agrégées.
  • Corrélation par heure. Les métriques sont agrégées dans la table de synthèse pour terminer les intervalles comme décrit ci-dessus. Ils peuvent être utilisés pour les tendances historiques, mais les événements bruts peuvent être plus actifs dans l'état de ce qui a été résumé pour l'analyse de tendances. Toute comparaison temporelle de synthèse des données brutes doit prendre en compte le fait qu'aucune donnée de synthèse pour les intervalles partiels susceptibles de se produire ou pour le début et la fin de la période de temps.
  • Événements manqués et latents. Les mesures qui sont agrégées dans la table de résumé peuvent être légèrement inexactes si les événements sont manqués ou latents pour la période d'agrégation. Bien que le service Monitor tente de conserver un état courant précis, il ne retourne pas dans le temps pour recalculer l'agrégation dans les tables de résumé pour les événements manqués ou latents.
  • Connexion haute disponibilité. Lors de la haute disponibilité de connexion, il existera des écarts dans les données de synthèse du nombre de connexions actives, mais les instances de session seront toujours en cours d'exécution dans les données brutes.
  • Périodes de rétention des données. Les données des tables de synthèse sont conservées sur un programme de nettoyage différent de celui de la planification des données brutes d'événement. Il se peut que les données soient manquantes, car elles ont été effacées depuis les tables de données de synthèse ou brutes. Les périodes de rétention peuvent également différer pour différents granularités de données de synthèse. Les données de granularité inférieures (en minutes) sont nettoyées plus rapidement que les données de granularité supérieures (en jours). Si des données sont manquantes dans une granularité à cause du nettoyage, elles peuvent être détectées dans une meilleure granularité. Étant donné que les appels API retournent uniquement la granularité demandée, l'absence de réception de données pour un niveau de granularité ne signifie pas que les données n'existent pas pour une meilleure granularité pour la même période.
  • Fuseaux horaires. Les métriques sont stockées avec des horodatages UTC. Les tables de synthèse sont regroupées sur des limites de fuseau horaire. Pour les zones qui ne se trouvent pas dans les limites horaires, il se peut qu'il existe une différence pour laquelle les données sont agrégées.

Granularité de données et rétention

La granularité des données agrégées récupérées par Director est une fonction de la période de temps (T) demandée. Les règles sont les suivantes :
  • 0 < T <= 1 heure utilise une granularité minute par minute
  • 0 < T <= 30 jours utilise une granularité heure par heure
  • T > 31 jours utilise une granularité jour par jour

Les données requises qui ne proviennent pas de données agrégées proviennent de la session brute et des informations de connexion. Ces données ont tendance à croître rapidement, et par conséquent, disposent de leur propre paramètre de nettoyage. Le nettoyage garantit que seules les données appropriées sont conservées à long terme. Cela garantit de meilleures performances tout en conservant la granularité nécessaire pour la création de rapports. Pour les clients qui ne possèdent pas de licence pour utiliser l'édition Platinum, le nettoyage commence le huitième jour, quel que soit le programme de rétention de nettoyage par défaut. Les clients Platinum peuvent modifier la rétention de nettoyage sur leur nombre de jours de rétention désirés, sinon, la valeur par défaut est utilisée.

Les paramètres suivants sont utilisés pour contrôler le nettoyage :

Nom du paramètre Nettoyage affecté Valeur par défaut (jours) Accès à l'aide de
GroomSessionsRetentionDays Enregistrements Session et SessionDetail 90 Applet de commande (set/get-monitorconfiguration)
GroomSummariesRetentionDays Enregistrements DesktopGroupSummary, FailureLogSummary et LoadIndexSummary. Données agrégées : granularité quotidienne. 90 Applet de commande (set/get-monitorconfiguration)
GroomHourlyRetentionDays Données agrégées : granularité horaire 32 Monitor.Configuration Database Table. Voir la remarque ci-dessous.
GroomMinuteRetentionDays Données agrégées : granularité par minute 3 Monitor.Configuration Database Table. Voir la remarque ci-dessous.
GroomFailuresRetentionDays Enregistrements MachineFailureLog et ConnectionFailureLog 90 Applet de commande (set/get-monitorconfiguration)
GroomLoadIndexesRetentionDays Enregistrements LoadIndex 90 Applet de commande (set/get-monitorconfiguration)
GroomDeletedRetentionDays Les entités Machine, Catalog, DesktopGroup et Hypervisor qui possèdent un LifecycleState « Supprimé ». Cette opération supprimera également tout enregistrement Session, SessionDetail, Summary, Failure ou LoadIndex. 90 Applet de commande (set/get-monitorconfiguration)
GroomMachineHotfixHistoryRetentionDays Corrections à chaud appliquées aux machines VDA et Controller 90 Applet de commande (set/get-monitorconfiguration)
Avertissement : la modification des valeurs de la base de données du service Monitor nécessite le redémarrage du service pour que les nouvelles valeurs prennent effet. Vous êtes invités à apporter des modifications à la base de données du service Monitor uniquement avec l'assistance de Citrix.

Notes sur la rétention de nettoyage :

  • Les clients Platinum peuvent modifier la rétention de nettoyage sur leur nombre de jours de rétention désirés, sinon, la valeur par défaut est utilisée.
  • Clients Enterprise Edition : le nettoyage commence le 32ème jour. 
  • Clients non Platinum non Enterprise Edition : le nettoyage commence le 8ème jour. 
La conservation de données pendant de longues périodes aura les conséquences suivantes sur la taille des tables :
  • Données horaires. Si les données horaires sont autorisées à rester dans la base de données pour un maximum de deux années, un site de 1 000 groupes de mise à disposition peut influencer la croissance de la base de données comme suit :

    1 000 groupes de mise à disposition x 24 heures/jour x 365 jours/an x 2 ans = 17 520 000 lignes de données. L'impact sur les performances d'une telle quantité importante de données dans les tables d'agrégation est significatif. Étant donné que les données du tableau de bord sont tirées de cette table, la configuration requise sur le serveur de base de données peut être importante. Il se peut que des quantités excessives de données aient un impact dramatique sur les performances.

  • Données de session et d'événement. Ce sont les données collectées chaque fois qu'une session est démarrée et qu'une connexion/reconnexion est effectuée. Pour un site important (100 000 utilisateurs), ces données vont s'accroître très rapidement. Par exemple, l'équivalent de deux ans de tables rassemblerait plus d'un To de données nécessitant une base de données d'entreprise de haut au niveau.