Supervision

Ce chapitre présente quelques aspects supervision et monitoring du fonctionnement de la plateforme et des bots Tock.

A venir : plus de détails sur la manière de monitorer les bots, voire des exemples de dashboards pour quelques technologies de monitoring classiques. N’hésitez pas à partager les vôtres.

Lignes de vie (healthchecks)

Les API des différents composants Tock comportent différentes sondes ou lignes de vie (healthchecks) permettant de vérifier si tout fonctionne correctement. Ces lignes de vie peuvent être utilisées par les systèmes de supervision automatisés.

Sondes & chemins

Chaque WebVerticle expose 3 sondes renvoyant le code HTTP 200 si tout fonctionne.

Pour certains composants et images, le ligne de vie ne pouvant pas être exposée directement à la racine, le chemin est modifié. En particulier :

• Pour tock/admin, la ligne de vie est localisée par défaut dans /rest/admin/healthcheck
• Pour tock/nlp_api, la ligne de vie est /rest/nlp/healthcheck

Chaque chemin par défaut peut être modifiée avec une propriété dédiée (voir tableau ci-dessus).

Mode détaillé

La ligne de vie principale /healthcheck peut effectuer une inspection plus détaillée (ie. généralement vérifier la connexion à d’autres composants) si l’on active la propriété tock_detailed_healthcheck_enabled. La réponse de la ligne de vie précise alors les composants vérifiés.

Voici un exemple d’activation dans l’image Docker bot_admin :

• docker-compose.yml

    version: '3'
    services:
      admin_web:
        image: tock/bot_admin:$TAG
        environment:
        - tock_detailed_healthcheck_enabled=true
  

• dockerrun.aws.json

  {
    "AWSEBDockerrunVersion": 2,
    "containerDefinitions": [
      {
        "name": "admin_web",
        "image": "tock/bot_admin:${TAG}",
        "environment": [
          { "name": "tock_detailed_healthcheck_enabled", "value": "true" }
        ]
      }
    ]
  }
  

Exemple de réponse de la ligne de vie en mode détaillé :

  {
    "results": [
      {
        "id": "duckling_service",
        "status": "OK"
      },
      {
        "id": "tock_front_database",
        "status": "OK"
      },
      {
        "id": "tock_model_database",
        "status": "OK"
      },
      {
        "id": "tock_bot_database",
        "status": "OK"
      }
    ]
  }

Voir ci-dessous pour une synthèse des lignes de vie composant par composant.

Détails par composants

Le tableau ci-dessous détaille le chemin et les vérifications effectuées par la ligne de vie principale composant par composant, en mode normal et en mode détaillé :

Ci-dessous des exemples de réponses de différents composants en mode détaillé :

• NLP

  {
    "results": [
      {
        "id": "duckling_service",
        "status": "OK"
      },
      {
        "id": "tock_front_database",
        "status": "OK"
      },
      {
        "id": "tock_model_database",
        "status": "OK"
      }
    ]
  }
  

• Duckling

  {
    "results": [
      {
        "id": "duckling_bridge",
        "status": "OK"
      }
    ]
  }
  

• Build Worker

  {
    "results": [
      {
        "id": "tock_front_database",
        "status": "OK"
      },
      {
        "id": "tock_model_database",
        "status": "OK"
      }
    ]
  }
  

• Bot Api

  {
    "results": [
      {
        "id": "nlp_client",
        "status": "OK"
      }
    ]
  }
  

• Kotlin Compiler

  {
    "results": []
  }
  

• Bot Admin

  {
    "results": [
      {
        "id": "duckling_service",
        "status": "OK"
      },
      {
        "id": "tock_front_database",
        "status": "OK"
      },
      {
        "id": "tock_model_database",
        "status": "OK"
      },
      {
        "id": "tock_bot_database",
        "status": "OK"
      }
    ]
  }
  

Supervision des lignes de vie

Les différentes sondes et lignes de vie peuvent être utilisées pour configurer les systèmes de supervision et autres orchestrateurs de conteneurs par exemple, pour mesurer la disponibilité des services, déclencher des alertes ou remédier aux problèmes dynamiquement.

Selon les outils et technologies utilisées, la configuration des lignes de vie peut se faire de différentes manières. Voici quelques exemples à titre indicatif :

