Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Datagramme et interface système

Cette section spécifie le format brut des datagrammes pour chaque type de données accepté par DogStatsD. Vous pouvez l’ignorer si vous utilisez l’une des bibliothèques client de DogStatsD. Toutefois, si vous souhaitez rédiger votre propre bibliothèque ou utiliser l’interface système pour envoyer des métriques ou des événements, lisez attentivement cette section.

Format des datagrammes

Métriques

<NOM_MÉTRIQUE>:<VALEUR>|<TYPE>|@<TAUX_ÉCHANTILLONNAGE>|#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>

ParamètreObligatoireDescription
<NOM_MÉTRIQUE>OuiUne chaîne sans deux-points, barres ni « @ ». Consultez la stratégie de nommage des métriques.
<VALEUR>OuiUn nombre entier ou une valeur flottante.
<TYPE>Ouic pour counter, g pour gauge, ms pour timer, h pour histogram, s pour set.
<TAUX_ÉCHANTILLONNAGE>NonUne valeur flottante entre 0 et 1 (inclusif). Elle ne fonctionne qu’avec des métriques counter, histogram et timer. Valeur par défaut : 1 (entraîne un échantillonnage 100 % du temps).
<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>NonUne liste de tags séparés par des virgules. Utilisez deux-points pour les tags clé/valeur, p. ex. env:prod. La clé device est réservée : Datadog supprime un tag ajouté par un utilisateur comme device:foobar.

Voici quelques exemples de datagrammes :

## Incrémenter le counter page.views
page.views:1|c

## Enregistrer le fait que le réservoir de carburant est à moitié vide
fuel.level:0.5|g

## Échantillonner l'histogramme de longueur de morceau une fois sur deux
song.length:240|h|@0.5

## Suivre un visiteur unique du site
users.uniques:1234|s

## Incrémenter le counter d'utilisateurs actifs tagués par pays d'origine
users.online:1|c|#country:china

## Suivre les utilisateurs chinois et utiliser un taux d'échantillonnage
users.online:1|c|@0.5|#country:china

Événements

_e{<TITRE>.length,<TEXTE>.length}:<TITRE>|<TEXTE>|d:<TIMESTAMP>|h:<HOSTNAME>|p:<PRIORITÉ>|t:<TYPE_ALERTE>|#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>

ParamètreObligatoireDescription
_eOuiLe datagramme doit commencer par _e.
<TITRE>OuiTitre de l’événement.
<TEXTE>OuiTexte de l’événement. Ajoutez des sauts de ligne en échappant une barre oblique (\\n).
d:<TIMESTAMP>NonAjoute un timestamp à l’événement. Valeur par défaut ; timestamp epoch Unix actuel.
h:<HOSTNAME>NonAjoute un hostname à l’événement. Pas de valeur par défaut.
k:aggregation_keyNonAjoute une clé d’agrégation afin de regrouper les événements qui possèdent la même clé. Pas de valeur par défaut.
p:<PRIORITÉ>NonDéfini sur « normal » ou « low ». Valeur par défaut : « normal ».
s:source_type_nameNonAjoute un type de source à l’événement. Pas de valeur par défaut.
t:<TYPE_ALERTE>NonDéfini sur « error », « warning », « info » ou « success ». Valeur par défaut : « info ».
#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>NonLa virgule dans les tags fait partie de la chaîne de liste de tags et ne fait pas l’objet d’un parsing comme pour les autres paramètres. Pas de valeur par défaut.

Voici quelques exemples de datagrammes :

## Envoyer une exception
_e{21,36}:Une exception s'est produite|Impossible d'analyser le fichier CSV depuis 10.0.0.17|t:warning|#err_type:bad_file

