DogStatsD

Docs > Développeurs > DogStatsD

La meilleure façon d’intégrer vos métriques custom d’application à Datadog consiste à les envoyer à DogStatsD, un service d’agrégation de métriques fourni avec l’Agent Datadog. DogStatsD exécute le protocole StatsD en apportant quelques extensions spécifiques à Datadog :

Type de métrique histogram
Checks de service
Événements
Tags

Vous pouvez utiliser n’importe quel client StatsD conforme avec DogStatsD et l’Agent. Cependant, les extensions Datadog ne sont pas incluses.

Remarque : DogStatsD n’implémente PAS les timers de StatsD en tant que type de métrique native (bien qu’il les prend en charge par l’intermédiaire des histogrammes).

DogStatsD est disponible sur Docker Hub et GCR :

Docker Hub	GCR
hub.docker.com/r/datadog/dogstatsd	gcr.io/datadoghq/dogstatsd

Docker Hub est soumis à des limites de pull d'images. Si vous n'êtes pas client Docker Hub, Datadog vous recommande de mettre à jour la configuration de votre Agent Datadog et de votre Agent de cluster afin de récupérer les images à partir de GCR ou ECR. Pour connaître la marche à suivre, consultez la section Modifier votre registre de conteneurs.

Fonctionnement

DogStatsD accepte les métriques custom, les événements et les checks de service par le biais du protocole UDP. Il les agrège et les transmet régulièrement à Datadog.

Grâce au protocole UDP, votre application peut envoyer des métriques à DogStatsD et reprendre sa tâche sans attendre de réponse. Si jamais DogStatsD devient indisponible, votre application continue à fonctionner sans interruption.

Lorsque DogStatsD reçoit des données, il agrège de nombreux points de données pour chaque métrique au sein d’un seul point de données, sur une période correspondant à l’intervalle de transmission. Par défaut, l’intervalle de transmission de DogStatsD dure 10 secondes.

Implémentation

DogStatsD est activé par défaut sur le port UDP 8125 à partir de la version 6 de l’Agent. Si vous ne devez pas changer ce port, passez directement à la configuration de DogStatsD dans votre code.

Agent

Par défaut, DogStatsD effectue une écoute sur le port UDP 8125. Pour modifier ce réglage, configurez l’option dogstatsd_port dans le fichier de configuration principal de l’Agent et redémarrez l’Agent. Vous pouvez également configurer DogStatsD afin d’utiliser un socket de domaine Unix. Pour activer un port UDP personnalisé pour le serveur DogStatsD de l’Agent :

Modifiez votre fichier datadog.yaml en supprimant la mise en commentaire des paramètres use_dogstatsd et dogstatsd_port :

## @param use_dogstatsd - boolean - optional - default: true
## Set this option to false to disable the Agent DogStatsD server.
#
use_dogstatsd: true

## @param dogstatsd_port - integer - optional - default: 8125
## Override the Agent DogStatsD port.
## Note: Make sure your client is sending to the same UDP port.
#
dogstatsd_port: 8125

Redémarrez votre Agent.

Par défaut, DogStatsD effectue une écoute sur le port UDP 8125. Vous devez donc associer ce port au port de votre host lorsque l’Agent est exécuté dans un conteneur. Si vos métriques StatsD proviennent d’une source en dehors de localhost, vous devez définir DD_DOGSTATSD_NON_LOCAL_TRAFFIC sur true pour autoriser la collecte de métriques. Pour exécuter l’Agent avec le serveur DogStatsd activé, exécutez la commande suivante :

docker run -d --cgroupns host \
              --pid host \
              -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" \
              -p 8125:8125/udp \
              gcr.io/datadoghq/agent:latest

Si vous devez modifier le port utilisé pour recueillir des métriques StatsD, utilisez la variable d’environnement DD_DOGSTATSD_PORT="<NOUVEAU_PORT_DOGSTATSD>. Vous pouvez également configurer DogStatsD de façon à utiliser un socket de domaine Unix :

Détection de l’origine via UDP

La détection de l’origine est prise en charge à partir de l’Agent 6.10.0. Elle permet à DogStatsD de détecter la provenance des métriques de conteneur et de taguer automatiquement les métriques. Lorsque ce mode est activé, toutes les métriques transmises via UDP reçoivent les mêmes tags de pod que les métriques Autodiscovery.

La détection de l’origine dans les environnements non basés sur Kubernetes fait appel à une extension du protocole DogStatsD dans le Datagramme et interface système. Pour activer cette fonctionnalité dans l’Agent, définissez la variable d’environnement DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT sur true.

Remarque : la détection de l’origine n’est pas prise en charge pour les environnements Fargate.

