Exploitation

Exploiter & Superviser votre plateforme


FlowerDocs s’appuie sur la librairie Logback pour la gestion des logs applicatifs.

Fichiers de log


Les paramètres suivants peuvent être définis dans les fichiers core.properties et gui.properties :

Paramètre Valeur par défaut Description
logging.file.name flowerdocs-xxx.log Chemin du fichier de log
logging.file.max-size 10MB Taille maximum d’un fichier de log à partir de laquelle la rotation est activée
logging.file.max-history non défini Nombre maximum de fichiers de log historisés
logging.level.root INFO Niveau de log par défaut

Niveaux de log


FlowerDocs et les librairies utilisées poussent des logs de plusieurs niveaux :

  • TRACE : niveau le plus fin d’information permettant d’obtenir des informations facilitant le debug (peut être activé suite à une demande du support)
  • DEBUG : niveau permettant d’obtenir des informations nécessaires au debug (peut être activé suite à une demande du support)
  • INFO : messages donnés à titre d’information
  • WARN : messages d’avertissement
  • ERROR: erreurs interceptées par l’application


Le niveau de log peut être défini par package Java en ajoutant un paramètre logging.level.<package>=<niveau> comme par exemple :

logging.level.com.flower.docs.core.tsp=DEBUG

Variables


Sur une plateforme mutualisée ou tout simplement très utilisée, il peut être nécessaire de contextualiser les logs. FlowerDocs met donc à disposition des variables pouvant être affichées dans les messages de log :

  • user : identifiant de l’utilisateur courrant
  • scope : identifiant du scope sur lequel l’utilisateur courrant est authentifié
  • request : identifiant unique de la requête émise (dans le cas d’une requête émise sur FlowerDocs GUI et propagée sur FlowerDocs Core, l’identifiant est conservé)

Pour utiliser ces variables, il suffit de modifier le paramètre logging.pattern.level de l’appender considéré : %X{variable} comme par exemple :

logging.pattern.level=%X{request} %X{scope} %X{user} %5p


FlowerDocs s’appuie sur le projet Spring Boot Actuator pour fournir des web services REST aidant à monitorer et gérer une stack FlowerDocs.

Endpoints


Les endpoints disponibles sont exposés sous le path /actuator

Endpoint Description
info Informations relatives à l’application (nom et version)
health Etat de santé de l’application
env Propriétés de l’application
caches Gestion des caches utilisés
httptrace Affiche, par défaut, les 100 dernières requêtes HTTP
loggers Configuration des logs
logfile Téléchargement du fichier de log

Ces endpoints peuvent être désactivés en ajoutant un paramètre tel que :

management.endpoints.web.exposure.exclude=httptrace,caches,env

Sécurité


Par défaut, l’ensemble des endpoints décrits requièrent une authentification basic et le rôle SYSTEM_ADMIN pour chaque application exposant ces endpoints.

La sécurisation de ces endpoints peut être désactivée en ajoutant le paramètre actuator.secured=false.


L’application Management s’appuie sur Actuator afin de faciliter la supervision d’une stack FlowerDocs. Cette application est basée sur le projet libre Spring Boot Admin.

Features

Cette application exploite les services REST exposés (cf. Actuator) pour fournir un ensemble de fonctionnalités facilitant la supervision de FlowerDocs.

Parmi la liste des fonctionnalités proposées, vous pourrez trouver entre autres :

  • Vision d’ensemble des différentes instances de la stack FlowerDocs
  • Changement des niveaux de log à la volée
  • Consultation des logs applicatifs
  • Purge de cache
  • Consultation des métriques à disposition
  • Visualisation des dernières traces HTTP
  • Notifications
  • ….

Pour plus d’informations sur les fonctionnalités et leur paramétrage, consultez la documentation.

Lancement

java -jar flower-docs-management-2.5.2.jar --system.admin.password=<password>

L’application est accessible à l’URL : http://localhost:2111/admin

Découverte via Eureka

Les différentes instances pouvant être gérées dans cette application sont découvertes via Eureka. La découverte des applications passe par l’enregistrement de chacune auprès du serveur Eureka (embarqué dans l’application Management).

