Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Assigner des tags

Présentation

Les tags vous permettent d’interroger les machines et métriques que vous surveillez avec Datadog. Pour identifier les problèmes au sein de votre environnement et affiner suffisamment les données afin d’en découvrir les causes profondes, vous devez être en mesure d’assigner des tags et d’appliquer des filtres à partir de ces derniers. Découvrez comment définir des tags dans Datadog avant de poursuivre la lecture de cette rubrique.

Vous pouvez assigner des tags au sein de plusieurs éléments de Datadog : les fichiers de configuration, les variables d’environnement, vos traces, l’IU de Datadog, l’API, DogStatsD et les intégrations (grâce à leur fonction d’héritage). Nous vous recommandons d’utiliser les fichiers de configuration et l’héritage des intégrations pour l’assignation de la majorité de vos tags.

Fichiers de configuration

Hostname

Le hostname (clé de tag host) est assigné automatiquement par l’Agent Datadog. Pour personnaliser le hostname, utilisez le fichier de configuration de l’Agent, datadog.yaml :

# Définissez le hostname (par défaut : détection automatique)
# Doit être conforme à la norme RFC-1123, qui autorise uniquement :
# les caractères de « A » à « Z », de « a » à « z », de « 0 » à « 9 » et « - » (trait d'union)
hostname: mamachine.mondomaine

Modifier le hostname

  • L’ancien hostname reste dans l’interface pendant 2 heures, mais n’affiche pas les nouvelles métriques.
  • Vous pouvez interroger les données provenant de hosts avec l’ancien hostname grâce à l’API.
  • Pour représenter des métriques avec l’ancien hostname et le nouveau hostname dans un seul graphique, utilisez des opérations arithmétiques entre deux métriques.

Ajouter des tags

Le fichier de configuration de l’Agent (datadog.yaml) est également utilisé pour définir des tags de host qui s’appliquent à l’ensemble des métriques, des traces et des logs transmis par l’Agent Datadog (voir les formats YAML ci-dessous).

Le fichier de configuration de l’Agent (datadog.conf) est également utilisé pour définir des tags de host qui s’appliquent à l’ensemble des métriques, des traces et des logs transmis par l’Agent Datadog. Les tags dans le fichier datadog.conf doivent respecter le format suivant :

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

Les tags pour les intégrations installées avec l’Agent sont configurés à l’aide des fichiers YAML situés dans le répertoire conf.d de l’installation de l’Agent. Pour accéder aux fichiers de configuration, consultez les fichiers de configuration de l’Agent.

Formats YAML

Dans les fichiers YAML, utilisez un dictionnaire de tags pour assigner une liste de tags. Les dictionnaires de tags peuvent respecter deux formats différents, aux caractéristiques similaires :

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

ou

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

Nous conseillons d’assigner des tags sous la forme de paires <KEY>:<VALUE>. L’autre format de tags plus simple est également accepté. Consultez la rubrique sur la définition des tags pour en savoir plus.

Variables d’environnement

Lors de l’installation de l’Agent Datadog conteneurisé, définissez vos tags de host à l’aide de la variable d’environnement DD_TAGS. Nous recueillons automatiquement les tags courants de Docker, Kubernetes, ECS, Swarm, Mesos, Nomad et Rancher. Pour extraire encore plus de tags, utilisez les paramètres suivants :

Variable d’environnementDescription
DD_DOCKER_LABELS_AS_TAGSExtraire les étiquettes de conteneur Docker
DD_DOCKER_ENV_AS_TAGSExtraire les variables d’environnement de conteneur Docker
DD_KUBERNETES_POD_LABELS_AS_TAGSExtraire les étiquettes de pod
DD_CHECKS_TAG_CARDINALITYAjouter des tags aux métriques de check
DD_DOGSTATSD_TAG_CARDINALITYAjouter des tags aux métriques custom

Exemples :

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

Lorsque vous utilisez DD_KUBERNETES_POD_LABELS_AS_TAGS, vous pouvez utiliser des wildcards au format suivant :

{"foo", "bar_%%label%%"}