Pour commencer à recueillir vos métriques StatsD, vous devez lier le port DogStatsD au port d’un host. Vous pouvez également configurer DogStatsD de façon à utiliser un socket de domaine Unix.

Ajoutez un hostPort à votre manifeste datadog-agent.yaml :
```
ports:
    - containerPort: 8125
      hostPort: 8125
      name: dogstatsdport
      protocol: UDP
```
Vos applications peuvent ainsi envoyer des métriques par l’intermédiaire de DogStatsD sur le port 8125 sur les nœuds sur lesquels elles s’exécutent.
Remarque : la fonction hostPort requiert un fournisseur réseau qui respecte la spécification CNI, tel que Calico, Canal ou Flannel. Pour obtenir davantage d’informations, et notamment pour trouver une solution pour les fournisseurs réseau ne respectant pas la spécification CNI, consultez la section Services HostPort non fonctionnels de la documentation Kubernetes (en anglais).
Remarque : pour un déploiement d’Operator, configurez le port du host à l’aide de agent.config.hostPort.
Activez le trafic DogStatsD non local pour permettre la collecte de données StatsD en définissant DD_DOGSTATSD_NON_LOCAL_TRAFFIC sur true dans votre manifeste datadog-agent.yaml :
```
- name: DD_DOGSTATSD_NON_LOCAL_TRAFFIC
  value: 'true'
```
Cela permet de recueillir les données StatsD depuis des conteneurs autres que celui qui exécute l’Agent.
Appliquez la modification :
```
kubectl apply -f datadog-agent.yaml
```

Attention : le paramètre hostPort ouvre un port sur votre host. Assurez-vous que votre pare-feu accorder uniquement un accès à vos applications ou à d’autres sources de confiance. Si votre plug-in réseau ne prend pas en charge hostPorts, vous devez ajouter hostNetwork: true aux spécifications de pod de votre Agent afin de partager l’espace de nommage réseau de votre host avec l’Agent Datadog. Cela signifie également que tous les ports ouverts sur le conteneur sont également ouverts sur le host. Si un port est utilisé sur le host et dans votre conteneur, ces derniers peuvent entrer en conflit (puisqu’ils partagent le même espace de nommage réseau), empêchant ainsi le pod de démarrer. Cela n’est pas possible avec certaines installations Kubernetes.

Envoyer des métriques StatsD à l’Agent

Votre application doit pouvoir déterminer de façon fiable l’adresse IP de son host. La version 1.7 de Kubernetes vous permet d’y parvenir facilement, en élargissant l’ensemble d’attributs que vous pouvez transmettre à vos pods sous la forme de variables d’environnement. Dans cette version, et les versions ultérieures, vous pouvez transmettre l’IP du host à n’importe quel pod en ajoutant une variable d’environnement au PodSpec. Voici un exemple de manifeste d’application :

env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP

Grâce à ce manifeste, un pod exécutant votre application peut transmettre des métriques DogStatsD avec le port 8125 sur $DD_AGENT_HOST.

Remarque : Datadog vous conseille d’utiliser le tagging de service unifié lorsque vous assignez des attributs. Le tagging de service unifié permet de lier les données de télémétrie Datadog entre elles via trois tags standards : env, service et version. Pour découvrir comment unifier votre environnement, consultez la section Tagging de service unifié.

Détection de l’origine via UDP

La détection de l’origine est prise en charge par l’Agent 6.10.0 et les versions ultérieures. Elle permet à DogStatsD de détecter la provenance des métriques de conteneur et de taguer automatiquement les métriques. Lorsque ce mode est activé, toutes les métriques transmises via UDP reçoivent les mêmes tags de pod que les métriques Autodiscovery.

Remarques :

La détection de l’origine via UDP utilise l’ID de pod en tant qu’ID d’entité. Les tags au niveau des conteneurs ne sont donc pas émis.
Comme alternative à UDP, vous pouvez utiliser des sockets de domaine Unix.

Pour activer la détection de l’origine via UDP, ajoutez les lignes suivantes au manifeste de votre application :

env:
    - name: DD_ENTITY_ID
      valueFrom:
          fieldRef:
              fieldPath: metadata.uid

Pour définir la cardinalité des tags pour les métriques recueillies avec la détection de l’origine, définissez la variable d’environnement DD_DOGSTATSD_TAG_CARDINALITY sur low (valeur par défaut) ou orchestrator.

Remarque :; pour UDP, les tags pod_name ne sont pas ajoutés par défaut afin d’éviter la création d’un nombre excessif de métriques custom.

Pour recueillir des métriques custom via DogStatsD avec Helm :

