Collecte de traces Kubernetes

Pour commencer à recueillir les traces de votre application, vous devez exécuter l’Agent Datadog dans votre cluster Kubernetes.

Configuration

Vous pouvez configurer l’admission des traces de l’Agent à l’aide de IP:Port, d’un socket de domaine Unix ou de ces deux options. L’Agent peut recevoir des traces à partir de ces deux configurations, si nécessaire.

Le pipeline de dépannage de l'APM : le traceur envoie des données de trace et de métrique depuis le pod de l'application vers le pod de l'Agent, qui envoie à son tour ces données au backend Datadog, afin qu'elles s'affichent dans l'interface Datadog.

Configurer l’Agent Datadog pour qu’il accepte les traces

  • Si vous ne l’avez pas déjà fait, installez le chart Helm.
  • Mettez à jour votre fichier values.yaml avec la configuration d’APM suivante :
    datadog:
      ## Enable apm agent and provide custom configs
      apm:
        # datadog.apm.portEnabled -- Enable APM over TCP communication (port 8126 by default)
        ## ref: https://docs.datadoghq.com/agent/kubernetes/apm/
        portEnabled: true
    

Ensuite, mettez à jour votre chart Helm Datadog à l’aide de la commande suivante : helm upgrade -f values.yaml <NOM_VERSION> datadog/datadog. Si vous n’avez pas défini votre système d’exploitation dans values.yaml, ajoutez --set targetSystem=linux ou --set targetSystem=windows à cette commande.

  • Si vous ne l’avez pas déjà fait, installez le chart Helm.
  • Mettez à jour votre fichier values.yaml avec la configuration d’APM suivante :
    datadog:
      ## Enable apm agent and provide custom configs
      apm:
        # datadog.apm.socketEnabled -- Enable APM over Socket (Unix Socket or windows named pipe)
        ## ref: https://docs.datadoghq.com/agent/kubernetes/apm/
        socketEnabled: true
    

Cette configuration crée un répertoire sur le host et le monte dans l’Agent. L’Agent crée ensuite un fichier de socket /var/run/datadog/apm.socket et effectue une écoute sur ce fichier. Les pods d’application peuvent alors être montés de la même façon sur ce volume et rédiger des données sur ce socket. Vous pouvez modifier le chemin et le socket avec les valeurs datadog.apm.hostSocketPath et datadog.apm.socketPath.

Ensuite, mettez à jour votre chart Helm Datadog à l’aide de la commande suivante : helm upgrade -f values.yaml <NOM_VERSION> datadog/datadog. Si vous n’avez pas défini votre système d’exploitation dans values.yaml, ajoutez --set targetSystem=linux ou --set targetSystem=windows à cette commande.

Pour activer la collecte de traces APM, ouvre le fichier de configuration DaemonSet et modifiez les éléments suivants :

  • Autorisez la réception de données sur le port 8126 (transmission du trafic du host à l’Agent) dans le conteneur trace-agent :

      # (...)
      containers:
        - name: trace-agent
          # (...)
          ports:
            - containerPort: 8126
              hostPort: 8126
              name: traceport
              protocol: TCP
      # (...)
    
  • Si vous utilisez une ancienne version de l’Agent (7.17 ou antérieure), en plus des étapes ci-dessus, vous devez définir les variables DD_APM_NON_LOCAL_TRAFFIC et DD_APM_ENABLED sur true dans la section env du manifeste de l’Agent de trace datadog.yaml :

      # (...)
      containers:
        - name: trace-agent
          # (...)
          env:
            - name: DD_APM_ENABLED
              value: 'true'
            - name: DD_APM_NON_LOCAL_TRAFFIC
              value: "true"
            # (...)
    

Pour activer la collecte de traces APM, ouvre le fichier de configuration DaemonSet et modifiez les éléments suivants :

  # (...)
  containers:
  - name: trace-agent
    # (...)
    env:
    - name: DD_APM_ENABLED
      value: "true"
    - name: DD_APM_RECEIVER_SOCKET
      value: "/var/run/datadog/apm.socket"
  # (...)
    volumeMounts:
    - name: apmsocket
      mountPath: /var/run/datadog/
  volumes:
  - hostPath:
      path: /var/run/datadog/
      type: DirectoryOrCreate
  # (...)