Par exemple, {"app*", "kube_%%label%%"} correspond au nom de tag kube_application pour l’étiquette application. En outre, {"*", "kube_%%label%%"} ajoute toutes les étiquettes de pod en tant que tags avec le préfixe kube_.

Lorsque vous utilisez la variable DD_DOCKER_LABELS_AS_TAGS dans un fichier docker-compose.yaml Docker Swarm, assurez-vous de supprimer les apostrophes. Exemple :

DD_DOCKER_LABELS_AS_TAGS={"com.docker.compose.service":"service_name"}

Lors de l’ajout d’étiquettes à des conteneurs Docker, le placement du mot-clé labels: à l’intérieur du fichier docker-compose.yaml est très important. Si les étiquettes doivent être appliquées au conteneur, placez le mot-clé labels: dans de la section services:, et non dans la section deploy:. Placez le mot-clé labels: dans la section deploy: uniquement lorsque les étiquettes doivent être appliquées au service. L’Agent Datadog n’a aucune étiquette à extraire des conteneurs si ce placement n’est pas utilisé. Un exemple de fichier docker-compose.yaml valide illustrant cette notion est présenté ci-dessous. Dans cet exemple, les étiquettes my.custom.label.project et my.custom.label.version dans la section myapplication: ont chacune des valeurs uniques. L’utilisation de la variable d’environnement DD_DOCKER_LABELS_AS_TAGS dans la section datadog: permet d’extraire les étiquettes et de générer ces tags pour le conteneur myapplication :

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

Une fois que l’Agent aura extrait les étiquettes du conteneur, les tags seront les suivants : projecttag:projectA versiontag:1

Exemple de fichier 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=abcdefghijklmnop
      - DD_DOCKER_LABELS_AS_TAGS={"my.custom.label.project":"projecttag","my.custom.label.version":"versiontag"}
      - DD_TAGS="key1:value1 key2:value2 key3:value3"
    image: 'datadog/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 les variables dans votre fichier datadog.yaml personnalisé ou configurez-les en tant que cartes JSON dans ces variables d’environnement. La clé de carte correspond au nom de la source (label/envvar), tandis que sa valeur correspond au nom du tag Datadog.

Il existe deux variables d’environnement qui définissent la cardinalité des tags : DD_CHECKS_TAG_CARDINALITY et DD_DOGSTATSD_TAG_CARDINALITY. Les règles de tarification pour DogStatsD étant différentes, un paramètre de cardinalité distinct est utilisé afin d’offrir des options de configuration plus poussées. Pour le reste, ces variables fonctionnent de la même façon : elles acceptent la valeur low, orchestrator ou high. Par défaut, la valeur low est utilisée, ce qui permet de récupérer les tags au niveau du host.

Si vous définissez la variable sur orchestrator, cela ajoute les tags suivants : pod_name (Kubernetes), oshift_deployment (OpenShift), task_arn (ECS et Fargate) et mesos_task (Mesos).

Si vous définissez la variable sur high, cela ajoute également les tags suivants : container_name (Docker), container_id (Docker) et display_container_name (Kubelet).

Traces

Si vous envoyez une seule trace, taguez ses spans afin d’ignorer les tags de configuration de l’Agent et/ou la valeur des tags du host (le cas échéant) pour ces traces :

Les exemples suivants utilisent le tag primaire par défaut env:<ENVIRONNEMENT>. Cependant, vous pouvez également le remplacer par un tag <KEY>:<VALUE>.

tracer.SetTag("env", "<ENVIRONNEMENT>")

Pour OpenTracing, utilisez l’option de démarrage tracer.WithGlobalTag pour définir de façon globale l’environnement.

Avec sysprop :

-Ddd.trace.span.tags=env:<ENVIRONNEMENT>

Avec des variables d’environnement :

DD_TRACE_SPAN_TAGS="env:<ENVIRONNEMENT>"
Datadog.tracer.set_tags('env' => '<ENVIRONNEMENT>')
from ddtrace import tracer
tracer.set_tags({'env': '<ENVIRONNEMENT>'})
using Datadog.Tracing;
Tracer.Instance.ActiveScope.Span.SetTag("env", "<ENVIRONNEMENT>");

