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

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 HubGCR
hub.docker.com/r/datadog/dogstatsdgcr.io/datadoghq/dogstatsd

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.

Dogstatsd

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.

Configuration

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 :

  1. 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
    
  2. 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 :

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.

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

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

  3. 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é][8].

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 :

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

  2. Mettez à jour la configuration de votre Agent :

    helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog
    
  3. 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
gem install dogstatsd-ruby
go get github.com/DataDog/datadog-go/v5/statsd

Le client Java StatsD Datadog est distribué avec Maven Central et peut être téléchargé depuis Maven. Commencez par ajouter la configuration suivante à votre fichier pom.xml :

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>3.0.0</version>
</dependency>

Ajoutez ce qui suit à votre fichier composer.json :

"datadog/php-datadogstatsd": "1.4.*"

Remarque : la première version distribuée dans Composer est la version 0.0.3.

Vous pouvez également dupliquer manuellement le référentiel disponible sur github.com/DataDog/php-datadogstatsd et le configurer avec require './src/DogStatsd.php'.

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.
# Importer la bibliothèque
require 'datadog/statsd'

# Créer une instance client DogStatsD
statsd = Datadog::Statsd.new('localhost', 8125)
dogstatsd_client, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}

Pour découvrir plus d’options, consultez la documentation Datadog pour Go (en anglais).

import com.timgroup.statsd.NonBlockingStatsDClientBuilder;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

    public static void main(String[] args) throws Exception {

        StatsDClient statsd = new NonBlockingStatsDClientBuilder()
            .prefix("statsd")
            .hostname("localhost")
            .port(8125)
            .build();


        // ou utiliser
        StatsDClient statsdAlt = new NonBlockingStatsDClient(
            new NonBlockingStatsDClientBuilder(
                .prefix("statsd")
                .hostname("localhost")
                .port(8125)
                .resolve()));

    }
}

Instanciez un nouvel objet DogStatsD avec Composer :

<?php

require __DIR__ . '/vendor/autoload.php';

use DataDog\DogStatsd;

$statsd = new DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );

Configurez la classe DogStatsD :

// Le code se trouve sous l'espace de nommage StatsdClient
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

using (var dogStatsdService = new DogStatsdService())
{
    dogStatsdService.Configure(dogstatsdConfig);
    // ...
} // Transmettre les métriques pas encore envoyées

Si vous utilisez DogStatsD avec l'Agent de conteneur ou dans Kubernetes, vous devez instancier le host auquel les métriques StatsD sont transmises avec la variable d'environnement $DD_DOGSTATSD_SOCKET si vous utilisez un socket de domaine Unix, ou avec la variable d'environnement $DD_AGENT_HOST si vous avez lié le port DogStatsD à un port du host.

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ètreTypeValeur par défautDescription
statsd_hostChaînelocalhostLe host de votre serveur DogStatsD.
statsd_portNombre entier8125Le port de votre serveur DogStatsD.
statsd_socket_pathChaînenullLe chemin vers le socket de domaine Unix de DogStatsD (remplace host et port, uniquement pris en charge par l’Agent v6+).
statsd_constant_tagsListe de chaînesnullLes tags à appliquer à l’ensemble des métriques, événements et checks de service.
statsd_namespaceChaînenullL’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ètreTypeValeur par défautDescription
hostChaînelocalhostLe host de votre serveur DogStatsD.
portNombre entier8125Le port de votre serveur DogStatsD.
socket_pathChaînenullLe chemin vers le socket de domaine Unix de DogStatsD (remplace host et port, uniquement pris en charge par l’Agent v6+).
tagsListe de chaînesnullLes tags à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
namespaceChaînenullL’espace de nommage à ajouter devant le nom de chaque métrique, événement et check de service.
single_threadBooléenfalseLorsque 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.

Pour obtenir la liste complète des paramètres facultatifs, consultez le référentiel dogstatsd-ruby sur GitHub.

Le client Go dispose de plusieurs options pour la configuration du comportement de votre client.

ParamètreTypeDescription
WithNamespace()ChaînePermet de configurer un espace de nommage à ajouter devant le nom de chaque métrique, événement et check de service.
WithTags()Liste de chaînesLes tags globaux à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.

Pour découvrir toutes les options disponibles, consultez la documentation Datadog pour Go (en anglais).

Depuis la version 2.10.0, il est conseillé d’instancier le client avec NonBlockingStatsDClientBuilder. Vous pouvez utiliser les méthodes de builder suivantes pour définir les paramètres du client.

Méthode de builderTypeValeur par défautDescription
prefix(String val)ChaînenullPréfixe à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
hostname(String val)ChaînelocalhostHostname du serveur StatsD ciblé.
port(int val)Nombre entier8125Port du serveur StatsD ciblé.
constantTags(String... val)Varargs sous forme de chaînenullTags globaux à appliquer à toutes les métriques, à tous les événements et à tous les checks de service.
blocking(boolean val)BooléenfalseLe type de client à instancier : bloquant ou non bloquant.
socketBufferSize(int val)Nombre entier-1La taille du buffer du socket sous-jacent.
enableTelemetry(boolean val)BooléenfalseTransmission de données de télémétrie sur le client.
entityID(String val)ChaînenullID d’entité pour la détection de l’origine.
errorHandler(StatsDClientErrorHandler val)Nombre entiernullGestionnaire d’erreurs en cas d’erreur client interne.
maxPacketSizeBytes(int val)Nombre entier8192/1432Taille maximale des paquets ; 8192 via UDS, 1432 via UDP.
processorWorkers(int val)Nombre entier1Nombre de threads worker de processeur qui assemblent les buffers à envoyer.
senderWorkers(int val)Nombre entier1Nombre de threads worker d’expéditeur qui envoient les buffers au socket.
poolSize(int val)Nombre entier512Taille du pool de buffers de paquets réseau.
queueSize(int val)Nombre entier4096Nombre maximal de messages non traités dans la file d’attente.
timeout(int val)Nombre entier100Délai en millisecondes pour les opérations de blocage. S’applique uniquement aux sockets Unix.

Pour en savoir plus, recherchez le package DogStatsD Java pour les classes NonBlockingStatsDClient et NonBlockingStatsDClientBuilder. Veillez à utiliser la version correspondant à votre client.

ParamètreTypeValeur par défautDescription
hostChaînelocalhostHost de votre serveur DogStatsD. S’il n’est pas défini, l’Agent utilise la variable d’environnement DD_AGENT_HOST.
portNombre entier8125Port de votre serveur DogStatsD. S’il n’est pas défini, l’Agent utilise la variable d’environnement DD_DOGSTATSD_PORT.
socket_pathChaînenullLe 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_tagsListe de chaînesnullLes 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ètreTypeValeur par défautDescription
StatsdServerNameChaînelocalhostHostname du serveur StatsD ciblé.
StatsdPortNombre entier8125Port du serveur StatsD ciblé.
PrefixChaînenullLe préfixe à appliquer à chaque métrique, événement et check de service.
ConstantTagsListe de chaînesnullTags 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 :


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.