For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/manage-and-operate/observability/logs-data-platform/field-naming-conventions.md.

Convention de nommage des champs

Voir en Markdown

Nommez et suffixez vos champs pour que Logs Data Platform les indexe avec le bon type de données.

Objectif

Maintenant que vous pouvez envoyer des logs, vous vous demandez peut-être comment indiquer à Logs Data Platform le type de données que vous envoyez. Il peut s'agir de dates, de nombres, de valeurs booléennes ou simplement de chaînes de texte.

Ce guide vous aidera à vous assurer que vos logs sont correctement analysés.

Prérequis

  • Aucun prérequis spécifique

En pratique

Qu'est-ce qu'un log valide pour Logs Data Platform ?

Chaque log reçu sur Logs Data Platform est transformé en un log au format GELF. Qu'est-ce que le GELF ? Une méthode standardisée d'envoi de logs au format JSON. GELF signifie Graylog Extended Log Format. L'utilisation de ce format nous offre deux avantages : il est directement compatible avec Graylog et reste suffisamment extensible pour enrichir vos logs comme vous le souhaitez.

Ce format impose quelques conventions dont le non-respect peut avoir plusieurs conséquences :

  • Logs Data Platform réécrira votre champ sous une forme incorrecte (avec un suffixe _fixit).
  • Votre log sera rejeté.

Veuillez d'abord consulter le tableau ci-dessous pour connaître les champs réservés et leur signification. Notez que certains de ces champs sont obligatoires et doivent être définis par la bibliothèque que vous utilisez pour envoyer des logs à Logs Data Platform. Reportez-vous à la documentation de la bibliothèque ou à l'un de nos excellents tutoriels pour savoir comment les envoyer.

ChampType ESDescription
versionStringVersion de la spécification GELF – « 1.1 » ; DOIT être définie par la bibliothèque cliente
hostStringLe nom de l'hôte, de la source ou de l'application ayant envoyé ce message ; DOIT être défini par la bibliothèque cliente.
short_messageStringUn message descriptif court ; DOIT être défini par la bibliothèque cliente.
full_messageStringUn message long pouvant, par exemple, contenir une backtrace ; facultatif.
timestampNumberSecondes depuis l'epoch UNIX, avec décimales optionnelles pour les millisecondes ; DEVRAIT être défini par la bibliothèque cliente. Sera défini sur l'heure actuelle par le serveur si absent.
levelNumberLe niveau équivalent aux niveaux syslog standards ; facultatif, la valeur par défaut est 1 (ALERT).
lineNumberNous considérons cette valeur comme un standard dans les messages de logs, nous la forçons donc à être un Number.
X-OVH-TOKENStringObligatoire en accès direct, n'essayez pas d'en forger d'étranges, vous seriez banni.
X-OVH-CONTENT-SIZENumberTaille en octets du log en cours.
X-OVH-TO-FREEZEStringSi renseigné, permettra de générer une archive supplémentaire contenant uniquement sa valeur (séparée par un saut de ligne).
Warning

Vous ne pouvez pas utiliser le champ source, car il est remplacé par le contenu du champ host dans Graylog.

Peut-on aller plus loin ?

Oui. Comme indiqué précédemment, vous pouvez envoyer des champs supplémentaires à condition de les préfixer par le caractère _ (underscore). Vous pouvez utiliser n'importe quel caractère valide en JSON pour votre champ, à l'exception du caractère . (point). Mais ne vous inquiétez pas, si vous le faites, nous remplacerons votre « . » par un joli underscore. Alors, comment envoyer des types spéciaux comme un nombre, une date ou un booléen ? Voici la réponse :

Suffixe (sensible à la casse)Type ESDescription
*_num, *_double, *_floatdoublevaleur flottante en double, selon la représentation Java : nombre à virgule flottante double précision 64 bits IEEE 754
*_int, *_longlongtype long signé 64 bits, dont la valeur minimale est -263 et la valeur maximale 263-1
*_datedateune date ISO 8601, avec heure optionnelle, ou millisecondes depuis l'epoch UNIX sous forme d'Integer.
*_boolbooleanValeurs attendues : "true" ou "false". ATTENTION : le GELF ne prend pas en charge les types booléens, vous devrez donc envoyer "true" ou "false" sous forme de String
*_geolocationStringUne paire de deux nombres flottants séparés par une virgule ','. Cette paire doit représenter la latitude et la longitude. Pour assurer la compatibilité avec OpenSearch Dashboards et Grafana, la valeur est également copiée dans un GeoHash : *_geolocation.geo
*_ipStringUne adresse IPv4 ou IPv6 valide. Cela vous permettra d'effectuer des recherches par plage (dst_ip:[10.0.0.0 TO 10.255.255.255]) ou par masque de sous-réseau (dst_ip:10.0.0.0\/8)
Tout le resteStringTout autre champ sera considéré comme une chaîne de caractères

Le principe est simple : ajoutez le bon suffixe à votre champ et vous pourrez envoyer les données de votre choix. À titre de référence, voici un exemple complet d'un message gelf valide avec chaque type disponible :

{
   "version":"1.1",
   "host":"my_host",
   "_some_num":87.6,
   "_some_user_id_float":123,
   "a_good_date":"2016-01-01T17:04:25.000",
   "short_message":"A short message that can save your life",
   "full_message":"all the things you want up to 32768 characters",
   "_line":18,
   "level":1,
   "_power_level_int":"9001",
   "_some_info":"info",
   "_ovh_is_wonderful_bool":"true",
   "_dst_ip":"51.38.195.65"
}

Spécifier le suffixe numérique correct est le seul moyen de générer des widgets numériques pour vos tableaux de bord. Voici un exemple de graphique que vous pouvez générer avec une valeur numérique :

Widget numérique

Notre plateforme limite l'utilisation des adresses IP comme clés de champ. Les adresses IP ont une cardinalité élevée et ne sont donc pas autorisées comme clés (elles sont bien sûr prises en charge et enrichies en tant que valeurs, comme vous pouvez le voir ci-dessus). Si vous utilisez une adresse IP comme clé, elle sera modifiée. Par exemple :

{
   "version":"1.1",
   "host":"my_host",
   "_some_user_id_float":123,
   "short_message":"A short message that can save your life",
   "192.168.1.1":"SSL Handshake Failures"
}

deviendra :

{
   "version":"1.1",
   "host":"my_host",
   "_some_user_id_float":123,
   "short_message":"A short message that can save your life",
   "invalid_ip_fields":"192.168.1.1",
   "invalid_ip_fields_values":"SSL Handshake Failures",
   "ovh_warn_ip_as_field":"One of your field name is an IP"
}

Vous disposez maintenant de tout ce qu'il faut pour envoyer vos messages dans un format valide et éviter les erreurs les plus courantes. Si vous avez la moindre question, vous pouvez toujours nous contacter sur le hub communautaire.

Happy Logging

Aller plus loin

Cette page vous a-t-elle aidé ?