## Envoyer un événement avec une nouvelle ligne dans le texte
_e{21,42}:Une exception s'est produite|Impossible d'analyser la requête JSON :\\n{"foo: "bar"}|p:low|#err_type:bad_request

Checks de service

_sc|<NOM>|<STATUT>|d:<TIMESTAMP>|h:<HOSTNAME>|#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>|m:<MESSAGE_CHECK_SERVICE>

ParamètreObligatoireDescription
_scOuiLe datagramme doit commencer par _sc.
<NOM>OuiNom du check de service.
<STATUT>OuiNombre entier correspondant à l’état du check (OK = 0, WARNING = 1, CRITICAL = 2, UNKNOWN = 3).
d:<TIMESTAMP>NonAjoute un timestamp au check. Valeur par défaut ; timestamp epoch Unix actuel.
h:<HOSTNAME>NonAjoute un hostname à l’événement. Pas de valeur par défaut.
#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>NonLa virgule dans les tags fait partie de la chaîne de liste de tags et ne fait pas l’objet d’un parsing comme pour les autres paramètres. Pas de valeur par défaut.
m:<MESSAGE_CHECK_SERVICE>NonAjoute un message décrivant l’état actuel du check de service. Ce champ DOIT être placé en dernier parmi les champs des métadonnées. Pas de valeur par défaut.

Voici un exemple de datagramme :

# Envoyer un statut CRITICAL pour une connexion à distance
_sc|Connexion Redis|2|#redis_instance:10.0.0.16:6379|m:La connexion Redis a expiré après 10 s

Envoyer des statistiques et des événements à l’aide de DogStatsD et de l’interface système

Pour Linux et d’autres systèmes d’exploitation comme Unix, utilisez Bash. Pour Windows, Powershell et powershell-statsd (une fonction Powershell simple qui gère des bits réseau) sont requis.

DogStatsD repose sur le concept suivant : créer un message qui contient des informations sur votre métrique ou événement, et l’envoyer à un collecteur via UDP sur le port 8125. En savoir plus sur le format du message.

Envoyer des métriques

Le format d’envoi des métriques est le suivant : <NOM_MÉTRIQUE>:<VALEUR>|<TYPE>|@<TAUX_ÉCHANTILLONNAGE>|#<CLÉ_TAG_1>:<VALEUR_TAG_1><TAG_2>. Imaginons que nous envoyons des points de données pour une métrique de type gauge du nom de custom_metric avec le tag shell. Si vous utilisez un Agent installé localement en tant que collecteur, l’adresse IP de la destination est 127.0.0.1.

Options sur Linux :

vagrant@vagrant-ubuntu-14-04:~$ echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125
vagrant@vagrant-ubuntu-14-04:~$ echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125
vagrant@vagrant-ubuntu-14-04:~$ echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

Options sur Windows :

PS C:\vagrant> .\send-statsd.ps1 "custom_metric:123|g|#shell"
PS C:\vagrant>

Depuis n’importe quelle plateforme avec Python (sur Windows, l’interpréteur Python intégré à l’Agent peut être utilisé ; il est situé à l’emplacement C:\Program Files\Datadog\Datadog Agent\embedded\python.exe) :

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

Pour envoyer des métriques sur des environnements conteneurisés, consultez l’article relatif à l’utilisation de DogStatsD sur Kubernetes, conjointement avec les instructions de configuration de l’APM sur Kubernetes avec DaemonSets ou Helm, en fonction de votre installation. La documentation sur l’APM Docker peut également vous venir en aide.

Envoyer des événements

Voici le format d’envoi d’événements :

_e{<TITRE>.length,<TEXTE>.length}:<TITRE>|<TEXTE>|d:<ÉVÉNEMENT_DATE>|h:<HOSTNAME>|p:<PRIORITÉ>|t:<TYPE_ALERTE>|#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>.

Calculez ici la taille du titre et du corps de l’événement :

Sur Linux :

vagrant@vagrant-ubuntu-14-04:~$ title="Événement de l'interface système"
vagrant@vagrant-ubuntu-14-04:~$ text="Ceci a été envoyé par Bash !"
vagrant@vagrant-ubuntu-14-04:~$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

Sur Windows :

PS C:\vagrant> $title = "Événement de l'interface système"
PS C:\vagrant> $text = "Ceci a été envoyé par Powershell !"
PS C:\vagrant> .\send-statsd.ps1 "_e{$($title.length),$($text.Length)}:$title|$text|#shell,powershell"

Pour aller plus loin