Modifiez votre fichier datadog-values.yaml pour activer DogStatsD :
```
  dogstatsd:
    port: 8125
    useHostPort: true
    nonLocalTraffic: true
```
Remarque : la fonction hostPort requiert un fournisseur réseau qui respecte la spécification CNI, tel que Calico, Canal ou Flannel. Pour obtenir davantage d’informations, et notamment pour trouver une solution pour les fournisseurs réseau ne respectant pas la spécification CNI, consultez la section Services HostPort non fonctionnels de la documentation Kubernetes (en anglais).
Attention : le paramètre hostPort ouvre un port sur votre host. Assurez-vous que votre pare-feu accorder uniquement un accès à vos applications ou à d’autres sources de confiance. Si votre plug-in réseau ne prend pas en charge hostPorts, vous devez ajouter hostNetwork: true aux spécifications de pod de votre Agent afin de partager l’espace de nommage réseau de votre host avec l’Agent Datadog. Cela signifie également que tous les ports ouverts sur le conteneur sont également ouverts sur le host. Si un port est utilisé sur le host et dans votre conteneur, ces derniers peuvent entrer en conflit (puisqu’ils partagent le même espace de nommage réseau), empêchant ainsi le pod de démarrer. Cela n’est pas possible avec certaines installations Kubernetes.

Mettez à jour la configuration de votre Agent :

helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog

Modifiez les pods de votre application : votre application doit pouvoir déterminer de façon fiable l’adresse IP de son host. La version 1.7 de Kubernetes vous permet d’y parvenir facilement, en élargissant l’ensemble d’attributs que vous pouvez transmettre à vos pods sous la forme de variables d’environnement. Dans cette version, et les versions ultérieures, vous pouvez transmettre l’IP du host à n’importe quel pod en ajoutant une variable d’environnement au PodSpec. Voici un exemple de manifeste d’application :
```
env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP
```
Grâce à ce manifeste, un pod exécutant votre application peut transmettre des métriques DogStatsD avec le port 8125 sur $DD_AGENT_HOST.

Code

Installer le client DogStatsD

Il existe des bibliothèques client Datadog/DogStatsD officielles pour les langages suivants. Vous pouvez utiliser n’importe quel client StatsD conforme avec DogStatsD et l’Agent. Sachez cependant que les fonctionnalités mentionnées ci-dessus ne seront pas incluses :

pip install datadog

Instancier le client DogStatsD

Une fois votre client DogStatsD installé, instanciez-le dans votre code :

from datadog import initialize, statsd

options = {
    'statsd_host':'127.0.0.1',
    'statsd_port':8125
}

