Aperçu

Le balisage est utilisé dans tout Datadog pour interroger les machines et les métriques que vous surveillez. Sans la possibilité d’assigner et de filtrer en fonction des balises, il pourrait être difficile de trouver des problèmes dans votre environnement et de les réduire suffisamment pour découvrir les véritables causes. Apprenez à définir des balises dans Datadog avant de continuer.

Les tags peuvent être configurés de différentes manières :

• Dans le fichier de configuration de l’Agent Datadog ou dans chaque fichier de configuration d’intégration individuelle
• Via le UI (interface utilisateur) de Datadog
• Avec l’API de Datadog
• Avec le DogStatsD

Méthodes pour assigner des balises

Fichier de configuration

tags: ["<KEY_1>:<VALUE_1>", "<KEY_2>:<VALUE_2>", "<KEY_3>:<VALUE_3>"]

tags:
    - "<KEY_1>:<VALUE_1>"
    - "<KEY_2>:<VALUE_2>"
    - "<KEY_3>:<VALUE_3>"

# Set the hostname (default: auto-detected)
# Must comply with RFC-1123, which permits only:
# "A" to "Z", "a" to "z", "0" to "9", and the hyphen (-)
hostname: mymachine.mydomain

tags: <KEY_1>:<VALUE_1>, <KEY_2>:<VALUE_2>, <KEY_3>:<VALUE_3>

# Set the hostname (default: auto-detected)
# Must comply with RFC-1123, which permits only:
# "A" to "Z", "a" to "z", "0" to "9", and the hyphen (-)
hostname: mymachine.mydomain

Héritage d’intégration

La méthode la plus efficace pour attribuer des balises est de s’appuyer sur l’héritage d’intégration. Les balises que vous attribuez à vos instances AWS, recettes Chef et autres intégrations sont automatiquement héritées par les hôtes et les métriques que vous envoyez à Datadog.

Dans les environnements conteneurisés, il est recommandé de suivre la documentation relative au tagging de service unifié afin d’effectuer une seule configuration pour toutes vos données de télémétrie Datadog.

Intégrations cloud

Les intégrations cloud sont basées sur l’authentification. Datadog recommande d’utiliser la tuile principale d’intégration cloud (AWS, Azure, Google Cloud, etc.) et d’installer l’Agent lorsque cela est possible. Remarque : Si vous choisissez d’utiliser uniquement l’Agent, certaines balises d’intégration ne sont pas disponibles.

Intégrations web

Les intégrations web sont basées sur l’authentification. Les métriques sont collectées par des appels API. Remarque : CamelCase les balises sont converties en underscores par Datadog, par exemple TestTag –> test_tag.

Variables d’environnement

Après avoir installé l’Agent Datadog containerisé, vous pouvez définir vos balises d’hôte en utilisant la variable d’environnement DD_TAGS dans le fichier de configuration principal de votre Agent. Si vous spécifiez plusieurs balises, séparez chacune par un espace.

Remarque : La variable d’environnement DD_TAGS utilise des espaces pour séparer les balises. Par exemple, DD_TAGS="key1:val1 key2:val2" définit deux balises. Une valeur comme DD_TAGS="test:this is a test" produit quatre balises distinctes (test:this, is, a, test) car chaque jeton séparé par un espace est traité comme sa propre balise. Pour inclure des espaces dans les valeurs de balises, définissez les balises via la configuration YAML ou les annotations d’intégration à la place. Ces méthodes convertissent les espaces en underscores (par exemple, test:this is a test devient test:this_is_a_test).

Datadog collecte automatiquement les balises communes de Docker, Kubernetes, ECS, Swarm, Mesos, Nomad et Rancher. Pour extraire encore plus de balises, utilisez les options suivantes :

Exemples :

DD_KUBERNETES_POD_LABELS_AS_TAGS='{"app":"kube_app","release":"helm_release"}'
DD_CONTAINER_LABELS_AS_TAGS='{"com.docker.compose.service":"service_name"}'

Lors de l’utilisation de DD_KUBERNETES_POD_LABELS_AS_TAGS, vous pouvez utiliser des caractères génériques au format :

{"foo": "bar_%%label%%"}

Par exemple, {"app*": "kube_%%label%%"} se résout au nom de l’étiquette kube_application pour l’étiquette application. De plus, {"*": "kube_%%label%%"} ajoute toutes les étiquettes des pods en tant qu’étiquettes préfixées par kube_.

Lors de l’utilisation de la variable DD_CONTAINER_LABELS_AS_TAGS dans un fichier Docker Swarm docker-compose.yaml, retirez les apostrophes, par exemple :

- DD_CONTAINER_LABELS_AS_TAGS={"com.docker.compose.service":"service_name"}