Remarque : les métadonnées span doivent respecter une arborescence. Chaque nœud de l’arborescence est séparé par le caractère . et ne peut posséder qu’un seul type. Ainsi, un nœud ne peut pas être un objet (avec des nœuds inférieurs) ET une chaîne de caractères.

Cet exemple de tags de span n’est donc pas valide :

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

IU

Vous pouvez assigner des tags de host dans l’interface depuis la page relative à la Hostmap. Cliquez sur l’hexagone (host) de votre choix pour superposer le host en bas de la page. Depuis la section User, cliquez ensuite sur le bouton Edit Tags. Saisissez les tags sous forme de liste de valeurs séparées par des virgules, puis cliquez sur Save Tags. Remarque : l’application des modifications de tags de métrique effectuées via l’interface peut prendre jusqu’à 30 minutes.

Vous pouvez assigner des tags de host dans l’interface depuis la page relative à la liste d’infrastructures. Cliquez sur un host pour le superposer sur la droite de la page. Depuis la section User, cliquez ensuite sur le bouton Edit Tags. Saisissez les tags sous forme de liste de valeurs séparées par des virgules, puis cliquez sur Save Tags. Remarque : l’application des modifications de tags de métrique effectuées via l’interface peut prendre jusqu’à 30 minutes.

Depuis la page de gestion des monitors, cochez la case en regard de chaque monitor pour ajouter des tags (sélectionnez un ou plusieurs monitors). Cliquez sur le bouton Edit Tags. Saisissez un tag ou sélectionnez un tag précédemment utilisé. Cliquez ensuite sur Add Tag nom:tag ou Apply Changes. Si vous aviez déjà ajouté des tags, vous pouvez assigner plusieurs tags à la fois en cochant leurs cases.

Lorsque vous créez un monitor, assignez des tags de monitor durant l’étape 4 *Say what’s happening* :

Créez des agrégations par centiles dans les métriques de distribution en appliquant une liste blanche d’un maximum de dix tags à une métrique. Cela permet de créer une série temporelle pour chaque combinaison de valeurs de tags potentiellement interrogeable. Pour en savoir plus sur le comptage de métriques custom et de séries temporelles émises à partir de métriques de distribution, consultez Métriques custom.

Jusqu’à dix tags peuvent être appliqués. Les tags d’exclusion ne sont pas acceptés :

Le carré d’intégration AWS vous permet d’assigner des tags supplémentaires à l’ensemble des métriques pour un compte spécifique. Utilisez une liste de tags au format <KEY>:<VALUE> séparés par des virgules.

API

Les tags peuvent être assignés de diverses façons avec l’API Datadog. Cliquez sur les liens ci-dessous pour accéder aux rubriques indiquées :

Les tags de Datadog vous permettent de recueillir facilement vos métriques. Pour mieux comprendre, imaginons que vous cherchez à obtenir un total pour l’ensemble de métriques suivant fourni par votre site Web (example.com) :

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")

Nous vous conseillons d’ajouter le tag domain:example.com et de ne pas toucher au hostname (l’API Datadog détermine automatiquement le hostname) :

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'])

Grâce au tag domain:example.com, vous pouvez calculer le total des vues de pages pour l’ensemble des hosts :

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

Pour obtenir des données détaillées pour chaque host, utilisez l’expression suivante :

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

DogStatsD

Vous pouvez ajouter des tags aux métriques, événements ou checks de service que vous envoyez à DogStatsD. Pour comparer les performances de deux algorithmes, il vous suffit donc de taguer une métrique de type timer de façon à indiquer la version de l’algorithme :

@statsd.timed('algorithm.run_time', tags=['algorithm:one'])
def algorithm_one():
    # À vous de jouer...

@statsd.timed('algorithm.run_time', tags=['algorithm:two'])
def algorithm_two():
    # À vous de jouer... (avec une version plus rapide ?)

Remarque : l’ajout de tags dans StatsD requiert une extension Datadog.

Des précautions particulières doivent être prises pour l’assignation du tag host aux métriques DogStatsD. Pour en savoir plus sur la clé de tag host, consultez la rubrique DogStatsD.

Héritage des intégrations

