Monitoring

Ewt intègre différents mécanismes de monitoring, notamment la génération d'un rapport d'état et la fourniture de metrics.

Rapport d'état

Ewt peut générer un rapport d'état de l'instance. Le rapport se présente sous la forme d'une page web qui fournit plusieurs indicateurs sur l'état du système (mémoire, threads, cpu, espace disque, etc.)

Il est généralement possible d'accéder au rapport via la commande suivante:

{ "action": "admin", "params": { "action": "instance-metrics" } }

Metrics

Ewt intègre des composants micrometer.io pour générer des métriques exploitables par Prometheus et, par extension, visualisables dans Grafana.

Activation des metrics

L'activation des metrics nécessite d'indiquer quels metrics on souhaite produire et d'activer le servlet qui servira à restituer les données. Nous décrivons ci-après la marche à suivre pour réaliser ces étapes.

1. En premier lieu, il faut activer la production de metrics et indiquer quels metrics on souhaite obtenir. Pour ce faire, ajoutez la propriété enabled-metrics dans le fichier de bootstrap et y déclarer les metrics à suivre. Les metrics reconnus sont:

   • classloader : Metrics portant sur le Class Loader
   • memory : Metrics relatifs à l'état de la mémoire
   • threads : Metrics relatifs au threads
   • deadlocks : Metrics relatifs aux interblocages de threads
   • gc : Suivi d'activité du Garbage Collector
   • cpu : Surveillance d'activité du processeur
   • disk : Surveillance de l'espace disque disponible sur les disques
   • filedescriptor : Surveillance des entrées-sorties (fichiers ou sockets)
   • uptime : Informations concernant l'uptime du serveur
   • database : Informations relatives à la base de données
   • all : Mot-clé désignant tous les metrics ci-dessus

   Exemple:

   enabled-metrics = disk,memory,cpu,gc,threads
   

2. Ensuite, il faut ouvrir un nouvel endpoint pour mettre les metrics à disposition de systèmes tiers (par exemple Prometheus). Pour ce faire, éditez le fichier web.xml de Ewt et ajoutez-y les éléments suivants:

   <servlet>
       <servlet-name>EwtMetricsServlet</servlet-name>
       <servlet-class>ch.epilogic.ewt.servlets.EwtMetricsServlet</servlet-class>
   </servlet>
   
   <servlet-mapping>
       <servlet-name>EwtMetricsServlet</servlet-name>
       <url-pattern>/metrics/*</url-pattern>
   </servlet-mapping>
   

   ⚠️ Attention, les modifications ci-dessus ont pour effet d'activer le servlet, mais celui-ci n'est pas sécurisé et donc accessible en public, ce qui n'est pas recommandé. Il convient donc de sécuriser l'endpoint. Nous allons le faire en activant deux mesures :

   1. en imposant une authentification BASIC
   2. en limitant la consultation des metrics à un compte disposant de rôle spécifique.

   La suite du chapitre part du principe que l'application est sécurisée au moyen du module d'authentification intégré à Ewt. Veuillez vous reporter au chapitre traitant de ce module pour de plus amples détails.

   Toujours dans le fichier web.xml, ajouté un nouveau filtre qui sera dédié aux metrics:

   <filter>
       <filter-name>EwtAuthFilterMetrics</filter-name>
       <filter-class>org.pac4j.jee.filter.SecurityFilter</filter-class>
       <init-param>
           <param-name>authorizers</param-name>
           <param-value>isAuthenticated,ewt-metrics-role</param-value>
       </init-param>
       <init-param>
           <param-name>clients</param-name>
           <param-value>basic</param-value>
       </init-param>
   </filter>
   
   <filter-mapping>
       <filter-name>EwtAuthFilterMetrics</filter-name>
       <url-pattern>/metrics/*</url-pattern>
       <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   

   Cela a pour effet d'imposer une authentification BASIC pour consulter l'endpoint /metrics (voir ligne 10). Le compte utilisé doit en outre disposer de rôles spécifiques (définis dans l'authorizer ewt-metrics-role, voir ligne 6). Il reste donc à déclarer ce client basic et cet authorizer ewt-metrics-role.

   Pour ce faire, éditez le fichier ewtAuthConfig.xml et ajoutez les éléments suivants:

   <repository name="tomcat-file-repo" type="file">
       <file>${env:CATALINA_BASE}/conf/tomcat-users.xml</file>
   </repository>
   
   <authorizer name="ewt-metrics-role" type="role">
       <role>ewt-metrics-reader</role>
   </authorizer>
   
   <client name="basic" type="basic">
       <realm>UserDatabase</realm>
       <repository>tomcat-file-repo</repository>
       <hashAlgo>AUTO</hashAlgo>
   
       <lockOut failureCount="5" lockOutTime="300"
                cacheSize="1000" warningTime="3600"/>
   </client>
   

   Le bloc ci-dessus déclare un repository, un authorizer et un client.

   Le repository indique la source dans laquelle est déclarée le compte utilisateur qui sera utilisé pour accéder aux metrics. Dans le cas présent, nous avons opté pour le fichier tomcat-users.xml du serveur d'application Tomcat. Vous êtes bien entendu libre d'exploiter un autre repository.

   Les lignes 5 à 7 déclarent l'authorizer ewt-metrics-role. Ce dernier vérifiera que le profil utilisateur possède le rôle ewt-metrics-reader avant d'autoriser l'accès. Cela évite que n'importe quel autre utilisateur authentifié ne puisse consulter les metrics.

   Le client défini aux lignes 9 à 16 active l'authentification BASIC.

   La configuration de Ewt est terminée. Il reste à créer le compte. Pour ce faire, éditez le fichier tomcat-users.xml dans le dossier conf de Tomcat et ajoutez-y les lignes suivantes:

   <role rolename="ewt-metrics-reader"/>
   <user username="metrics-reader"
         password="{MD5}b91cd1a54781790beaa2baf741fa6789"
         roles="ewt-metrics-reader"/>
   

   Le compte metrics-reader reçoit le rôle ewt-metrics-reader qui est attendu par l'authorizer. Le mot de passe "changeit" est ici hashé en MD5 pour ne pas figurer en clair dans le fichier. On notera que le hashAlgo était défini en AUTO au niveau du client afin de pouvoir tenir compte du préfixe inclu dans le mot de passe.