Aperçu

Dans un environnement Kubernetes, utilisez l’instrumentation à étape unique (SSI) pour APM afin d’installer l’Agent Datadog et instrumenter vos applications avec les SDK Datadog en une seule étape.

Exigences

• Kubernetes v1.20+.
• Helm pour déployer l’Opérateur Datadog.
• Kubectl CLI pour installer l’Agent Datadog.
• Compatibilité de l’environnement confirmée selon le guide de compatibilité de l’instrumentation à étape unique.

Activer APM sur vos applications

Suivez ces étapes pour activer l’instrumentation à étape unique sur l’ensemble de votre cluster. Cela envoie automatiquement des traces de toutes les applications écrites dans des langages pris en charge.

Remarque : Pour instrumenter uniquement des espaces de noms ou des pods spécifiques, consultez le ciblage des charges de travail dans Options avancées.

1. Dans Datadog, allez à la page Installer l’Agent Datadog sur Kubernetes.

2. Suivez les instructions à l’écran pour choisir votre méthode d’installation, sélectionner une clé API et configurer l’Opérateur ou le dépôt Helm.

3. Dans la section Configurer datadog-agent.yaml, allez à Configuration supplémentaire > Observabilité de l’application, et activez Instrumentation APM.

4. Déployez l’Agent en utilisant le fichier de configuration généré.

5. Redémarrez vos applications.

Configurez les étiquettes de service unifiées

Les étiquettes de service unifiées (UST) appliquent des étiquettes cohérentes à travers les traces, les métriques et les journaux, facilitant la navigation et la corrélation de vos données d’observabilité. Vous pouvez configurer les UST via l’extraction automatique d’étiquettes (recommandé), par configuration explicite avec ddTraceConfigs, ou dans les manifestes de déploiement.

(Recommandé) Configurez les UST via l’extraction automatique d’étiquettes

Avec SSI, vous pouvez extraire automatiquement les valeurs UST des étiquettes et des métadonnées des pods sans modifier les déploiements individuels. Pour ce faire, configurez kubernetesResourcesLabelsAsTags pour mapper vos étiquettes Kubernetes existantes aux étiquettes de service Datadog.

Remarque : Cette méthode n’est pas compatible avec la configuration distante. Si vous utilisez la configuration distante, consultez Configurer les UST explicitement avec ddTraceConfigs.

Prérequis

Configuration

Remplacez app.kubernetes.io/name dans l’exemple suivant par toute étiquette contenant le nom de votre service (par exemple, service.kubernetes.io/name ou component). Vous pouvez configurer plusieurs étiquettes de cette manière.

datadog:
  # Automatically extract service names from Kubernetes labels
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # Modern Kubernetes label
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true

Avec cette configuration, Datadog définit automatiquement le tag service en utilisant la valeur de l’étiquette app.kubernetes.io/name pour toute charge de travail instrumentée qui inclut cette étiquette.

Configurez les UST explicitement avec ddTraceConfigs

Dans la plupart des cas, la configuration automatique est suffisante. Cependant, si vous avez besoin d’un contrôle granulaire sur les paramètres pour des charges de travail spécifiques, utilisez ddTraceConfigs pour mapper explicitement les étiquettes aux configurations de service:

datadog:
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service
    deployments.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # Explicitly override service name
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV inherited from cluster-level tags above
            # DD_VERSION automatically extracted from image tags

Configurez les UST dans les manifestes de déploiement

Si votre configuration n’utilise pas d’étiquettes adaptées à l’extraction des UST, vous pouvez définir les UST directement dans vos manifestes de déploiement en utilisant des variables d’environnement. Cette approche nécessite de modifier chaque déploiement individuellement, mais offre un contrôle précis.

Pour des instructions complètes, voir configuration des UST pour les services Kubernetes.

Activez les produits et fonctionnalités dépendants du SDK

Après que SSI a chargé le SDK Datadog dans vos applications et activé le traçage distribué, vous pouvez configurer des produits supplémentaires qui dépendent du SDK :

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

Utilisez l’une des méthodes de configuration suivantes :

• Configurez avec le ciblage des workloads (recommandé) :

  Par défaut, l’instrumentation par étape unique instrumente tous les services dans tous les espaces de noms. Utilisez le ciblage des charges de travail pour limiter l’instrumentation à des espaces de noms, pods ou charges de travail spécifiques, et appliquez des configurations personnalisées.

• Définir des variables d’environnement :

  Activez les produits en définissant des variables d’environnement directement dans la configuration de votre application.

Options avancées

Utilisez les options avancées suivantes pour personnaliser le comportement de l’instrumentation à étape unique dans votre environnement. Ces paramètres sont optionnels et généralement nécessaires uniquement dans des configurations spécialisées.

