Les DogStatsD tags unifiés relient vos métriques custom aux traces et aux logs d’un même service grâce à trois étiquettes : env, service et version. Sans elles, une métrique envoyée en UDP vers le port 8125 reste orpheline : impossible de la filtrer par déploiement ou de la comparer à la version précédente.
Ce tutoriel suit la documentation Datadog : envoyer une métrique à DogStatsD, poser les étiquettes sur Kubernetes, puis vérifier qu’elles arrivent bien. Pour une équipe SRE, l’enjeu est concret : lors d’un incident, filtrer sur version:1.4.2 vous dit vite si la régression suit le dernier déploiement.
Notre blog traite aussi la cardinalité des métriques custom et le modèle de facturation APM. Ici, on reste sur le marquage.
En bref
- DogStatsD écoute en UDP sur le port 8125 (Agent v6 et suivants). L’application n’attend aucune réponse.
- Les tags réservés
env,serviceetversionsont recommandés par Datadog pour lier métriques, traces et logs. - Si le service voit
DD_ENV,DD_SERVICEetDD_VERSION, le client DogStatsD ajoute ces tags aux métriques custom. Les clients .NET et PHP ne le font pas, selon la documentation. - Sur Kubernetes, l’Admission Controller du Cluster Agent peut injecter ces variables à partir des labels des pods.
DogStatsD tags unifiés : le problème à résoudre
Une métrique checkout.latency émise par vingt pods n’a de valeur que si vous savez de quel environnement et de quelle version elle vient. Vous pourriez coder ces tags à la main dans chaque appel. C’est fragile : une faute de frappe crée un nouveau tag, donc une nouvelle série.
Le marquage unifié déplace la décision hors du code. Le déploiement porte les valeurs, l’application les lit dans son environnement, et le client les ajoute. L’objectif de cet article : obtenir ce comportement sur un service Kubernetes, puis le contrôler de bout en bout.
Prérequis, d’après la documentation Datadog : Agent 6.19.x ou 7.19.x au minimum, un SDK ou client compatible, et pour l’injection automatique un Cluster Agent v7.40 ou plus récent. Cet article porte sur Datadog ; il ne dit rien de Dynatrace Managed ou SaaS.
Étape 1 : envoyer une métrique à DogStatsD sur le port 8125
Avant de parler de tags, validez le chemin réseau. Le format d’un datagramme est : nom, valeur, type, taux d’échantillonnage facultatif, puis tags précédés de #. Le nom accepte lettres ASCII, chiffres, tirets bas et points. Les types sont c (compteur), g (jauge), ms (timer), h (histogramme), s (set) et d (distribution).

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
L’option -n de echo supprime le saut de ligne final. Les options -4u de nc imposent l’UDP en IPv4. Ces commandes viennent de la page de la documentation sur le format des datagrammes.
Où écoute l’Agent
Sur un hôte, le port se règle avec dogstatsd_port dans datadog.yaml, valeur par défaut 8125. En conteneur, publiez 8125/udp et définissez DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" si des métriques arrivent d’ailleurs que de localhost. Avec Helm, le bloc dogstatsd accepte port, useHostPort et nonLocalTraffic.
Sur Kubernetes, la documentation propose de passer l’IP du nœud au pod avec DD_AGENT_HOST, lue depuis status.hostIP. Le pod envoie alors vers le port 8125 de cette adresse.
Étape 2 : initialiser le client DogStatsD
Côté application, un client DogStatsD encapsule l’envoi UDP. Exemple Python tiré de la documentation (pip install datadog) :

from datadog import initialize, statsd
options = {
'statsd_host':'127.0.0.1',
'statsd_port':8125
}
initialize(**options)
Le client Python propose aussi statsd_constant_tags (tags appliqués à toutes les métriques, événements et checks de service) et statsd_namespace (préfixe de nom). La documentation précise que les clients Python sont sûrs entre threads mais ne se partagent pas entre processus : chaque processus fils crée son propre client, ou active disable_buffering.
Les constantes statsd_constant_tags restent utiles pour un tag qui ne dépend pas du déploiement. Pour env, service et version, préférez le mécanisme unifié ci-dessous.
Étape 3 : poser env, service et version sur Kubernetes
La documentation sur le marquage unifié décrit la configuration complète : trois labels tags.datadoghq.com/env, /service et /version, placés à la fois sur la ressource parente (Deployment) et sur le modèle de pod. Pour l’APM, on ajoute les variables DD_ENV, DD_SERVICE et DD_VERSION, lues par l’API descendante (fieldRef) depuis ces labels.