Pour cela, il est nécessaire de définir, pour FlowerDocs GUI et FlowerDocs Core, la propriété eureka.client.serviceUrl.defaultZone (par défaut : http://localhost:2111/eureka).


FlowerDocs Core et FlowerDocs GUI s’enregistrent auprès d’Eureka avec les informations à leur disposition afin d’indiquer comment les contacter. Si leur contexte (path) ou leur port ont été personnalisés, il est nécessaire de l’indiquer dans leur fichier de configuration core.properties et gui.properties.

FlowerDocs Core

Information Propriété Valeur par défaut
Contexte core.context /core
Port core.port 8081

FlowerDocs GUI

Information Propriété Valeur par défaut
Contexte gui.context /gui
Port gui.port 8080

Configuration

Sécurité

Accès à l’application

Un compte utilisateur est nécessaire pour pouvoir accéder à cette application. Par défaut, le mot de passe de l’utilisateur user est indiqué dans le fichier de logs. Ce compte peut être personnalisé avec les paramètres spring.security.user.name et spring.security.user.password.

Accès à FlowerDocs

L’application nécessite l’utilisation d’un compte ayant le rôle SYSTEM_ADMIN afin d’exécuter des requêtes sur les endpoints décrits précédemment (cf. Actuator). Ce compte peut être défini grâce aux paramètres system.admin.username et system.admin.password.


Sans configuration, seul l’utilisateur système de FlowerDocs Core et de FlowerDocs GUI peut être utilisé. Il est possible de définir un utilisateur additionnel tel que :

internal.realm.users[0].id=metric-admin
internal.realm.users[0].password=<password>
internal.realm.users[0].profiles=SYSTEM_ADMIN

Cette configuration est à effectuer côté FlowerDocs Core et FlowerDocs GUI.


Les secrets définis dans cette application peuvent être chiffrés comme indiqué ici.

Notifications Email

Il est possible de configurer les notifications de changement de statut des applications FlowerDocs Core et FlowerDocs GUI.

Serveur SMTP

Pour cela, il est nécessaire de configurer le serveur SMTP à utiliser pour l’envoi d’email :

spring.mail.host=<host>
spring.mail.username=<user>
spring.mail.password=<password>
spring.mail.properties.mail.smtp.starttls.enable=true

Selon la configuration, il peut être nécessaire de forcer la confiance en l’hôte SMTP :

spring.mail.properties.mail.smtp.ssl.trust=<host>

Diffusion

Pour définir à quelles adresses seront envoyés les emails de notification, ajoutez le paramètre suivant :

spring.boot.admin.notify.mail.to=<recipient>

Métriques

La plateforme FlowerDocs expose diverses métriques permettant d’obtenir des retours quantitatifs sur l’utilisation de FlowerDocs Core. Ces métriques concernent différents aspects, de la consommation des services à l’usage de la JVM.

Les métriques sont, pour la plupart, exposées avec des tags permettant de disposer de métriques contextualisées, plus précises.

Métriques applicatives

Composants

Les métriques concernant les composants sont listées dans les tableaux ci-dessous. Elles sont exposées avec des tags permettant de les filtrer en fonction :

  • du scope concerné (scope)
  • de l’exception déclenchée (exception)
Nom Description
createDocuments Créations de documents
getDocuments Récupérations de documents
searchDocuments Recherches de documents
updateDocuments Mises à jour de documents
deleteDocuments Suppressions de documents
addFilesDocuments Ajouts de contenus à des documents
getFileDocuments Récupérations de contenus de documents
getFilesDocuments Récupérations des contenus de documents
promoteVersion Créations d’une version de documents
getVersionsVersion Récupérations des versions de documents
revertVersion Restaurations de versions de documents
Nom Description
createFolders Créations de dossiers
getFolders Récupérations de dossiers
searchFolders Recherches de dossiers
updateFolders Mises à jour de dossiers
deleteFolders Suppressions de dossiers
addChildrenFolders Ajouts de composants dans des dossiers
deleteChildrenFolders Suppressions de composants de dossiers
getStartableTasksFolders Récupérations des tâches pouvant être déclenchées depuis des cases
startTaskFolders Déclenchements de tâches depuis des cases
Nom Description
createVirtualFolders Créations de dossiers virtuels
getVirtualFolders Récupérations de dossiers virtuels
searchVirtualFolders Recherches de dossiers virtuels
updateVirtualFolders Mises à jour de dossiers virtuels
deleteVirtualFolders Suppressions de dossiers virtuels
Nom Description
createTasks Créations de tâches
getTasks Récupérations de tâches
searchTasks Recherches de tâches
updateTasks Mises à jour de tâches
deleteTasks Suppressions de tâches
answerTasks Applications de réponses à des tâches
assignTasks Assignations de tâches

OperationHandler

Les exécutions d’OperationHandlers peuvent également être monitorées à l’aide de métriques :

  • invokeSyncOperationHandler pour ceux exécutés de manière synchrone
  • processAsyncOperationHandler pour ceux exécutés de manière asynchrone

Ces métriques sont publiées avec les tags suivants :

Nom Description
ObjectType Type d’objet concerné
action Action à laquelle l’OperationHandler réagit
phase Phase d’exécution
registration Identifiant de l’abonnement
scope Identifiant du scope concerné
exception Exception provoquée ou none

Une métrique est exposée à partir du moment où l’opération a été exécutée une première fois.

Autres

Des dizaines d’autres métriques sont exposées comme les exports (ZIP ou CSV), les conversions, les authentifications… Celles-ci peuvent évoluer en fonction des versions et peuvent être parcourues dans le système d’export utilisé (voir section ci-dessous).

Métriques techniques

Les principales métriques techniques exposées par FlowerDocs Core sont listées ci-dessous.

Nom Description
process.cpu.usage Usage CPU du processus Java
process.files.max Nombre maximum de fichiers pouvant être ouverts
process.files.open Nombre de fichiers ouverts
process.start.time Heure de démarrage du processus Java
process.uptime Durée de fonctionnement du processus Java
system.cpu.usage Usage CPU du système hôte
Nom Description
jvm.buffer.count
jvm.buffer.memory.used
jvm.buffer.total.capacity
jvm.classes.loaded
jvm.classes.unloaded
jvm.gc.live.data.size
jvm.gc.max.data.size
jvm.gc.memory.allocated
jvm.gc.memory.promoted
jvm.gc.pause
jvm.memory.committed
jvm.memory.max
jvm.memory.used
jvm.threads.daemon
jvm.threads.live
jvm.threads.peak
jvm.threads.states
Nom Description
createDocuments Créations de documents

Consultation des métriques

API REST

Les métriques sont exposées sur le endpoint /actuator/metrics et comme les autres endpoints Actuator. Leur accès requiert une authentification basic d’un compte disposant du rôle SYSTEM_ADMIN.


GET /core/actuator/metrics HTTP/1.1
Authorization: Basic <basic authorization>

GET /core/actuator/metrics/getDocuments HTTP/1.1
Authorization: Basic <basic authorization>

GET /core/actuator/metrics/getDocuments?tag=scope:GEC HTTP/1.1
Authorization: Basic <basic authorization>

Ces web services peuvent être consommés depuis diverses applications de monitoring. Dans ce cas, l’utilisation d’un compte utilisateur spécifique est recommandée.

JMX

Les métriques sont exposées à travers des MBean JMX dans l’espace de nom metrics. Elles peuvent, par exemple, être consultées à l’aide d’outils fournis par un JDK comme jconsole ou jvisualvm (avec le plugin VisualVM-MBeans). Les MBeans ne supportant pas la logique de tags, les noms des métriques publiées sont concaténés avec leurs tags.


Par défaut, la technologie est accessible en local pour monitorer l’application et consulter les MBean.

Cette technologie peut également être utilisée à distance avec une configuration supplémentaire. Typiquement, en ajoutant les propriétés ci-dessous à la JVM, il est possible d’accéder de manière non-sécurisée depuis une machine distante aux MBeans.

-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.port=6001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.rmi.port=6001 


Consulter la documentation officielle pour plus d’information.

Amazon CloudWatch

Lorsque le connecteur AWS S3 est utilisé, les métriques sont automatiquement poussées dans AWS CloudWatch permettant leur consultation et la construction de tableau de bord ou d’alertes.

Afin de pouvoir pousser ces métriques, les FlowerDocs Core doivent disposer des permissions adéquates telles que définies par la stratégie ci-dessous.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "flowerdocs-cloudwatch",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricData",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:PutMetricData"
            ],
            "Resource": "*"
        }
    ]
}