Pour assigner facilement des tags, nous vous conseillons de faire appel à la fonction d’héritage des intégrations. Les tags que vous assignez à vos instances AWS, à vos recettes Chef ainsi qu’à d’autres intégrations sont automatiquement appliqués aux hosts et aux métriques que vous envoyez à Datadog.

Intégrations cloud

Les intégrations cloud sont basées sur un système d’authentification. Datadog vous conseille d’utiliser le carré d’intégration cloud principal (AWS, Azure, Google Cloud, etc.) et d’installer l’Agent lorsque cela est possible. Remarque : si vous utilisez uniquement l’Agent, certains tags d’intégration ne seront pas disponibles.

Amazon Web Services

Les tags suivants sont recueillis à partir des intégrations AWS. Remarque : certains tags s’affichent uniquement pour des métriques spécifiques.

IntégrationClés de tag Datadog
Toutesregion
API Gatewayapiid, apiname, method, resource, stage
Auto Scalingautoscalinggroupname, autoscaling_group
Billingaccount_id, budget_name, budget_type, currency, servicename, time_unit
CloudFrontdistributionid
CodeBuildproject_name
CodeDeployapplication, creator, deployment_config, deployment_group, deployment_option, deployment_type, status
DirectConnectconnectionid
DynamoDBglobalsecondaryindexname, operation, streamlabel, tablename
EBSvolumeid, volume-name, volume-type
EC2autoscaling_group, availability-zone, image, instance-id, instance-type, kernel, name, security_group_name
ECSclustername, servicename, instance_id
EFSfilesystemid
ElastiCachecachenodeid, cache_node_type, cacheclusterid, cluster_name, engine, engine_version, prefered_availability-zone, replication_group
ElasticBeanstalkenvironmentname, enviromentid
ELBavailability-zone, hostname, loadbalancername, name, targetgroup
EMRcluster_name, jobflowid
ESdedicated_master_enabled, ebs_enabled, elasticsearch_version, instance_type, zone_awareness_enabled
Firehosedeliverystreamname
Healthevent_category, status, service
IoTactiontype, protocol, rulename
Kinesisstreamname, name, state
KMSkeyid
Lambdafunctionname, resource, executedversion, memorysize, runtime
Machine Learningmlmodelid, requestmode
MQbroker, queue, topic
OpsWorksstackid, layerid, instanceid
Pollyoperation
RDSauto_minor_version_upgrade, dbinstanceclass, dbclusteridentifier, dbinstanceidentifier, dbname, engine, engineversion, hostname, name, publicly_accessible, secondary_availability-zone
Redshiftclusteridentifier, latency, nodeid, service_class, stage, wlmid
Route 53healthcheckid
S3bucketname, filterid, storagetype
SESLes clés de tag sont personnalisées dans AWS.
SNStopicname
SQSqueuename
VPCnategatewayid, vpnid, tunnelipaddress
WorkSpacesdirectoryid, workspaceid

Azure

Les métriques, événements et checks de service des intégrations Azure reçoivent les tags suivants :

IntégrationEspace de nommageClés de tag Datadog
Toutes les intégrations AzureToutescloud_provider, region, kind, type, name, resource_group, tenant_name, subscription_name, subscription_id, status (le cas échéant)
Intégrations VM Azureazure.vm.*host, size, operating_system, availability_zone
Plans Azure App Service(1)azure.web_serverfarms.*per_site_scaling, plan_size, plan_tier, operating_system
Azure App Services Web Apps et Functions(1)azure.app_services.*, azure.functions.*operating_system, server_farm_id, reserved, usage_state, fx_version (applications web Linux uniquement), php_version, dot_net_framework_version, java_version, node_version, python_version
Azure SQL DB(1)azure.sql_servers_databases.*license_type, max_size_mb, server_name, role, zone_redundant

(1)Les tags spécifiques aux ressources sont en version bêta.

Google Cloud Platform

Consultez la documentation de l’intégration Google Cloud Platform.

Intégrations web

Les intégrations web sont basées sur un système d’authentification. Les métriques sont recueillies via des appels d’API. Remarque : les tags CamelCase sont convertis en tirets bas par Datadog (par exemple, TestTag –> test_tag).

Pour aller plus loin