Datagramme et interface système

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

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.

Protocole DogStatsD v1.1

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 :

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

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.

Exemples de datagrammes

• 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.

Protocole DogStatsD v1.2

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.

L’ID de conteneur commence par c:. Exemple :

<NOM_MÉTRIQUE>:<VALEUR>|<TYPE>|#<CLÉ_TAG_1>:<VALEUR_TAG_1>,<TAG_2>|c:<ID_CONTENEUR>

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.

Exemples de datagrammes

• 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.

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

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

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

Voici un exemple de datagramme :

# Envoyer un statut CRITICAL pour une connexion à distance
_sc|Redis connection|2|#env:dev|m:La connexion à Redis a expiré après 10 s

Voici le format d’envoi de métriques :

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

Les exemples ci-dessous envoient des points de données pour une métrique gauge custom_metric avec le tag shell.

Sur Linux :

echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125

echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125

echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

Sur Windows :

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

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) :

Python 2

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

Python 3

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

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>.

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"

Voici le format d’envoi des checks de service :

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

Sur Linux :

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"