Dans le cas d’une ferme de FlowerDocs Core, il peut être nécessaire d’isoler les métriques par instance. L’identifiant de l’instance FlowerDocs Core concernée peut être ajouté comme tag des métriques en ajoutant la propriété management.metrics.export.cloudwatch.tags.instanceId=true.

Pour désactiver la publication des métriques dans AWS CloudWatch, la propriété management.metrics.export.cloudwatch.enabled=false peut être ajoutée.


Ce type de métrique n’est disponible qu’avec l’utilisation du connecteur Elasticsearch.

L’historique des connexions des utilisateurs est maintenu et peut être requêté sur le endpoint /rest/metrics/profiles :

  • par profil (ou équipe) utilisateur
  • par plage de date

Ces métriques permettent d’obtenir des informations sur les utilisateurs s’étant connectés pour un profil particulier. Pour obtenir ces métriques, il est nécessaire de disposer du rôle ADMIN.

  • /rest/metrics/profiles/{profile} : Liste les connexions pour un profil donné
  • /rest/metrics/profiles/{profile}/count : Compte les connexions pour un profil donné


Cet endpoint nécessite une authentification qui doit être fournie par un jeton utilisateur :

  • via un paramètre token de l’URL
  • via une en-tête HTTP token
Paramètre Description
start Paramètre facultatif permettant d’indiquer le début de la plage de date sur laquelle la mesure doit porter.
Par défaut, ce paramètre est valorisé à 24 heures avant la fin de la plage de date. timestamp
end Paramètre facultatif permettant d’indiquer la fin de la plage de date sur laquelle la mesure doit porter.
Par défaut, ce paramètre est valorisé à l’instant présent. timestamp