Cette configuration crée un répertoire sur le host et le monte dans l’Agent. L’Agent crée ensuite un fichier de socket dans ce répertoire avec la valeur DD_APM_RECEIVER_SOCKET de /var/run/datadog/apm.socket et effectue une écoute sur ce fichier. Les pods d’application peuvent alors être montés de la même façon sur ce volume et rédiger des données sur ce socket.

Modifiez votre manifeste datadog-agent.yaml en indiquant ce qui suit :

agent:
  image:
    name: "gcr.io/datadoghq/agent:latest"
  apm:
    enabled: true
    hostPort: 8126
site: <SITE_DATADOG>

Remplacez <SITE_DATADOG> par (valeur par défaut : datadoghq.com).

Consultez l’exemple de manifeste avec activation de l’APM et de la collecte des métriques pour un exemple complet.

Ensuite, appliquez la nouvelle configuration :

$ kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

Modifiez votre manifeste datadog-agent.yaml en indiquant ce qui suit :

agent:
  image:
    name: "gcr.io/datadoghq/agent:latest"
  apm:
    enabled: true
    unixDomainSocket:
      enabled: true
site: <SITE_DATADOG>

Remplacez <SITE_DATADOG> par (valeur par défaut : datadoghq.com).

Consultez l’exemple de manifeste avec activation de l’APM et de la collecte des métriques pour un exemple complet.

Ensuite, appliquez la nouvelle configuration :

$ kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

Remarque : sur minikube, vous pouvez recevoir une erreur Unable to detect the kubelet URL automatically. Si c’est le cas, définissez DD_KUBELET_TLS_VERIFY=false.

Configurer les pods de votre application pour communiquer avec l’Agent Datadog

Si vous envoyez des traces à l’Agent à l’aide de (<ADRESSE_IP>:8126), transmettez cette adresse aux pods de votre application, que ce soit automatiquement avec le contrôleur d’admission Datadog ou manuellement avec l’API Downward (afin de récupérer l’IP du host). La variable d’environnement DD_AGENT_HOST doit pointer sur status.hostIP pour le conteneur d’application :

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<NOM_CONTENEUR>"
        image: "<IMAGE_CONTENEUR>/<TAG>"
        env:
          - name: DD_AGENT_HOST
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP

Si vous envoyez des traces à l’Agent à l’aide d’un socket de domaine Unix, montez le répertoire du host dans lequel le socket se trouve (le répertoire créé par l’Agent) sur le conteneur de l’application, et spécifiez le chemin du socket avec DD_TRACE_AGENT_URL :

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<NOM_CONTENEUR>"
        image: "<IMAGE_CONTENEUR>/<TAG>"
        env:
        - name: DD_TRACE_AGENT_URL
          value: 'unix:///var/run/datadog/apm.socket'
        volumeMounts:
        - name: apmsocketpath
          mountPath: /var/run/datadog
        #(...)
      volumes:
        - hostPath:
            path: /var/run/datadog/
          name: apmsocketpath

Configurer les traceurs de votre application pour générer des traces

Après avoir configuré votre Agent Datadog de façon à ce qu’il recueille des traces et transmis aux pods de votre application l’emplacement vers lequel envoyer les traces, installez le traceur Datadog sur votre application afin de générer des traces. Une fois cette étape terminée, le traceur envoie automatiquement les traces vers l’endpoint DD_AGENT_HOST (pour IP:Port) ou DD_TRACE_AGENT_URL (pour un socket de domaine Unix) relatif.

Consultez la documentation sur l’APM propre à votre langage pour obtenir davantage d’exemples.

Remarque : les traceurs .NET et PHP ne prennent actuellement pas en charge l’envoi de traces sur un socket de domaine Unix. Pour obtenir les dernières informations à ce sujet, contactez l’assistance.