Configurer les modes d’injection

SSI prend en charge plusieurs modes d’injection, qui contrôlent la manière dont les fichiers de l’injecteur et de la bibliothèque APM sont livrés à vos conteneurs d’application. Vous n’avez généralement pas besoin de configurer ce paramètre manuellement. Envisagez de l’ajuster si vous remarquez des délais de démarrage de pod significatifs ou une utilisation des ressources (CPU, mémoire) plus élevée que prévu lors de l’initialisation du pod. Pour en savoir plus sur le fonctionnement de l’injecteur, consultez Comportement de l’injecteur avec l’instrumentation à étape unique.

Avant d’utiliser le mode csi, installez et activez le driver CSI Datadog. Si vous déployez avec Helm, définissez également datadog.csi.enabled: true dans votre datadog-values.yaml. Consultez la documentation du driver CSI pour les étapes d’installation et les exigences spécifiques à l’environnement, telles que GKE Autopilot.

Configurer le mode d’injection globalement

datadog:
  apm:
    instrumentation:
      injectionMode: <mode>

features:
  apm:
    instrumentation:
      injectionMode: <mode>

Configurer le mode d’injection par pod

Pour remplacer le mode d’injection pour un pod spécifique, ajoutez l’annotation suivante à la spécification du pod :

metadata:
  annotations:
    admission.datadoghq.com/apm-inject.injection-mode: "<mode>"

Valeurs prises en charge : init_container, csi.

Cibler des charges de travail spécifiques

Par défaut, SSI instrumente tous les services dans tous les espaces de noms de votre cluster. Selon la version de votre Agent, utilisez l’une des méthodes de configuration suivantes pour affiner quels services sont instrumentés et comment.

   apm:
     instrumentation:
       enabled: true
       disabledNamespaces:
         - "jenkins"
       targets:
         - name: "all-remaining-services"
           ddTraceVersions:
             java: "default"
             python: "3.1.0"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: "login-service_namespace"
          namespaceSelector:
            matchNames:
              - "login-service"
          ddTraceVersions:
            java: "default"
          ddTraceConfigs:
            - name: "DD_PROFILING_ENABLED"  ## profiling is enabled for all services in this namespace
              value: "auto"
        - name: "billing-service_apps"
          namespaceSelector:
            matchLabels:
              app: "billing-service"
          ddTraceVersions:
            python: "3.1.0"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "db-user"
           podSelector:
             matchLabels:
               app: "db-user"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:   ## trace configs set for services in matching pods
             - name: "DD_DATA_STREAMS_ENABLED"
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "login-service-namespace"
           namespaceSelector:
             matchNames:
               - "login-service"
           podSelector:
             matchLabels:
               app: "password-resolver"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           podSelector:
               matchExpressions:
                 - key: app
                   operator: NotIn
                   values:
                   - app1
                   - app2

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "web-apps-with-security"
           namespaceSelector:
             matchNames:
               - "web-apps"
           ddTraceVersions:
             java: "default"
             python: "default"
           ddTraceConfigs:
             - name: "DD_APPSEC_ENABLED"
               value: "true"
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # Add namespaces to instrument
           - default
           - applications

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # Add namespaces to not instrument
           - default
           - applications

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # Add namespaces to instrument
             - namespace_1
             - namespace_2

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Add namespaces to not instrument
            - namespace_1
            - namespace_2

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    # ...
spec:
  template:
    metadata:
      annotations:
        admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"
    spec:
      containers:
        - # ...

   features:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

Changez le registre d’images par défaut

Datadog publie des images de bibliothèques d’instrumentation sur gcr.io, Docker Hub et Amazon ECR :

La variable d’environnement DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY dans la configuration du Datadog Cluster Agent spécifie le registre utilisé par le Contrôleur d’Admission. La valeur par défaut est gcr.io/datadoghq.

Vous pouvez récupérer le SDK depuis un registre différent en le changeant pour docker.io/datadog, public.ecr.aws/datadog, ou une autre URL si vous hébergez les images dans un registre de conteneurs local.

Pour obtenir des instructions sur la modification de votre registre de conteneurs, consultez Changing Your Container Registry.

Utilisez un registre de conteneurs privé

Si votre organisation n’autorise pas les récupérations directes depuis des registres publics (comme gcr.io, docker.io, ou public.ecr.aws), vous pouvez héberger les images Datadog requises en interne et configurer le Contrôleur d’Admission pour les utiliser.

Pour utiliser SSI avec un registre de conteneurs privé :

