Appendix A. Implementer Guidelines (Directives pour les implémenteurs)

A.1. Relationship with BSD Syslog (Relation avec BSD Syslog)

Ce document est un successeur du [RFC3164]. Le format du message a été changé du format BSD syslog pour utiliser des données structurées et un format de message clairement défini. Cette annexe décrit certaines des différences et préoccupations de rétrocompatibilité.

La différence la plus évidente est que [RFC3164] n'a pas formalisé le format de message syslog. Alors que [RFC3164] décrivait un format de paquet, il était basé sur des observations d'implémentations existantes. Au fil du temps, les implémentations ont évolué dans différentes directions. Cette spécification est écrite de sorte que les périphériques suivant ce format puissent interopérer correctement. Dans le même temps, le format a été conçu pour coexister avec les expéditeurs et destinataires BSD syslog plus anciens.

Le format HEADER décrit dans la section 6.2 commence par le champ PRI, suivi du champ VERSION. Le champ PRI est formaté de la même manière que dans [RFC3164]. Le champ VERSION permet aux nouvelles implémentations d'identifier les messages formatés selon cette spécification. Il fournit également une certaine rétrocompatibilité limitée avec [RFC3164]. Un destinataire implémentant [RFC3164] interpréterait probablement le caractère VERSION comme le premier caractère du champ HOSTNAME. Cela peut ou non être le comportement souhaité.

Le champ TIMESTAMP peut utiliser la NILVALUE. Cela diffère de [RFC3164], qui spécifiait qu'un TIMESTAMP manquant devait être déduit du temps de réception. Cependant, une NILVALUE dans le champ TIMESTAMP indique explicitement que le temps n'est pas disponible.

Les messages conformes à cette spécification peuvent être distingués des messages conformes à [RFC3164] car ces derniers ne contiennent pas de champ VERSION immédiatement après le champ PRI.

A.2. Message Length (Longueur du message)

Il y a eu une confusion significative concernant la longueur maximale de message pour les messages syslog. [RFC3164] stipule que "La longueur totale du paquet DOIT être de 1024 octets ou moins." Cela a conduit à des problèmes d'interopérabilité car de nombreuses implémentations acceptent des messages plus longs, et certaines implémentations qui essaient d'honorer la longueur de 1024 octets ont dû tronquer les messages.

Ce document n'impose pas de longueur de message maximale. Au lieu de cela, le mappage de transport définit la longueur de message maximale minimale prise en charge. Un transport receiver est libre d'accepter des messages plus longs. Cela a conduit à la définition d'une longueur minimale requise de 480 octets. Tous les transport receivers DOIVENT pouvoir accepter des messages de cette longueur. Les transport receivers DEVRAIENT pouvoir accepter des messages d'une longueur allant jusqu'à 2048 octets inclus. Si des messages plus longs doivent être pris en charge, le mappage de transport peut définir des longueurs maximales minimales plus longues.

A.3. Severity Values (Valeurs de sévérité)

Les valeurs de sévérité sont tirées de [RFC3164] et des implémentations BSD syslog. Il n'y a pas de mappage standard ou universellement accepté des valeurs de sévérité à l'importance réelle. Les significations décrites dans le tableau 2 sont des directives. Chaque implémentation peut avoir sa propre définition pour chaque niveau de sévérité.

En pratique, les sévérités sont souvent utilisées pour le filtrage. Les opérateurs peuvent souhaiter recevoir uniquement les messages de niveaux de sévérité élevés, ou ils peuvent souhaiter stocker uniquement les messages de certaines sévérités. Pour cette raison, les originators de messages DEVRAIENT sélectionner des niveaux de sévérité appropriés qui ont un sens logique dans le contexte de leur opération.

A.4. TIME-SECFRAC Precision (Précision TIME-SECFRAC)