Variables d’environnement de l’Agent

Remarque : Datadog vous conseille d’utiliser le tagging de service unifié lorsque vous assignez des tags. Le tagging de service unifié permet de lier les données de télémétrie Datadog entre elles via trois tags standards : env, service et version. Pour découvrir comment configurer le tagging unifié pour votre environnement, consultez la documentation dédiée au tagging de service unifié.

Voici la liste de l’ensemble des variables d’environnement disponibles pour le tracing lorsque l’Agent est exécuté dans Kubernetes :

Variable d’environnementDescription
DD_API_KEYClé d’API Datadog
DD_PROXY_HTTPSConfigure l’URL utilisée par le proxy.
DD_APM_REPLACE_TAGSNettoye les données sensibles des tags de vos spans.
DD_HOSTNAMEDéfinit manuellement le hostname à utiliser pour les métriques si la détection automatique échoue, ou lors de l’exécution de l’Agent de cluster Datadog.
DD_DOGSTATSD_PORTDéfinit le port DogStatsD.
DD_APM_RECEIVER_SOCKETRecueillez vos traces via un socket de domaine Unix afin de ne pas tenir compte du port et du hostname configurés, le cas échéant. Cette variable est désactivée par défaut. Si vous l’activez, vous devez indiquer un fichier de socket valide.
DD_BIND_HOSTDéfinit le hostname StatsD et le hostname du récepteur.
DD_LOG_LEVELDéfinit le niveau de journalisation (trace, debug, info, warn, error, critical ou off).
DD_APM_ENABLEDLorsque ce paramètre est défini sur true, l’Agent Datadog accepte les métriques de trace. Valeur par défaut : true (Agent 7.18+)
DD_APM_CONNECTION_LIMITDéfinit la limite maximale de connexion pour un intervalle de 30 secondes.
DD_APM_DD_URLDéfinissez l’endpoint de l’API Datadog sur l’adresse vers laquelle vos traces sont envoyées : https://trace.agent.. Valeur par défaut : https://trace.agent.datadoghq.com.
DD_APM_RECEIVER_PORTPort sur lequel le récepteur de traces de l’Agent Datadog effectue son écoute. Valeur par défaut : 8126.
DD_APM_NON_LOCAL_TRAFFICAutorise le trafic non local pour le tracing depuis d’autres conteneurs. Valeur par défaut : true (Agent 7.18+)
DD_APM_IGNORE_RESOURCESConfigure les ressources que l’Agent doit ignorer. Utilisez des expressions régulières séparées par des virgules, par exemple : GET /ignore-me,(GET|POST) /and-also-me.
DD_ENVDéfinit le paramètre env global pour toutes les données générées par l’Agent. Si env n’est pas présent dans vos données de trace, cette variable est utilisée. Consultez la configuration de l’environnement APM pour en savoir plus.

Variables d’environnement d’opérateur

Variable d’environnementDescription
agent.apm.enabledPermet d’activer l’APM et le tracing sur le port 8126. Consultez la documentation Datadog relative à Docker.
agent.apm.envL’Agent Datadog prend en charge de nombreuses variables d’environnement.
agent.apm.hostPortNuméro du port à exposer sur le host. Lorsque spécifié, doit correspondre à un numéro de port valide, 0 < x < 65536. Si HostNetwork est spécifié, la valeur doit correspondre à ContainerPort. La plupart des conteneurs ne nécessitent pas ce paramètre.
agent.apm.resources.limitsIndique la quantité maximale de ressources de calcul autorisées. Pour en savoir plus, consultez la documentation Kubernetes (en anglais).
agent.apm.resources.requestsIndique la quantité minimale de ressources de calcul requises. Si requests n’est pas défini pour un conteneur, la valeur limits est utilisée par défaut si celle-ci est explicitement définie. Sinon, une valeur définie au niveau de l’implémentation est utilisée. Pour en savoir plus, consultez la documentation Kubernetes (en anglais).

Pour aller plus loin