Journalisation du connecteur

En bref

Les journaux du connecteur sont gérés par NLog. Ils sont actifs dès la première installation, au niveau Debug, et se paramètrent depuis l'écran Configuration de l'outil de configuration : activation, niveau enregistré, nombre de fichiers conservés et dossier de destination.

Activer les journaux

Les journaux sont pilotés par la présence d'un fichier NLog.config dans le dossier d'installation du connecteur.

À la première installation, l'installeur crée ce fichier actif, au niveau Debug, et crée le dossier des journaux. Une mise à jour ne l'écrase jamais, et ne le recrée pas si vous avez désactivé les journaux.
Ensuite, l'outil de configuration s'en charge :
1. Ouvrez l'écran Configuration, section Journalisation.
2. Basculez Journaux du service. À l'activation, le fichier NLog.config est créé à partir du modèle livré avec le connecteur, et le dossier de journaux est créé s'il n'existe pas.
3. Le chemin du fichier NLog.config est affiché à côté de l'interrupteur.

Désactiver l'interrupteur supprime le fichier NLog.config : plus aucun journal n'est écrit.

Le résultat de chaque réglage (succès ou erreur) s'affiche dans le bloc Journalisation lui-même. Si l'écriture du fichier échoue, les champs reprennent l'état réel du fichier : l'interrupteur ne reste pas sur "activé" à tort.

Prise en compte immédiate

Le fichier de configuration des journaux est rechargé à chaud : un changement de niveau ou de dossier s'applique sans redémarrer le service.

Capture à venir

Dossier des journaux du connecteur - identifiant connecteur/dossier-journaux. L'image sera ajoutée lors de la prochaine campagne de captures.

Où sont les journaux

Par défaut :

C:\ProgramData\Sage\SenSaaS\logs\Log.SenSaaS.txt

Les fichiers archivés portent le nom Logs.SenSaaS.<date>.<n>.txt dans le même dossier. Le service et l'outil de configuration écrivent dans le même journal.

Vous pouvez changer ce dossier dans l'écran Configuration : saisissez le chemin (ou choisissez-le avec le bouton …) puis cliquez sur Appliquer. Les fichiers suivants y seront écrits. Le bouton en forme de dossier ouvre l'emplacement dans l'Explorateur Windows.

Droits d'écriture

Le dossier choisi doit être local et accessible en écriture par le compte sous lequel tourne le service ServeurSensaas. Sans quoi aucun journal n'est produit, sans message d'erreur visible côté API.

Rotation des fichiers

Règle	Valeur livrée
Nouvelle archive	chaque jour, ou dès que le fichier dépasse 5 Mo
Fichiers conservés	7 par défaut, réglable dans l'écran Configuration (Fichiers conservés)

Les archives les plus anciennes sont supprimées automatiquement au-delà du nombre configuré.

Niveaux de journalisation

Le champ Niveau enregistré fixe le niveau minimal écrit dans les fichiers :

Niveau	Ce qu'il enregistre
`Trace`	Tout, y compris le détail interne : très verbeux
`Debug`	Détaillé, pour un diagnostic ; niveau posé à la première installation
`Info`	Fonctionnement normal : appels reçus, opérations
`Warn`	Anomalies non bloquantes
`Error`	Erreurs
`Fatal`	Erreurs empêchant le fonctionnement

Un second réglage, Logs du serveur web, gouverne le niveau des traces d'exploitation produites par le socle web (activé : niveau Information ; désactivé : erreurs seulement). Il se règle dans la même section et s'applique au redémarrage du service.

Ce qu'on lit dans les journaux

Chaque appel reçu par le connecteur est délimité par deux lignes, au niveau Info :

une ligne d'arrivée (DÉBUT appel) : identifiant de corrélation, méthode HTTP, chemin et requête, adresse IP du client ;
une ligne de sortie (FIN appel) : identifiant de corrélation, code HTTP, durée en millisecondes et utilisateur. Elle est toujours écrite, même en cas d'erreur.

L'identifiant de corrélation relie les lignes d'un même appel entre elles ; il est aussi renvoyé au client dans l'en-tête X-Correlation-Id et dans le corps des erreurs. C'est la première information à relever quand vous signalez un incident.

Deux préfixes de routes ne sont pas journalisés : ceux du contrat de l'API (/swagger) et de l'outil de test (/test). La chaîne de requête est tronquée à 200 caractères.

Messages utiles

Message ou situation	Sens
"Licence vérifiée en ligne."	Mode nominal de la licence
"Licence rejouée depuis le cache signé (hors-ligne, dans la grâce)."	Portail injoignable, cache signé utilisé
"Vérification de licence refusée (HTTP , code `) : …"`	Refus du portail ; le code d'erreur n'apparaît que dans le journal
"Jeton serveur de licence reçu et enregistré (livraison poussée)."	Jeton serveur livré par le portail
"Synchronisation refusée par le portail : HTTP , code `: …"`	Refus de synchronisation ; le code se lit dans la table des codes du portail
Avertissement sur une requête SQL brute refusée	Utilisateur, dossier, motif et requête reçue, pour corriger la requête
Avertissement de colonnes inconnues retirées d'une requête `/v2/query`	Colonnes absentes d'un dossier, signalées aussi au client (`QUERY.COLUMN_IGNORED`)
Avertissement de clés du serveur d'identité injoignables	Les jetons de connexion par la webapp sont refusés tant que la clé ne peut pas être obtenue

Passer en mode détaillé pour un diagnostic

Écran Configuration › Journalisation.
Vérifiez que Journaux du service est actif.
Passez Niveau enregistré à Debug, ou à Trace si le support vous le demande.
Reproduisez le problème.
Récupérez le fichier Log.SenSaaS.txt (et l'archive du jour si besoin).
Remettez le niveau voulu (Info pour un fonctionnement courant) une fois le diagnostic terminé.

Le niveau Trace n'est pas un réglage permanent

Il produit un volume de journaux très important et écrit sur le disque des contenus sensibles : au niveau Trace, le corps complet des synchronisations avec le portail (adresses email des utilisateurs et, pendant l'assistant, le jeton d'association) et le SQL réécrit des requêtes brutes. Réservez-le à un diagnostic ponctuel, activé sciemment.

Des journaux à traiter comme confidentiels

Même hors Trace, le journal enregistre au niveau Info l'appel d'adhésion au réseau EasyConnect avec la clé d'authentification si une clé a été saisie. Transmettez les journaux par un canal privé, jamais dans un ticket ouvert.

Autres journaux utiles

Journal	Emplacement	Contenu
Installation et mise à jour	`SenSaaS.Updater.log`, dans le dossier d'installation	Déroulé de l'installeur : prérequis .NET, copie des fichiers, EasyConnect, modèles, création du service
Observateur d'événements Windows	Journaux Windows › Système et Application	Échecs de démarrage du service

Questions fréquentes

Les journaux sont activés mais aucun fichier n'apparaît.

Le fichier n'est créé qu'à la première écriture. Vérifiez le niveau enregistré, puis les droits d'écriture du compte de service sur le dossier choisi.

Aucun journal sur une installation mise à jour.

Une mise à jour ne recrée jamais NLog.config : si les journaux avaient été désactivés, ils le restent. Réactivez Journaux du service dans l'écran Configuration.

Puis-je envoyer les journaux ailleurs que dans un fichier ?

Le fichier NLog.config est un fichier NLog standard ; le modèle livré contient des exemples de destinations supplémentaires. L'outil de configuration ne pilote que la destination fichier et ne modifie pas le reste du fichier.