Cette section spécifie le format des datagrammes bruts pour les métriques, événements et checks de service acceptés par DogStatsD. Les datagrammes bruts sont encodés en UTF-8. Vous pouvez ignorer cette section si vous utilisez l’une des bibliothèques client pour DogStatsD. Toutefois, si vous souhaitez rédiger votre propre bibliothèque ou utiliser l’interface système pour envoyer des métriques, lisez attentivement ce qui suit.
Chaîne contenant uniquement des caractères alphanumériques ASCII, des underscores et des points. Consultez les règles de nommage des métriques.
<VALEUR>
Oui
Nombre entier ou valeur flottante.
<TYPE>
Oui
c pour COUNT, g pour GAUGE, ms pour TIMER, h pour HISTOGRAM, s pour SET et d pour DISTRIBUTION. Consultez la section Types de métriques pour en savoir plus.
<TAUX_ÉCHANTILLONNAGE>
Non
Valeur flottante entre 0 et 1 (inclusif). Elle ne fonctionne qu’avec des métriques COUNT, HISTOGRAM, DISTRIBUTION et TIMER. Valeur par défaut : 1 (entraîne un échantillonnage 100 % du temps).
<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>
Non
Liste de chaînes séparées par des virgules. Utilisez deux-points « : » pour les tags clé/valeur (env:prod). Consultez la section Débuter avec les tags pour découvrir comment définir des tags.
Voici quelques exemples de datagrammes :
page.views:1|c : incrémente la métrique COUNT page.views.
fuel.level:0.5|g : indique que le réservoir est à moitié vide.
song.length:240|h|@0.5 : échantillonne l’histogramme song.length comme s’il était envoyé une fois sur deux.
users.uniques:1234|s : surveille les visiteurs uniques du site.
users.online:1|c|#country:china : incrémente la métrique COUNT correspondant au nombre d’utilisateurs actifs et ajoute un tag avec le pays d’origine.
users.online:1|c|@0.5|#country:china : surveille les utilisateurs chinois actifs et utilisez un taux d’échantillonnage.
Avec l’Agent >=v6.25.0 et <v7.0.0 ou >=v7.25.0, il est possible de rassembler des valeurs. Cette fonctionnalité est proposée pour tous les types de métriques, sauf SET. Les valeurs sont séparées par le caractère :. Exemple :
Les paramètres TYPE, TAUX_ÉCHANTILLONNAGE et TAGS sont partagés entre toutes les valeurs. Les métriques obtenues sont identiques à celles générées par plusieurs messages comportant une seule valeur à la fois. Cette fonctionnalité est particulièrement utile pour les métriques HISTOGRAM, TIMING et DISTRIBUTION.
page.views:1:2:32|d : échantillonne la métrique DISTRIBUTION page.views trois fois avec les valeurs 1, 2 et 32.
song.length:240:234|h|@0.5 : échantillonne l’histogramme song.length comme s’il était envoyé une fois sur deux, à deux reprises. Un taux d’échantillonnage de 0.5 est appliqué à chaque valeur.
Les versions >=v6.35.0 && <v7.0.0 ou >=v7.35.0 de l’Agent prennent en charge un nouveau champ d’ID de conteneur. L’Agent Datadog se sert de la valeur de l’ID de conteneur pour ajouter aux métriques DogStatsD des tags de conteneur supplémentaires afin de les enrichir.
Remarque : définissez dogstatsd_origin_detection_client sur true dans votre fichier datadog.yaml ou la variable d’environnement DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT=true pour indiquer à l’Agent Datadog d’extraire le champ d’ID de conteneur et d’appliquer les tags de conteneur correspondants.
page.views:1|g|#env:dev|c:83c0a99c0a54c0c187f461c7980e9b57f3f6a8b0c918c8d93df19a9de6f3fe1d : l’Agent Datadog ajoute des tags de conteneur comme image_name et image_tag à la métrique page.views.
Consultez la documentation sur le tagging Kubernetes et Docker pour en savoir plus sur les tags de conteneur.
Texte de l’événement. Ajoutez des sauts de ligne avec \\n.
<LONGUEUR_TITRE_UTF8>
Oui
La longueur (en octets) du <TITRE> encodé en UTF-8
<LONGUEUR_TEXTE_UTF8>
Oui
La longueur (en octets) du <TEXTE> encodé en UTF-8
d:<TIMESTAMP>
Non
Ajoute un timestamp à l’événement. Valeur par défaut ; timestamp epoch Unix actuel.
h:<HOSTNAME>
Non
Ajoute un hostname à l’événement. Pas de valeur par défaut.
k:<CLÉ_AGGRÉGATION>
Non
Ajoute 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É>
Non
Défini sur normal ou low. Valeur par défaut : normal.
s:<NOM_TYPE_SOURCE>
Non
Ajoute un type de source à l’événement. Pas de valeur par défaut.
t:<TYPE_ALERTE>
Non
Défini sur error, warning, info ou success. Valeur par défaut : info.
#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>
Non
La virgule dans les tags fait partie de la chaîne de liste de tags et ne sert pas au parsing comme pour les autres paramètres. Pas de valeur par défaut.
Voici quelques exemples de datagrammes :
## Envoyer une exception
_e{21,36}:An exception occurred|Cannot parse CSV file from 10.0.0.17|t:warning|#err_type:bad_file
## Envoyer un événement avec un saut de ligne dans le texte
_e{21,42}:An exception occurred|Cannot parse JSON request:\\n{"foo: "bar"}|p:low|#err_type:bad_request
Pour Linux et d’autres systèmes d’exploitation comme Unix, utilisez Bash. Pour Windows, utilisez Powershell et Powershell-statsd (une fonction Powershell simple qui gère des bits réseau).
DogStatsD crée un message qui contient des informations à propos de votre métrique, événement ou check de service et l’envoie à un Agent installé en local sous la forme d’un collecteur. L’adresse IP de destination est 127.0.0.1 et le port du collecteur via UDP est 8125. Consultez la section DogStatsD pour en savoir plus sur la configuration de l’Agent.
Depuis n’importe quelle plateforme avec Python (sur Windows, vous pouvez utiliser l’interpréteur Python intégré à l’Agent ; il se trouve à l’emplacement %PROGRAMFILES%\Datadog\Datadog Agent\embedded\python.exe pour les versions 6.11 ou antérieures de l’Agent et à l’emplacement %PROGRAMFILES%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe pour les versions ultérieures) :
Les exemples ci-dessous calculent la taille du titre et du corps de l’événement.
Sur Linux :
$ title="Événement depuis le shell"$ text="Cet événement a été envoyé depuis Bash !"$ echo"_e{${#title},${#text}}:$title|$text|#shell,bash" >/dev/udp/localhost/8125
Sur Windows :
PS C:>$title="Événement depuis le shell"PS C:>$text="Cet événement a été envoyé depuis PowerShell !"PS C:>.\send-statsd.ps1"_e{$($title.length),$($text.Length)}:$title|$text|#shell,PowerShell"
echo -n "_sc|Connexion Redis|2|#env:dev|m:La connexion Redis a expiré après 10 s" >/dev/udp/localhost/8125
Sur Windows :
PS C:\>.\send-statsd.ps1"_sc|Redis connection|2|#env:dev|m:La connexion à Redis a expiré après 10 s"
Pour envoyer des métriques, des événements ou des checks de service sur des environnements conteneurisés, consultez la section relative à l’utilisation de DogStatsD sur Kubernetes, conjointement avec les instructions de configuration de l’APM sur Kubernetes, en fonction de votre installation. La documentation sur l’APM Docker peut également vous venir en aide.