Lors de l’ajout d’étiquettes aux conteneurs Docker, le placement du mot-clé labels: à l’intérieur du fichier docker-compose.yaml est important. Pour éviter des problèmes, suivez la documentation Docker unified service tagging.

Si le conteneur doit être étiqueté en dehors de cette configuration, placez le mot-clé labels: à l’intérieur de la section services:, pas à l’intérieur de la section deploy:. Placez le mot-clé labels: à l’intérieur de la section deploy: uniquement lorsque le service doit être étiqueté. L’Agent Datadog n’a pas d’étiquettes à extraire des conteneurs sans ce placement.

Ci-dessous se trouve un exemple de fichier docker-compose.yaml fonctionnel qui montre ce placement d’étiquette. Dans l’exemple ci-dessous, les étiquettes dans la section myapplication:, my.custom.label.project et my.custom.label.version ont chacune des valeurs uniques. L’utilisation de la variable d’environnement DD_CONTAINER_LABELS_AS_TAGS dans la section datadog: extrait les étiquettes et produit ces étiquettes pour le conteneur myapplication :

À l’intérieur du conteneur myapplication, les étiquettes sont : my.custom.label.project et my.custom.label.version

Après que l’Agent ait extrait les étiquettes du conteneur, les étiquettes sont : projecttag:projectA versiontag:1

Exemple de docker-compose.yaml :

services:
  datadog:
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock:ro'
      - '/proc:/host/proc:ro'
      - '/sys/fs/cgroup/:/host/sys/fs/cgroup:ro'
    environment:
      - DD_API_KEY= "<DATADOG_API_KEY>"
      - DD_CONTAINER_LABELS_AS_TAGS={"my.custom.label.project":"projecttag","my.custom.label.version":"versiontag"}
      - DD_TAGS="key1:value1 key2:value2 key3:value3"
    image: 'registry.datadoghq.com/agent:latest'
    deploy:
      restart_policy:
        condition: on-failure
      mode: replicated
      replicas: 1
  myapplication:
    image: 'myapplication'
    labels:
      my.custom.label.project: 'projectA'
      my.custom.label.version: '1'
    deploy:
      restart_policy:
        condition: on-failure
      mode: replicated
      replicas: 1

Définissez soit les variables dans votre datadog.yaml personnalisé, soit définissez-les comme des cartes JSON dans ces variables d’environnement. La clé de la carte est le nom de la source (label/envvar), et la valeur de la carte est le nom de l’étiquette Datadog.

Cardinalité des étiquettes

Il existe deux variables d’environnement qui définissent la cardinalité des étiquettes : DD_CHECKS_TAG_CARDINALITY et DD_DOGSTATSD_TAG_CARDINALITY. Parce que DogStatsD est tarifé différemment, le paramètre de cardinalité des étiquettes DogStatsD est séparé pour offrir la possibilité d’une configuration plus fine. Sinon, ces variables fonctionnent de la même manière : elles peuvent avoir des valeurs low, orchestrator ou high. Elles ont toutes deux par défaut low, ce qui inclut les étiquettes au niveau du cluster Kubernetes.

Les différents paramètres de cardinalité ciblent :

• low : étiquettes au niveau du cluster Kubernetes, telles que kube_namespace.
• orchestrator : étiquettes au niveau des pods, telles que pod_name.
• high : étiquettes au niveau des conteneurs, telles que container_id.

En fonction de la cardinalité, il existe un ensemble différent d’étiquettes prêtes à l’emploi pour Kubernetes et OpenShift, et pour Docker, Rancher et Mesos. Pour ECS et Fargate, définir la variable sur orchestrator ajoute l’étiquette task_arn.

Notes :

• L’envoi d’étiquettes de conteneur pour les métriques DogStatsD peut créer plus de métriques (une par conteneur au lieu d’une par hôte). Cela peut avoir un impact sur la facturation de vos métriques personnalisées.
• Dans les métriques, les horodatages sont arrondis à la seconde la plus proche. Si des points ont le même horodatage, le dernier point écrase les précédents. Définir une cardinalité plus élevée peut aider à prévenir ce problème.

Traces

Le SDK Datadog peut être configuré avec des variables d’environnement, des propriétés système ou par le biais de la configuration dans le code. La documentation de la configuration du traçage Datadog contient des informations sur les options d’étiquetage et la configuration pour chaque SDK. Vous pouvez également suivre la documentation sur l’étiquetage de service unifié 2 pour configurer votre SDK pour l’étiquetage de service unifié.

Quel que soit le SDK utilisé, les métadonnées de span doivent respecter une structure d’arbre typée. Chaque nœud de l’arbre est séparé par un . et est d’un seul type.

Par exemple, un nœud ne peut pas être à la fois un objet (avec des sous-nœuds) et une chaîne :

