DogStatsD tags unifiés : env, service, version dans les métriques

DogStatsD tags unifiés : envoyez des métriques en UDP sur le port 8125 et ajoutez env, service et version via DD_ENV, DD_SERVICE, DD_VERSION.
DogStatsD tags unifiés : env, service, version dans les métriques

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, service et version sont recommandés par Datadog pour lier métriques, traces et logs.
  • Si le service voit DD_ENV, DD_SERVICE et DD_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).

Format d'un datagramme DogStatsD et trois commandes shell qui envoient une métrique en UDP vers le port 8125 de localhost
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) :

Initialisation du client DogStatsD Python avec statsd_host 127.0.0.1 et statsd_port 8125
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.

Extrait YAML de Deployment avec les labels tags.datadoghq.com env, service et version, et la variable DD_SERVICE lue par fieldRef
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.enabled et features.admissionController.mutateUnlabelled ;
  • Helm : clusterAgent.admissionController.enabled et clusterAgent.admissionController.mutateUnlabelled (activé par défaut depuis la version 2.35.0 du chart, d’après la page) ;
  • DaemonSet : variables DD_ADMISSION_CONTROLLER_ENABLED et DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED sur 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 portant admission.datadoghq.com/enabled: "false" n’est jamais injecté, même si mutateUnlabelled vaut true.

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

  1. Dans le pod : kubectl exec <pod> -- env | grep DD_ doit lister DD_ENV, DD_SERVICE et DD_VERSION avec vos valeurs.
  2. Dans Datadog, ouvrez le Metrics Explorer et filtrez votre métrique custom : les tags env, service et version doivent apparaître comme facettes.
  3. Déployez une nouvelle version : la valeur de version doit changer. La documentation insiste sur ce point : version doit é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.

Bonnes pratiques

  • 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 un env global (Helm datadog.tags) combiné à un label de pod différent.
  • Évitez d’ajouter version aux métriques système d’un hôte non conteneurisé : elle ne change pas à chaque invocation.
  • Gardez des valeurs de tags à faible cardinalité ; version est 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

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.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Snapshot Elasticsearch : sauvegarde et snapshot consultable ne sont pas la même chose

Snapshot Elasticsearch : sauvegarde et snapshot consultable ne sont pas la même chose

Next Post
Jan alternative ChatGPT open source : IA locale hors ligne

Jan alternative ChatGPT open source : IA locale hors ligne

Related Posts