• Au niveau des répartiteurs de charge (load balancers) Cloud ou on-premise, par exemple :
  • dans la section Health checks au niveau ELB dans AWS
  • avec la directive health_check dans NGINX
  • avec l’option httpchk dans HAProxy
• Dans Docker (descripteurs Dockerfile) :
  • avec l’instruction HEALTHCHECK pour vérifier le statut du composant
  • avec ENTRYPOINT ou CMD pour attendre que le composant soit prêt au démarrage
• Dans Docker Compose (descripteurs docker-compose.yml) :
  • avec healthcheck
• Dans Kubernetes :
  • avec livenessProbe et readinessProbe
• Etc.

Journalisation (logs)

Logs applicatifs

Tock utilise SLF4J et Logback pour générer ses logs applicatifs côté serveur.

Par défaut Tock configure automatiquement ses logs et quelques propriétés permettent de modifier la configuration.

Il est possible de configurer finement les logs en fonction des besoins, notamment avec des fichiers de configuration Logback ou avec Docker Compose.

Auto-configuration

Par défaut, en l’absence de configuration spécifique, Tock configure ses logs automatiquement grâce à la classe LogbackConfigurator. Celle-ci configure Logback programmatiquement, avec le comportement suivant :

• Niveau de log général DEBUG si tock_env=dev (par défaut), ou INFO pour les autres environnements et la production
  • Exception pour les logs org.mongodb.driver toujours à INFO
  • Exception pour les logs io.netty toujours à INFO
  • Exception pour les logs okhttp3 toujours à INFO
  • Exception pour les logs io.mockk toujours à INFO
• Logs dirigés vers la console (sortie standard) par défaut, mais possibilité d’écrire dans des fichiers
  • En mode logs fichiers, écriture dans log/logFile.log, archivage d’un fichier chaque jour (log/logFile.%d{yyyy-MM-dd}.log), maximum 30 jours ou 3GB de logs conservés

Pour en savoir plus sur la configuration automatiques des logs Tock, se référer à l’implémentation LogbackConfigurator.

Des variables d’environnement permettent de configurer ces différents modes de journalisation. Elles peuvent être définies indépendamment sur chaque composant produisant des logs.

Selon le mode de déploiement utilisé, ces variables d’environnement peuvent être ajoutées soit directement en ligne de commande, soit dans un descripteur type docker-compose.yml, dockerrun.aws.json ou autre.

Voici un exemple configurant les logs de Tock Studio (admin_web) dans Docker :

• docker-compose.yml

  version: '3'
  services:
    admin_web:
      image: tock/bot_admin:$TAG
      environment:
      - tock_default_log_level=WARN
      - tock_logback_file_appender=true
  

• dockerrun.aws.json

  {
    "AWSEBDockerrunVersion": 2,
    "containerDefinitions": [
      {
        "name": "admin_web",
        "image": "tock/bot_admin:${TAG}",
        "environment": [
          { "name": "tock_default_log_level", "value": "WARN" },
          { "name": "tock_logback_file_appender", "value": "true" }
        ]
      }
    ]
  }
  

Fichiers Logback

Il est possible de configurer finement les logs Tock en configurant directement Logback. Pour cela, différentes possibilités existent, notamment des fichiers de configuration en format XML ou Groovy. Ci-dessous un exemple de configuration :

• logback.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration debug="false">
      
        <logger name="ai.tock" level="DEBUG" />
      
        <logger name="org.mongodb" level="WARN" />
      
        <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>
                    %d %-5level [%thread] %logger{1}: %msg%n
                </pattern>
            </encoder>
        </appender>
      
        <root level="INFO">
            <appender-ref ref="console" />
        </root>
      
    </configuration>
  

• logback.groovy

    import ch.qos.logback.classic.encoder.PatternLayoutEncoder
    import ch.qos.logback.core.ConsoleAppender
      
    import static ch.qos.logback.classic.Level.DEBUG
    import static ch.qos.logback.classic.Level.INFO
    import static ch.qos.logback.classic.Level.WARN
      
    appender("console", ConsoleAppender) {
      encoder(PatternLayoutEncoder) {
        pattern = "%d %-5level [%thread] %logger{1}: %msg%n"
      }
    }
    logger("ai.tock", DEBUG)
    logger("org.mongodb", WARN)
    root(INFO, ["console"])
  