1. Suivez ces instructions pour mettre en miroir les images de conteneurs de Datadog sur votre registre privé.

   Vous n’avez besoin que des images pour les langages que vous instrumentez. Si vous n’êtes pas certain de celles dont vous avez besoin, voici une configuration de base couvrant la plupart des cas d’utilisation :

   • apm-inject
   • dd-lib-java-init
   • dd-lib-python-init
   • dd-lib-dotnet-init
   • dd-lib-php-init
   • dd-lib-ruby-init
   • dd-lib-js-init

   Vous pouvez trouver ces images sur gcr.io, Docker Hub, ou Amazon ECR Public Gallery.

2. Taguez les images selon votre configuration.

   Les versions que vous reflétez doivent correspondre aux versions configurées dans vos charges de travail, qui peuvent être définies de l’une des manières suivantes :

   • globalement dans la configuration de l’Agent en utilisant ddTraceVersions, ou
   • per-pod utilisant des annotations comme admission.datadoghq.com/java-lib.version.

   Si aucune version n’est explicitement configurée, la version par défaut (0) est utilisée.

   Exemple :

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           ddTraceVersions:
             java: "1"
             python: "3"
   

   Cette configuration nécessite les tags d’image suivantes :

   • apm-inject:0
   • dd-lib-java-init:1
   • dd-lib-python-init:3

3. Mettez à jour la configuration de l’Agent de Cluster pour utiliser votre registre privé.

   Définissez la variable d’environnement DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY dans la configuration de votre Agent de Cluster pour utiliser votre registre privé.

Pour obtenir plus de détails sur la modification de votre registre de conteneurs, consultez Changing Your Container Registry.

Utilisation d’une Interface de Réseau de Conteneurs sur EKS

Lors de l’utilisation d’un CNI comme Calico, les nœuds du plan de contrôle ne peuvent pas initier de connexions réseau au Contrôleur d’Admission de Datadog et signalent une erreur “L’adresse n’est pas autorisée”. Pour utiliser l’instrumentation à Étape Unique, modifiez l’Agent de Cluster de Datadog avec le paramètre useHostNetwork: true.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Supprimez l’instrumentation APM à Étape Unique de votre Agent

Si vous ne souhaitez pas collecter de données de trace pour un service, un hôte, une VM ou un conteneur particulier, complétez les étapes suivantes :

Supprimez l’instrumentation pour des services spécifiques

Pour supprimer l’instrumentation APM et arrêter l’envoi de traces d’un service spécifique, vous pouvez faire l’une des choses suivantes :

Utilisez des règles d’instrumentation pour cibler des charges de travail spécifiques (recommandé)

Avec les règles d’instrumentation (disponibles pour l’Agent v7.64+), vous pouvez activer et désactiver le traçage pour des applications spécifiques. Voir les détails de configuration ici.

Utilisez le Contrôleur d’Admission de Datadog

En alternative, ou pour une version de l’agent qui ne prend pas en charge les règles d’instrumentation, vous pouvez également désactiver la mutation de pod en ajoutant une étiquette à votre pod.

1. Définissez l’étiquette admission.datadoghq.com/enabled: sur "false" pour la spécification du pod :

   spec:
     template:
       metadata:
         labels:
           admission.datadoghq.com/enabled: "false"
   

2. Appliquez la configuration :

   kubectl apply -f /path/to/your/deployment.yaml
   

3. Redémarrez les services pour lesquels vous souhaitez supprimer l’instrumentation.

Supprimez APM pour tous les services sur l’infrastructure

Pour arrêter la production de traces, désinstallez APM et redémarrez l’infrastructure :

Le fichier que vous devez configurer dépend de si vous avez activé l’instrumentation par étape unique avec Datadog Operator ou Helm :

Meilleures pratiques

Après avoir activé SSI, tous les processus pris en charge dans le cluster sont automatiquement instrumentés et commencent à produire des traces en quelques minutes.

Pour contrôler où APM est activé et réduire la surcharge, envisagez les meilleures pratiques suivantes.

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # pin version

targets:
  - name: default-target          # tag any pod *without* an override
    ddTraceVersions:
      java:   "1"   # stay on latest v1.x
      python: "3"   # stay on latest v3.x
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

Dépannage

Si vous rencontrez des problèmes pour activer APM avec SSI, consultez le guide de dépannage SSI.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Activer les métriques d'exécutionDOCUMENTATION En savoir plus sur l'utilisation des ressources des conteneurs initDOCUMENTATION Instrumentez vos applications en utilisant l'injection du SDK localDOCUMENTATION Configurer l'instrumentation à étape unique sur KubernetesCENTRE D'APPRENTISSAGE