Aperçu

Le balisage de service unifié relie la télémétrie Datadog en utilisant trois balises réservées : env, service et version.

Avec ces trois tags, vous pouvez :

• Identifiez l’impact du déploiement avec des métriques de trace et de conteneur filtrées par version
• Naviguez sans effort à travers les traces, les métriques et les journaux avec des balises cohérentes
• Affichez les données de service en fonction de l’environnement ou de la version de manière unifiée

Notes :

• La balise version est censée changer à chaque nouveau déploiement d’application. Deux versions différentes du code de votre application doivent avoir des balises version distinctes.
• Le service officiel d’un journal adopte par défaut le short-image du conteneur, en l’absence d’une configuration des journaux Autodiscovery. Pour remplacer le service officiel d’un journal, ajoutez des étiquettes Docker/annotations de pod d’Autodécouverte. Par exemple : "com.datadoghq.ad.logs"='[{"service": "service-name"}]'
• Les informations sur l’hôte sont exclues pour les spans de base de données et de cache, car l’hôte associé au span n’est pas celui de la base de données ou du cache.

Exigences

• Le balisage de service unifié nécessite la configuration d’un Agent Datadog qui est 6.19.x/7.19.x ou supérieur.

• Le balisage de service unifié nécessite une version SDK qui prend en charge de nouvelles configurations des balises réservées. Plus d’informations peuvent être trouvées par langue dans les instructions d’installation.

• Le balisage de service unifié nécessite des connaissances sur la configuration des balises. Si vous n’êtes pas certain de la manière de configurer les balises, consultez la documentation Démarrer avec le balisage et Attribution des balises avant de procéder à la configuration.

Configuration

Pour commencer la configuration du tagging de service unifié, choisissez votre environnement :

• Conteneurisé
• Non conteneurisé
• Sans serveur
• OpenTelemetry

Environnement conteneurisé

Dans les environnements conteneurisés, env, service et version sont définis par les variables d’environnement ou les étiquettes du service (par exemple, les étiquettes de déploiement et de pod Kubernetes, les étiquettes de conteneur Docker). L’Agent Datadog détecte cette configuration de balisage et l’applique aux données qu’il collecte à partir des conteneurs.

Pour configurer le tagging de service unifié dans un environnement conteneurisé :

1. Activer Autodécouverte. Cela permet à l’Agent Datadog d’identifier automatiquement les services fonctionnant sur un conteneur spécifique et de collecter des données à partir de ces services pour associer les variables d’environnement aux balises env, service, et version.

2. Si vous utilisez Docker, assurez-vous que l’Agent peut accéder à la socket Docker de votre conteneur. Cela permet à l’Agent de détecter les variables d’environnement et de les associer aux balises standard.

3. Configurez votre environnement en fonction de votre service d’orchestration de conteneurs, que ce soit par une configuration complète ou partielle comme détaillé ci-dessous.

Configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    tags.datadoghq.com/env: "<ENV>"
    tags.datadoghq.com/service: "<SERVICE>"
    tags.datadoghq.com/version: "<VERSION>" 
...
template:
  metadata:
    labels:
      tags.datadoghq.com/env: "<ENV>"
      tags.datadoghq.com/service: "<SERVICE>"
      tags.datadoghq.com/version: "<VERSION>" 
  containers:
  -  ...
     env:
          - name: DD_ENV
            valueFrom:
              fieldRef:
                fieldPath: metadata.labels['tags.datadoghq.com/env']
          - name: DD_SERVICE
            valueFrom:
              fieldRef:
                fieldPath: metadata.labels['tags.datadoghq.com/service']
          - name: DD_VERSION 
            valueFrom: 
              fieldRef: 
                fieldPath: metadata.labels['tags.datadoghq.com/version']

  containers:
  -  ...
     env:
         - name: OTEL_RESOURCE_ATTRIBUTES
           value: "service.name=<SERVICE>,service.version=<VERSION>,deployment.environment=<ENV>"
         - name: OTEL_SERVICE_NAME
           value: "<SERVICE>"

template:
  metadata:
    labels:
      tags.datadoghq.com/env: "<ENV>"
      tags.datadoghq.com/service: "<SERVICE>"
      tags.datadoghq.com/version: "<VERSION>" 

tags.datadoghq.com/<container-name>.env
tags.datadoghq.com/<container-name>.service
tags.datadoghq.com/<container-name>.version 

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    tags.datadoghq.com/env: "<ENV>"
    tags.datadoghq.com/service: "<SERVICE>"
    tags.datadoghq.com/version: "<VERSION>" 