Dans cet exemple :

• Le niveau de log général est INFO, avec des exceptions :
  • Exception pour les logs ai.tock toujours à DEBUG
  • Exception pour les logs org.mongodb toujours à WARN
• Les logs sont dirigés vers la console (sortie standard)

De nombreuses possibilités sont offertes pour configurer les logs grâce à ces fichiers de configuration : niveaux de logs ajustés en fonction des packages/frameworks embarqués, modification du pattern par défaut, journalisation de logs fichiers et archivage auto avec un RollingFileAppender, redirection des logs vers un serveur de base de données ou email, etc. Pour en savoir plus, se référer à la documentation Logback.

Une fois le fichier de configuration Logback créé, il faut s’assurer que celui-ci est dans la classpath du composant Tock et que Logback l’identifie comme la configuration à suivre (pour cela on utilise généralement la propriété ` -Dlogback.configurationFile` au démarrage du composant Java).

Ci-dessous un exemple complet dans Docker Compose avec :

• Un fichier logback.xml embarqué par Maven (pom.xml) dans l’image Docker

• Quelques variables d’environnement définies pour pouvoir rapidement ajuste les principaux niveaux de log directement dans Docker-Compose (sans avoir à modifier le fichier XML ni l’image Docker)’

• logback.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration debug="false">
  
        <!-- Leverage env variables with defaults, for more flexibility -->
        <variable name="tock_default_log_level" value="${tock_default_log_level:-WARN}" />
        <variable name="tock_service_log_level" value="${tock_service_log_level:-INFO}" />
        <variable name="tock_database_log_level" value="${tock_database_log_level:-WARN}" />
      
        <logger name="ai.tock" level="${tock_service_log_level}" />
        <logger name="org.mongodb" level="${tock_database_log_level}" />
      
        <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>
                    %d %-5level [%thread] %logger{1}: %msg%n
                </pattern>
            </encoder>
        </appender>
      
        <root level="${tock_default_log_level}">
            <appender-ref ref="console" />
        </root>
      
    </configuration>
  

• pom.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <artifactId>tock-docker-bot-admin</artifactId>
        <build>
            <plugins>
                <plugin>
                    <groupId>io.fabric8</groupId>
                    <artifactId>docker-maven-plugin</artifactId>
                    <configuration>
                        <images>
                            <image>
                                <name>tock/bot_admin:${project.version}</name>
                                <build>
                                    <assembly>
                                        <inline>
                                            <dependencySets>
                                                ...
                                            </dependencySets>
                                            <files>
                                                <file>
                                                    <source>logback.xml</source>
                                                    <outputDirectory>.</outputDirectory>
                                                </file>
                                            </files>
                                        </inline>
                                    </assembly>
                                    <cmd>
                                        <shell>java $JAVA_ARGS -Dlogback.configurationFile='file:///maven/logback.xml' -Dfile.encoding=UTF-8 -Dtock_nlp_model_refresh_rate=10 -cp '/maven/*' ai.tock.bot.admin.StartBotAdminServerKt</shell>
                                    </cmd>
                                    ...
  

• docker-compose.yml

    version: '3'
    services:
      admin_web:
        image: tock/bot_admin:$TAG
        environment:
        - tock_default_log_level=WARN # Default, see logback.xml
        - tock_service_log_level=INFO # Default, see logback.xml
        - tock_database_log_level=WARN # Default, see logback.xml
  

Le code complet de cet exemple appliqué à tous les modules Tock est disponible dans le dépôt tock-docker sur la branche logbackxml.

Docker Compose

Pour les utilisateurs de Docker Compose, un mécanisme permet de configurer les logs directement dans les descripteurs en YAML. Voir le dépot tock-docker pour un exemple d’implémentation de Tock dans Docker Compose.

Chaque composant applicatif peut avoir sa propre configuration :

• docker-compose.yml

  logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "5"
  

L’exemple ci-dessus configure une rotation automatique des fichiers de logs, de manière à avoir maximum 5 fichiers de logs de maximum 10 Mo chacun (le plus ancien étant supprimé pour en créer un nouveau si besoin).

Pour en savoir plus, voir la documentation Docker Compose de ce mécanisme.

Chiffrement et anonymisation

Voir la page sécurité concernant les possibilités de chiffrement et anonymisation des logs.