metadata:
labels:
tags.datadoghq.com/env: "prod"
tags.datadoghq.com/service: "checkout"
tags.datadoghq.com/version: "1.4.2"
env:
- name: DD_SERVICE
valueFrom:
fieldRef:
fieldPath: metadata.labels['tags.datadoghq.com/service']
Pour les métriques et les logs, la documentation indique que les labels au niveau du pod suffisent : les variables DD_* ne sont requises que pour l’APM. Mais pour que le client DogStatsD du processus applicatif ajoute lui-même les tags, le service doit voir les trois variables. C’est ce que dit la page : si DD_ENV, DD_SERVICE et DD_VERSION sont visibles, les tags correspondants sont ajoutés aux métriques custom.
Conteneurs multiples et Docker
Pour un pod à plusieurs conteneurs, utilisez tags.datadoghq.com/<NOM_CONTENEUR>.env (et .service, .version). Sous Docker, les labels équivalents sont com.datadoghq.tags.env, .service et .version.
Étape 4 : laisser l’Admission Controller injecter les variables
Écrire les variables dans chaque manifeste est répétitif. L’Admission Controller du Cluster Agent le fait pour vous. Selon la documentation Datadog, il injecte DD_AGENT_HOST, DD_TRACE_AGENT_URL, DD_ENTITY_ID et DD_EXTERNAL_ENV, ainsi que env, service et version tirés des labels. Les labels du pod l’emportent sur ceux de la ressource propriétaire, et une variable DD_ENV, DD_SERVICE ou DD_VERSION déjà présente n’est jamais écrasée.
Les options d’activation :
- Datadog Operator :
features.admissionController.enabledetfeatures.admissionController.mutateUnlabelled; - Helm :
clusterAgent.admissionController.enabledetclusterAgent.admissionController.mutateUnlabelled(activé par défaut depuis la version 2.35.0 du chart, d’après la page) ; - DaemonSet : variables
DD_ADMISSION_CONTROLLER_ENABLEDetDD_ADMISSION_CONTROLLER_MUTATE_UNLABELLEDsur le Cluster Agent.
Les limites à connaître
- C’est un
MutatingAdmissionWebhook: il ne modifie les pods qu’à leur création. Un pod déjà en cours ne reçoit rien ; il faut le recréer. - Il ne couvre que les variables APM et DogStatsD et les tags standards.
- Avec
mutateUnlabelled: false(valeur par défaut), un pod sans label n’est pas injecté. Un pod portantadmission.datadoghq.com/enabled: "false"n’est jamais injecté, même simutateUnlabelledvauttrue.
Le mode de communication (hostip par défaut, service, socket, csi) détermine comment DD_AGENT_HOST ou le socket est rempli. Le mode service demande Kubernetes 1.22 ou plus.
Comment vérifier que ça fonctionne
- Dans le pod :
kubectl exec <pod> -- env | grep DD_doit listerDD_ENV,DD_SERVICEetDD_VERSIONavec vos valeurs. - Dans Datadog, ouvrez le Metrics Explorer et filtrez votre métrique custom : les tags
env,serviceetversiondoivent apparaître comme facettes. - Déployez une nouvelle version : la valeur de
versiondoit changer. La documentation insiste sur ce point :versiondoit évoluer à chaque déploiement.
Je n’ai pas exécuté ces commandes dans un cluster pour cet article ; elles découlent de la documentation citée. Relisez-les dans votre contexte.
- Ne définissez pas
envà deux valeurs différentes : les tags StatsD s’ajoutent, et une métrique peut porter les deux. C’est aussi vrai pour unenvglobal (Helmdatadog.tags) combiné à un label de pod différent. - Évitez d’ajouter
versionaux métriques système d’un hôte non conteneurisé : elle ne change pas à chaque invocation. - Gardez des valeurs de tags à faible cardinalité ;
versionest acceptable, un identifiant de requête ne l’est pas. - Le trafic UDP est sans accusé de réception : une métrique perdue ne génère aucune erreur côté application. Surveillez l’Agent, pas seulement le code.
Et OpenTelemetry ?
Selon la même page, les variables DD_* ne sont pas prises en charge d’emblée avec OpenTelemetry. On utilise OTEL_RESOURCE_ATTRIBUTES avec service.name, service.version et deployment.environment.name, et OTEL_SERVICE_NAME prime sur service.name. Si vous hésitez entre les deux mondes, lisez notre comparatif OpenTelemetry et Prometheus et notre comparatif Dynatrace et Datadog. Dynatrace a sa propre logique de marquage ; je ne décris ici aucune équivalence non documentée.
Pour le déploiement d’un collecteur dans le même cluster, voir le Collector OpenTelemetry sur Kubernetes.
Questions fréquentes
Quel port utilise DogStatsD ?
L’UDP 8125 par défaut pour l’Agent v6 et suivants. Il se change avec dogstatsd_port dans datadog.yaml ou avec DD_DOGSTATSD_PORT en conteneur.
Pourquoi mes métriques DogStatsD n’ont-elles pas le tag version ?
Vérifiez d’abord que le processus voit DD_VERSION et que votre client le gère : selon la documentation, les clients .NET et PHP ne reprennent pas ces variables. Vérifiez ensuite que le pod a été créé après l’activation de l’Admission Controller.
Faut-il les variables DD_* pour les métriques ?
Pour les métriques et les logs vus par l’Agent, les labels de pod suffisent. Pour que le client DogStatsD ajoute les tags dans le processus, les variables doivent être présentes.
Conclusion
Trois labels, trois variables et un Admission Controller bien réglé suffisent pour que chaque métrique custom porte son environnement, son service et sa version. C’est un petit investissement qui accélère le diagnostic. Pour aller plus loin sur la méthode, lisez observabilité et monitoring.
Sources
- DogStatsD, documentation Datadog
- Format des datagrammes DogStatsD, documentation Datadog
- Unified Service Tagging, documentation Datadog
- Admission Controller, documentation Datadog
span.observer est un blog indépendant, non affilié à Dynatrace LLC ni à Datadog Inc. Les noms de produits appartiennent à leurs propriétaires respectifs. Les extraits de code reprennent des exemples de la documentation officielle ; les valeurs sont des exemples.