{
  "key": "value",
  "key.subkey": "value_2"
}

Les métadonnées de span ci-dessus sont invalides puisque la valeur de key ne peut pas référencer une chaîne ("value") et aussi un sous-arbre ({"subkey": "value_2"}).

UI

Attribuez des étiquettes d’hôte dans l’UI en utilisant la page de carte des hôtes. Cliquez sur n’importe quel hexagone (hôte) pour afficher la superposition de l’hôte en bas de la page. Ensuite, sous la section Utilisateur, cliquez sur le bouton Ajouter des étiquettes. Entrez les étiquettes sous forme de liste séparée par des virgules, puis cliquez sur Enregistrer les étiquettes. Les modifications apportées aux étiquettes d’hôte dans l’UI peuvent prendre jusqu’à cinq minutes pour s’appliquer.

Attribuez des étiquettes d’hôte dans l’UI en utilisant la page de liste d’infrastructure. Cliquez sur n’importe quel hôte pour afficher la superposition de l’hôte à droite de la page. Ensuite, sous la section Utilisateur, cliquez sur le bouton Ajouter des étiquettes. Entrez les étiquettes sous forme de liste séparée par des virgules, puis cliquez sur Enregistrer les étiquettes. Les modifications apportées aux étiquettes d’hôte dans l’UI peuvent prendre jusqu’à cinq minutes pour s’appliquer. Après avoir ajouté des étiquettes, assurez-vous qu’elles sont visibles dans l’UI avant d’essayer d’ajouter d’autres étiquettes.

Depuis la page Gérer les Moniteurs, sélectionnez la case à cocher à côté de chaque moniteur pour ajouter des étiquettes (sélectionnez un ou plusieurs moniteurs). Cliquez sur le bouton Modifier les étiquettes. Entrez une étiquette ou sélectionnez-en une utilisée précédemment. Puis cliquez sur Ajouter une étiquette tag:name ou Appliquer les modifications. Si des étiquettes ont été ajoutées précédemment, plusieurs étiquettes peuvent être attribuées en même temps en utilisant les cases à cocher des étiquettes. Pour plus d’informations, consultez la documentation sur la gestion des moniteurs.

Lors de la création d’un moniteur, attribuez des étiquettes de moniteur à l’étape 4 Indiquez ce qui se passe ou Notifier votre équipe :

Créez des agrégations de percentile dans Métriques de distribution en appliquant une liste autorisée de jusqu’à dix étiquettes à une métrique. Cela crée une série temporelle pour chaque combinaison potentiellement interrogeable de valeurs d’étiquettes. Pour plus d’informations sur le comptage des métriques personnalisées et des séries temporelles émises par les métriques de distribution, consultez Métriques personnalisées.

Appliquez jusqu’à dix étiquettes. Les étiquettes d’exclusion ne sont pas acceptées :

La tuile d’intégration AWS vous permet d’attribuer des étiquettes supplémentaires à toutes les métriques au niveau du compte, ainsi qu’aux journaux envoyés via déclencheurs d’abonnement automatique. Utilisez une liste d’étiquettes séparées par des virgules sous la forme <KEY>:<VALUE>.

Lors de la création d’un SLO, attribuez des étiquettes à l’étape 3, Ajouter un nom et des étiquettes :

API

Web server 1: api.metric('page.views', [(1317652676, 100), ...], host="example_prod_1")
Web server 2: api.metric('page.views', [(1317652676, 500), ...], host="example_prod_2")

Web server 1: api.metric('page.views', [(1317652676, 100), ...], tags=['domain:example.com'])
Web server 2: api.metric('page.views', [(1317652676, 500), ...], tags=['domain:example.com'])

sum:page.views{domain:example.com}

sum:page.views{domain:example.com} by {host}

DogStatsD

Ajoutez des étiquettes à toute métrique, événement ou vérification de service que vous envoyez à DogStatsD. Par exemple, comparez la performance de deux algorithmes en étiquetant une métrique de minuterie avec la version de l’algorithme :

@statsd.timed('algorithm.run_time', tags=['algorithm:one'])
def algorithm_one():
    # Do fancy things here ...

@statsd.timed('algorithm.run_time', tags=['algorithm:two'])
def algorithm_two():
    # Do fancy things (maybe faster?) here ...

Remarque : L’étiquetage est une extension spécifique à Datadog de StatsD.

Une attention particulière est nécessaire lors de l’attribution de l’étiquette host aux métriques DogStatsD. Pour plus d’informations sur la clé d’étiquette d’hôte, consultez la documentation Soumission de Métriques : DogStatsD.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Débuter avec les tagsDOCUMENTATION Apprendre à utiliser des tags dans DatadogDOCUMENTATION