Exemple :

GET /core/rest/metrics/profiles/ALL_USERS?token=<token>

Navigateurs qualifiés

Les navigateurs qualifiés sont testés et validés par Arondor pour chaque release du produit. Nous n’excluons pas qu’il puisse y avoir des anomalies sur ces navigateurs qualifiés, cependant le risque est minime et restreint à des cas particuliers ou spécifiques.


Liste des navigateurs qualifiés :

  • Chrome 88
  • Mozilla FireFox 85
  • MS Edge 88


Arondor s’engage à qualifier la dernière version de ces navigateurs au plus tard 6 mois après leur sortie.

Navigateurs supportés

Les navigateurs supportés correspondent à ceux dans lesquels l’application est réputée fonctionnelle. En effet, le rythme de release de certains navigateurs étant très important, Arondor ne peut pleinement qualifier l’ensemble des couples navigateurs/versions à chaque release. Cependant, la très grande majorité des versions intermédiaires des navigateurs permettent une utilisation normale de l’application. La remontée d’anomalies éventuelles sur ces navigateurs est couverte par le support produit standard.


Liste des navigateurs supportés :

  • Chrome 58+
  • Mozilla FireFox 53+
  • MS Edge 16+
  • Safari for iOS 11+


Les navigateurs non listés ci-dessus ne sont pas pris en charge dans le cadre du support produit standard. Le support étendu d’une version particulière d’un navigateur peut être envisagé au cas par cas.



  • L’utilisation d’un navigateur WEB conforme au standard HTML 5 et récent est préconisée pour des questions de confort utilisateur, de performance et de rendu visuel.
  • Les anomalies des navigateurs liées au non-respect des standards (HTML, JavaScript …) ne sont pas couvertes par le support produit. Une montée de version des navigateurs concernés est préconisée.

Apache HTTP Server est un des serveurs WEB les plus utilisés. Il permet facilement d’exposer des URL via HTTP(s).

Cette section décrit quelques configurations types à adapter en fonction du contexte.

Configuration minimale

<VirtualHost *:80>
	ServerName www.flowerdocs.com                                                           
	ServerAlias flowerdocs.com *.flowerdocs.com                                             
	                                                                                                                                                                                      
	<Location /gui >                                                         
	    ProxyPass http://localhost:8080/gui
	    ProxyPassReverse http://localhost:8080/gui
	</Location>
	                                                                                        
	<Location /flower-docs-arender >
	    ProxyPass http://localhost:8080/flower-docs-arender
	    ProxyPassReverse http://localhost:8080/flower-docs-arender
	</Location>
	
	<Location /core >
	    ProxyPass http://localhost:8081/core
	    ProxyPassReverse http://localhost:8081/core
	</Location>
	                                                                                        
	ErrorLog ${APACHE_LOG_DIR}/flower-error.log
	CustomLog ${APACHE_LOG_DIR}/flower-access.log combined
</VirtualHost>

Ré-écriture

Dans le cas où le chemin d’accès à FlowerDocs change, il est nécessaire de modifier certaines en-têtes HTTP pour la GUI.

Pour cela, il est nécessaire de rajouter les directives suivantes :

	<Location /ui >
	    Header edit Set-Cookie "^(.*; [p|P]ath=)(.*)" "$1/ui"                          
	    RequestHeader edit X-GWT-Module-Base ^(.*)/gui/(.*)$ $1/ui/$2
    </Location>                  

Load balancing

Apache HTTP Server permet de mettre en place facilement un load balancing applicatif.

Dans l’exemple ci-dessous, un équilibrage de type roundrobin est mis en place pour les applications FlowerDocs Core et un avec affinité de session pour les applications FlowerDocs GUI.

<VirtualHost *:80>
	Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
	
	<Proxy "balancer://core-cluster">
	    BalancerMember "http://192.168.1.50:8080/core"
	    BalancerMember "http://192.168.1.51:8080/core"
	</Proxy>
	ProxyPass        "/core" "balancer://core-cluster"
	ProxyPassReverse "/core" "balancer://core-cluster"
	
	
	<Proxy "balancer://gui-cluster">
	    BalancerMember "http://192.168.1.52:8080/gui" route=1
	    BalancerMember "http://192.168.1.53:8080/gui" route=2
	    ProxySet stickysession=ROUTEID
	</Proxy>
	ProxyPass        "/gui" "balancer://gui-cluster"
	ProxyPassReverse "/gui" "balancer://gui-cluster"

	ErrorLog ${APACHE_LOG_DIR}/flower-cluster-error.log
	CustomLog ${APACHE_LOG_DIR}/flower-cluster-access.log combined
</VirtualHost>