spec:
  template:
    metadata:
      labels:
        tags.datadoghq.com/env: "<ENV>"
        tags.datadoghq.com/service: "<SERVICE>"
        tags.datadoghq.com/version: "<VERSION>" 

containers:
-  ...
    env:
        - name: DD_ENV
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['tags.datadoghq.com/env']
        - name: DD_SERVICE
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['tags.datadoghq.com/service']
        - name: DD_VERSION 
          valueFrom: 
            fieldRef: 
              fieldPath: metadata.labels['tags.datadoghq.com/version'] 

ENV DD_SERVICE <SERVICE>
ENV DD_VERSION <VERSION> 

LABEL com.datadoghq.tags.service="<SERVICE>"
LABEL com.datadoghq.tags.version="<VERSION>" 

docker run -e DD_ENV=<ENV> -l com.datadoghq.tags.env=<ENV> ...

docker run -e DD_ENV="<ENV>" \
           -e DD_SERVICE="<SERVICE>" \
           -e DD_VERSION="<VERSION>" \ 
           -l com.datadoghq.tags.env="<ENV>" \
           -l com.datadoghq.tags.service="<SERVICE>" \
           -l com.datadoghq.tags.version="<VERSION>" \ 
           ...

com.datadoghq.tags.env
com.datadoghq.tags.service
com.datadoghq.tags.version 

"environment": [
  {
    "name": "DD_ENV",
    "value": "<ENV>"
  },
  {
    "name": "DD_SERVICE",
    "value": "<SERVICE>"
  },
  {
    "name": "DD_VERSION",
    "value": "<VERSION>"
  }
   
],
"dockerLabels": {
  "com.datadoghq.tags.env": "<ENV>",
  "com.datadoghq.tags.service": "<SERVICE>",
  "com.datadoghq.tags.version": "<VERSION>"
}

"dockerLabels": {
  "com.datadoghq.tags.env": "<ENV>",
  "com.datadoghq.tags.service": "<SERVICE>",
  "com.datadoghq.tags.version": "<VERSION>"
}

Environnement non conteneurisé

En fonction de la manière dont vous construisez et déployez les binaires ou exécutables de vos services, vous pouvez avoir plusieurs options disponibles pour définir des variables d’environnement. Puisque vous pouvez exécuter un ou plusieurs services par hôte, Datadog recommande de limiter ces variables d’environnement à un seul processus.

Afin de former un point de configuration unique pour l’ensemble des données de télémétrie émises directement depuis le runtime de vos services pour les traces, les logs, les ressources RUM, les tests Synthetic, les métriques StatsD ou les métriques système, vous pouvez :

1. Exportez les variables d’environnement dans la commande pour votre exécutable :

   DD_ENV=<env> DD_SERVICE=<service> DD_VERSION=<version> /bin/my-service
   