initialize(**options)
Par défaut, les instances de client DogStatsD Python (y compris l'instance globale statsd) ne peuvent pas être partagées entre des processus, mais sont thread-safe. De ce fait, le processus parent et chaque processus enfant doivent créer leurs propres instances du client, ou la mise en mémoire tampon doit être explicitement désactivée en définissant disable_buffering sur True. Consultez la documentation sur datadog.dogstatsd pour en savoir plus.

Paramètres d’instanciation du client

Remarque : Datadog vous conseille d’utiliser le tagging de service unifié lorsque vous assignez des tags. Le tagging de service unifié permet de lier les données de télémétrie Datadog entre elles via trois tags standards : env, service et version. Pour découvrir comment unifier votre environnement, consultez la section Tagging de service unifié.

En plus de la configuration DogStatsD obligatoire (url et port), vous pouvez configurer les paramètres facultatifs suivants pour votre client DogStatsD :

Paramètre	Type	Valeur par défaut	Description
`statsd_host`	Chaîne	`localhost`	Le host de votre serveur DogStatsD.
`statsd_port`	Nombre entier	`8125`	Le port de votre serveur DogStatsD.
`statsd_socket_path`	Chaîne	`null`	Le chemin vers le socket de domaine Unix de DogStatsD (remplace `host` et `port`, uniquement pris en charge par l’Agent v6+).
`statsd_constant_tags`	Liste de chaînes	`null`	Les tags à appliquer à l’ensemble des métriques, événements et checks de service.
`statsd_namespace`	Chaîne	`null`	L’espace de nommage à ajouter devant le nom de chaque métrique, événement et check de service.

Pour obtenir la liste complète des paramètres facultatifs disponibles pour datadog.initialize(), ainsi que les paramètres qui sont uniquement disponibles lorsque vous instanciez explicitement des instances datadog.dogstatsd.DogStatsd, consultez la bibliothèque Python de Datadog.

Paramètre	Type	Valeur par défaut	Rôle
`host`	Chaîne	`localhost`	Le host de votre serveur DogStatsD.
`port`	Nombre entier	`8125`	Le port de votre serveur DogStatsD.
`socket_path`	Chaîne	`null`	Le chemin vers le socket de domaine Unix de DogStatsD (remplace `host` et `port`, uniquement pris en charge par l’Agent v6+).
`tags`	Liste de chaînes	`null`	Les tags à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
`namespace`	Chaîne	`null`	L’espace de nommage à ajouter devant le nom de chaque métrique, événement et check de service.
`single_thread`	Booléen	`false`	Lorsque ce paramètre est activé, il permet au client d’envoyer les métriques sur le thread principal plutôt que dans un thread complémentaire.

Paramètre	Type	Rôle
`WithNamespace()`	Chaîne	Permet de configurer un espace de nommage à ajouter devant le nom de chaque métrique, événement et check de service.
`WithTags()`	Liste de chaînes	Les tags globaux à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.

Méthode de builder	Type	Valeur par défaut	Rôle
`prefix(String val)`	Chaîne	null	Préfixe à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
`hostname(String val)`	Chaîne	localhost	Hostname du serveur StatsD ciblé.
`port(int val)`	Nombre entier	8125	Port du serveur StatsD ciblé.
`constantTags(String... val)`	Varargs sous forme de chaîne	null	Tags globaux à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
`blocking(boolean val)`	Booléen	false	Le type de client à instancier : bloquant ou non bloquant.
`socketBufferSize(int val)`	Nombre entier	-1	La taille du buffer du socket sous-jacent.
`enableTelemetry(boolean val)`	Booléen	false	Transmission de données de télémétrie sur le client.
`entityID(String val)`	Chaîne	null	ID d’entité pour la détection de l’origine.
`errorHandler(StatsDClientErrorHandler val)`	Nombre entier	null	Gestionnaire d’erreurs en cas d’erreur client interne.
`maxPacketSizeBytes(int val)`	Nombre entier	8192/1432	Taille maximale des paquets ; 8192 via UDS, 1432 via UDP.
`processorWorkers(int val)`	Nombre entier	1	Nombre de threads worker de processeur qui assemblent les buffers à envoyer.
`senderWorkers(int val)`	Nombre entier	1	Nombre de threads worker d’expéditeur qui envoient les buffers au socket.
`poolSize(int val)`	Nombre entier	512	Taille du pool de buffers de paquets réseau.
`queueSize(int val)`	Nombre entier	4096	Nombre maximal de messages non traités dans la file d’attente.
`timeout(int val)`	Nombre entier	100	Délai en millisecondes pour les opérations de blocage. S’applique uniquement aux sockets Unix.

Paramètre	Type	Valeur par défaut	Rôle
`host`	Chaîne	`localhost`	Host de votre serveur DogStatsD. S’il n’est pas défini, l’Agent utilise la variable d’environnement `DD_AGENT_HOST`.
`port`	Nombre entier	`8125`	Port de votre serveur DogStatsD. S’il n’est pas défini, l’Agent utilise la variable d’environnement `DD_DOGSTATSD_PORT`.
`socket_path`	Chaîne	`null`	Le chemin vers le socket de domaine UNIX de DogStatsD (remplace `host` et `port`). Il est uniquement pris en charge avec les versions 6 et ultérieures de l’Agent.
`global_tags`	Liste de chaînes	`null`	Les tags à appliquer à toutes les métriques, à tous les événements et à tous les checks de service. Le tag `@dd.internal.entity_id` est ajouté à global_tags depuis la variable d’environnement `DD_ENTITY_ID`.

Paramètre	Type	Valeur par défaut	Rôle
`StatsdServerName`	Chaîne	`localhost`	Hostname du serveur StatsD ciblé.
`StatsdPort`	Nombre entier	`8125`	Port du serveur StatsD ciblé.
`Prefix`	Chaîne	`null`	Le préfixe à appliquer à chaque métrique, événement et check de service.
`ConstantTags`	Liste de chaînes	`null`	Tags globaux à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.

Découvrir DogStatsD

DogStatsD et StatsD sont assez semblables. Toutefois, DogStatsD comprend des fonctionnalités avancées propres à Datadog, notamment en ce qui concerne les types de données, les événements, les checks de service et les tags disponibles :

Documentation, liens et articles supplémentaires utiles:

Envoyer des métriques à Datadog avec DogStatsD

Envoyer des événements à Datadog avec DogStatsD

Envoyer des checks de service à Datadog avec DogStatsD

Si vous souhaitez approfondir vos connaissances sur le format des datagrammes utilisé par DogStatsD, ou concevoir votre propre bibliothèque Datadog, consultez la section relative au datagramme et à l’interface système, qui décrit également comment envoyer des métriques et des événements directement depuis la ligne de commande.