Ce document spécifie que le champ TIME-SECFRAC peut avoir jusqu'à 6 chiffres. Cela fournit une précision de la microseconde. Cependant, il n'est pas nécessaire que tous les chiffres soient significatifs. Un originator peut fournir seulement 3 chiffres (précision de la milliseconde) si c'est la limite de sa résolution d'horloge. Alternativement, un originator pourrait fournir les 6 chiffres mais ne garantir que les 3 premiers sont précis.

Le destinataire d'un message ne peut pas déterminer la précision de l'horloge à partir du champ TIME-SECFRAC seul. Si les informations de précision de l'horloge sont importantes, l'originator DEVRAIT inclure le SD-ID timeQuality (section 7.1) pour fournir des informations supplémentaires sur son horloge.

A.5. Case Convention for Names (Convention de casse pour les noms)

SD-ID, PARAM-NAME, APP-NAME et MSGID sont sensibles à la casse. Cela signifie que "eventId" est différent de "eventID" et "EventID". Cela a été décidé pour fournir une flexibilité maximale. Cependant, cela signifie également qu'il faut faire attention lors de la définition des SD-ID et PARAM-NAME.

Il n'y a pas de convention de casse requise pour les SD-ID et PARAM-NAME. Cependant, à titre de directive, les noms en camelCase sont suggérés (par exemple, "eventSource", "sequenceId"). Cela est cohérent avec les conventions communes utilisées dans de nombreux langages de programmation.

A.6. Syslog Applications Without Knowledge of Time (Applications syslog sans connaissance du temps)

Certaines applications syslog peuvent ne pas être en mesure de déterminer l'heure actuelle. Cela peut être parce que le périphérique n'a pas de source de temps ou parce que la source de temps est temporairement indisponible. Dans de tels cas, la NILVALUE ("-") DOIT être utilisée pour le champ TIMESTAMP.

Lorsqu'un relay reçoit un message avec une NILVALUE dans le champ TIMESTAMP, il PEUT insérer son propre horodatage. Cela permettrait au relay d'ajouter des informations de temps aux messages qui n'en ont pas. Cependant, le relay NE DEVRAIT PAS le faire si cela modifierait la signification du message. Par exemple, si le message décrit un événement qui s'est produit à un moment spécifique, remplacer la NILVALUE par l'heure actuelle du relay serait inapproprié.

A.7. Notes on the timeQuality SD-ID (Notes sur le SD-ID timeQuality)

Le SD-ID timeQuality (section 7.1) est conçu pour permettre à un originator de fournir des informations sur la qualité de son horloge. Ces informations peuvent être utiles pour l'analyse des journaux.

Par exemple, si un périphérique réseau perd la connectivité à son serveur NTP, il pourrait définir isSynced="0" pour indiquer que son horloge n'est plus synchronisée. Si l'horloge du périphérique dérive de manière significative pendant qu'elle n'est pas synchronisée, tous les horodatages qu'elle produit peuvent être inexacts. Le SD-ID timeQuality permet au périphérique d'indiquer cette situation.

Le paramètre syncAccuracy est particulièrement utile pour indiquer la précision attendue de l'horodatage. Cela permet aux outils d'analyse de journaux de déterminer si les informations de temps sont suffisamment précises à des fins de corrélation.

A.8. UTF-8 Encoding and the BOM (Encodage UTF-8 et le BOM)

Le champ MSG peut être encodé en UTF-8. S'il est encodé en UTF-8, il DOIT commencer par la marque d'ordre d'octet UTF-8 (BOM), qui est la séquence d'octets %xEF.BB.BF.

Le BOM est utilisé comme indicateur que le MSG est encodé en UTF-8. Si le BOM est présent, le destinataire DEVRAIT interpréter le MSG comme étant en UTF-8. Si le BOM n'est pas présent, l'encodage n'est pas spécifié par ce document.

Il est important de noter que le BOM n'est utilisé qu'au début du champ MSG. Il NE DOIT PAS apparaître ailleurs dans le message. Si le BOM apparaît ailleurs, il DEVRAIT être traité comme des données, et non comme un BOM.