2. Ou utilisez Chef, Ansible ou un autre outil d’orchestration pour peupler le fichier de configuration systemd ou initd d’un service avec les variables d’environnement DD. Lorsque le processus de service démarre, il a accès à ces variables.

   Lors de la configuration de vos traces pour le tagging de service unifié :

   1. Configurez le SDK Datadog avec DD_ENV pour garder la définition de env plus proche de l’application qui génère les traces. Cette méthode permet au tag env d’être automatiquement dérivé d’un tag dans les métadonnées du span.

   2. Configurez les spans avec DD_VERSION pour ajouter la version à tous les spans qui relèvent du service appartenant au SDK (généralement DD_SERVICE). Cela signifie que si votre service crée des spans avec le nom d’un service externe, ces spans ne reçoivent pas version comme tag.

      Tant que la version est présente dans les spans, elle est ajoutée aux métriques de trace générées à partir de ces spans. La version peut être ajoutée manuellement dans le code ou automatiquement par le SDK Datadog. Lorsqu’elles sont configurées, celles-ci sont utilisées par les clients APM et DogStatsD pour étiqueter les données de trace et les métriques StatsD avec env, service et version. Si activé, le SDK Datadog injecte également les valeurs de ces variables dans vos journaux.

      Remarque : Il ne peut y avoir qu’un service par span. Les métriques de trace ont généralement également un seul service. Cependant, si vous avez un service différent défini dans les étiquettes de vos hôtes, cette étiquette de service configurée apparaît sur toutes les métriques de trace émises depuis cet hôte.

   Si vous utilisez des journaux et des traces connectés, activez l’injection automatique des journaux si cela est pris en charge par votre SDK Datadog. Ensuite, le SDK Datadog injecte automatiquement env, service et version dans vos journaux, éliminant ainsi la configuration manuelle pour ces champs ailleurs.

   Si vous utilisez des RUM et des traces connectés, spécifiez l’application du navigateur dans le champ service, définissez l’environnement dans le champ env et listez les versions dans le champ version de votre fichier d’initialisation.

   Lorsque vous créez une application RUM, confirmez les noms env et service.

   Si vous utilisez des tests de navigateur synthétiques connectés et des traces, spécifiez une URL pour envoyer des en-têtes dans la section Intégration APM pour les tests de navigateur de la page des paramètres d’intégration.

   Vous pouvez utiliser * pour des caractères génériques, par exemple : https://*.datadoghq.com.

   Les balises sont ajoutées en mode append-only pour des métriques StatsD personnalisées. Par exemple, si vous avez deux valeurs différentes pour env, les métriques sont étiquetées avec les deux environnements. Il n’y a pas d’ordre dans lequel une balise remplace une autre du même nom.

   Si votre service a accès à DD_ENV, DD_SERVICE et DD_VERSION, alors le client DogStatsD ajoute automatiquement les balises correspondantes à vos métriques personnalisées.

   Remarque : Les clients Datadog DogStatsD pour .NET et PHP ne prennent pas en charge cette fonctionnalité.

   Vous pouvez ajouter des balises env et service à vos métriques d’infrastructure. Dans des contextes non conteneurisés, le balisage pour les métriques de service est configuré au niveau de l’Agent.

   Parce que cette configuration ne change pas pour chaque invocation du processus d’un service, l’ajout de version n’est pas recommandé.

   Un service par hôte

   Définissez la configuration suivante dans le fichier de configuration principal de l’Agent :

   env: <ENV>
   tags:
     - service:<SERVICE>
   

   Cette configuration garantit un balisage cohérent de env et service pour toutes les données émises par l’Agent.

   Plusieurs services par hôte

   Définissez la configuration suivante dans le fichier de configuration principal de l’Agent :

   env: <ENV>
   

   Pour obtenir des balises service uniques sur les métriques CPU, mémoire et I/O disque au niveau du processus, configurez un contrôle de processus dans le dossier de configuration de l’Agent (par exemple, dans le dossier conf.d sous process.d/conf.yaml) :

   init_config:
   instances:
       - name: web-app
         search_string: ["/bin/web-app"]
         exact_match: false
         service: web-app
       - name: nginx
         search_string: ["nginx"]
         exact_match: false
         service: nginx-web-app
   

   Remarque : Si vous avez déjà une balise service définie globalement dans le fichier de configuration principal de votre Agent, les métriques de processus sont étiquetées avec deux services. Étant donné que cela peut prêter à confusion lors de l’interprétation des métriques, il est recommandé de configurer la balise service uniquement dans la configuration de la vérification du processus.

Environnement sans serveur

Pour en savoir plus sur les fonctions AWS Lambda, découvrez comment associer vos données de télémétrie Lambda à l’aide de tags.

OpenTelemetry

Lorsque vous utilisez OpenTelemetry, mappez les attributs de ressource suivants à leurs conventions correspondantes dans Datadog :

1 : deployment.environment est obsolète au profit de deployment.environment.name dans les conventions sémantiques OpenTelemetry v1.27.0.
2 : deployment.environment.name est pris en charge dans Datadog Agent 7.58.0+ et Datadog Exporter v0.110.0+.

export OTEL_RESOURCE_ATTRIBUTES="service.name=my-service,deployment.environment=production,service.version=1.2.3"

from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider

resource = Resource(attributes={
   "service.name": "<SERVICE>",
   "deployment.environment": "<ENV>",
   "service.version": "<VERSION>"
})
tracer_provider = TracerProvider(resource=resource)

processors:
  transform:
    trace_statements:
      - context: resource
        statements:
          - set(attributes["service.name"], "my-service")
          - set(attributes["deployment.environment"], "production")
          - set(attributes["service.version"], "1.2.3")
...

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Apprendre à utiliser les tags dans l'application DatadogDOCUMENTATION Utiliser des tags version dans l'APM Datadog pour surveiller les déploiementsDOCUMENTATION En savoir plus sur AutodiscoveryBLOG