Tracing d'un proxy

L’APM Datadog est inclus dans Envoy v1.9.0 et les versions ultérieures.

Activer l’APM Datadog

Remarque : l’exemple de configuration ci-dessous s’applique à Envoy v1.14. D’autres exemples de configuration pour des versions plus anciennes sont disponibles ici

Trois paramètres sont requis pour activer l’APM Datadog dans Envoy :

• Un cluster pour envoyer les traces à l’Agent Datadog
• La configuration de tracing pour activer l’extension de l’APM Datadog
• La configuration de http_connection_manager pour activer le tracing

Un cluster destiné à l’envoi des traces à l’Agent Datadog doit être ajouté.

  clusters:
  ... existing cluster configs ...
  - name: datadog_agent
    connect_timeout: 1s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: datadog_agent
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: localhost
                port_value: 8126

Il est possible que vous soyez contraint de modifier la valeur du paramètre address si Envoy s’exécute dans un conteneur ou un environnement orchestré.

La configuration de tracing d’Envoy doit utiliser l’extension de l’APM Datadog.

tracing:
  http:
    name: envoy.tracers.datadog
    typed_config:
      "@type": type.googleapis.com/envoy.config.trace.v2.DatadogConfig
      collector_cluster: datadog_agent   # comparé au nom du cluster
      service_name: envoy-example        # nom de service défini par l'utilisateur

La valeur collector_cluster doit correspondre au nom fourni pour le cluster de l’Agent Datadog. Le service_name peut être remplacé par une valeur plus adaptée à votre utilisation d’Envoy.

Enfin, les sections http_connection_manager doivent inclure un bloc de configuration supplémentaire pour activer le tracing.

      - name: envoy.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
          tracing: {}

Une fois cette configuration terminée, les requêtes HTTP vers Envoy démarrent et propagent les traces Datadog, qui apparaissent alors dans l’interface de l’APM.

Exemple de configuration Envoy pour la version 1.14

Un exemple de configuration est fourni ici pour montrer le placement des éléments requis pour activer le tracing avec l’APM Datadog.

static_resources:
  listeners:
  - address:
      socket_address:
        address: 0.0.0.0
        port_value: 80
    traffic_direction: OUTBOUND
    filter_chains:
    - filters:
      - name: envoy.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
          generate_request_id: true
          tracing: {}
          codec_type: auto
          stat_prefix: ingress_http
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains:
              - "*"
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service1
          http_filters:
          # Les traces des requêtes de check de santé ne doivent pas être échantillonnées.
          - name: envoy.filters.http.health_check
            typed_config:
              "@type": type.googleapis.com/envoy.config.filter.http.health_check.v2.HealthCheck
              pass_through_mode: false
              headers:
                - exact_match: /healthcheck
                  name: :path
          - name: envoy.filters.http.router
            typed_config: {}
          use_remote_address: true
  clusters:
  - name: service1
    connect_timeout: 0.250s
    type: strict_dns
    lb_policy: round_robin
    http2_protocol_options: {}
    load_assignment:
      cluster_name: service1
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: service1
                port_value: 80
  # Configurer ce cluster avec l'adresse de l'Agent Datadog
  # pour l'envoi des traces.
  - name: datadog_agent
    connect_timeout: 1s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: datadog_agent
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: localhost
                port_value: 8126

tracing:
  # Utiliser le traceur Datadog
  http:
    name: envoy.tracers.datadog
    typed_config:
      "@type": type.googleapis.com/envoy.config.trace.v2.DatadogConfig
      collector_cluster: datadog_agent   # comparé au nom du cluster
      service_name: envoy-example        # nom de service défini par l'utilisateur

admin:
  access_log_path: "/dev/null"
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 8001

Exclure des métriques

Si vous utilisez la configuration dog_statsd d’Envoy pour envoyer les métriques, vous pouvez exclure l’activité du cluster datadog_agent avec ce bloc de configuration supplémentaire :

stats_config:
  stats_matcher:
    exclusion_list:
      patterns:
      - prefix: "cluster.datadog_agent."

Variables d’environnement

Les variables d’environnement dépendent de la version du traceur C++ intégré à Envoy.

Remarque : les variables DD_AGENT_HOST, DD_TRACE_AGENT_PORT et DD_TRACE_AGENT_URL ne s’appliquent pas à Envoy, l’adresse de l’Agent Datadog étant configurée à l’aide des paramètres cluster.

L’APM Datadog peut prendre en charge NGINX en utilisant une combinaison de plug-ins et de configurations. Les instructions ci-dessous utilisent le paquet NGINX disponible dans les référentiels Linux officiels et des binaires pré-compilés pour les plug-ins.

Version open source de NGINX

Installation des plug-ins

Remarque : ce plug-in ne fonctionne pas sur les distributions Linux qui utilisent des versions antérieures de libstdc++, notamment RHEL/Centos 7 et AmazonLinux 1. Une solution consiste à exécuter NGINX à partir d’un conteneur Docker. Un exemple de Dockerfile est disponible ici.

Les plug-ins suivants doivent être installés :

• Plug-in NGINX pour OpenTracing - linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz : installé dans /usr/lib/nginx/modules
• Plug-in Datadog OpenTracing C++ - linux-amd64-libdd_opentracing_plugin.so.gz : installé à un emplacement accessible pour NGINX, p. ex. /usr/local/lib

Commandes pour télécharger et installer ces modules :

# Récupérer le dernier numéro de version depuis GitHub.
get_latest_release() {
  wget -qO- "https://api.github.com/repos/$1/releases/latest" |
    grep '"tag_name":' |
    sed -E 's/.*"([^"]+)".*/\1/';
}
NGINX_VERSION=1.17.3
OPENTRACING_NGINX_VERSION="$(get_latest_release opentracing-contrib/nginx-opentracing)"
DD_OPENTRACING_CPP_VERSION="$(get_latest_release DataDog/dd-opentracing-cpp)"
# Installer le plug-in NGINX pour OpenTracing
https://github.com/opentracing-contrib/nginx-opentracing/releases/download/${OPENTRACING_NGINX_VERSION}/linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz
tar zxf linux-amd64-nginx-${NGINX_VERSION}-ngx_http_module.so.tgz -C /usr/lib/nginx/modules
# Installer le plug-in C++ Datadog pour Opentracing
wget https://github.com/DataDog/dd-opentracing-cpp/releases/download/${DD_OPENTRACING_CPP_VERSION}/linux-amd64-libdd_opentracing_plugin.so.gz
gunzip linux-amd64-libdd_opentracing_plugin.so.gz -c > /usr/local/lib/libdd_opentracing_plugin.so

Configuration de NGINX

La configuration de NGINX doit charger le module OpenTracing.

# Charger le module OpenTracing
load_module modules/ngx_http_opentracing_module.so;

Le bloc http active le module OpenTracing et charge le traceur Datadog :

    opentracing on; # Activer OpenTracing.
    opentracing_tag http_user_agent $http_user_agent; # Ajouter un tag à chaque trace.
    opentracing_trace_locations off; # Émettre une seule span par requête.

    # Charger l'implémentation de tracing Datadog et le fichier de configuration donné.
    opentracing_load_tracer /usr/local/lib/libdd_opentracing_plugin.so /etc/dd-config.json;

Le bloc log_format with_trace_id assure la corrélation entre les logs et les traces. Consultez le fichier d’exemple de configuration NGINX pour découvrir le format complet à utiliser. La valeur $opentracing_context_x_datadog_trace_id enregistre l’ID de la trace, tandis que la valeur $opentracing_context_x_datadog_parent_id enregistre l’ID de la span.

Ajoutez les lignes suivantes au bloc location dans le serveur où vous souhaitez effectuer le tracing :

            opentracing_operation_name "$request_method $uri";
            opentracing_propagate_context;

Un fichier de configuration pour l’implémentation du tracing Datadog est également requis :

{
  "environment": "prod",
  "service": "nginx",
  "operation_name_override": "nginx.handle",
  "agent_host": "localhost",
  "agent_port": 8126
}

La valeur service peut être modifiée afin d’être adaptée à votre utilisation de NGINX. Il est possible que vous soyez contraint de modifier la valeur agent_host si NGINX s’exécute dans un conteneur ou un environnement orchestré.

Exemples complets :

• nginx.conf
• dd-config.json

Une fois cette configuration terminée, les requêtes HTTP transmises à NGINX initieront et propageront les traces Datadog, qui s’afficheront dans l’interface graphique de l’APM.

NGINX et FastCGI

Lorsque l’emplacement dessert un backend FastCGI au lieu de HTTP, le bloc location doit utiliser opentracing_fastcgi_propagate_context au lieu de opentracing_propagate_context.

NGINX Ingress Controller pour Kubernetes

Les versions 0.23.0 et ultérieures du contrôleur Kubernetes ingress-nginx incluent le plug-in NGINX pour OpenTracing.

Pour activer ce plug-in, créez ou modifiez une ConfigMap en définissant enable-opentracing: "true" et datadog-collector-host, à savoir l’emplacement où les traces doivent être envoyées. Le nom de la ConfigMap sera cité explicitement par l’argument de ligne de commande du conteneur du contrôleur nginx-ingress. Par défaut, sa valeur est --configmap=$(POD_NAMESPACE)/nginx-configuration. Si ingress-nginx a été installé avec une chart helm, le nom de cette ConfigMap suivra le modèle suivant : Nom-Version-nginx-ingress-controller.

Le contrôleur Ingress gère les fichiers nginx.conf et /etc/nginx/opentracing.json. Le tracing est activé pour tous les blocs location.

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
  labels:
    app.kubernetes.io/name: ingress-nginx
    app.kubernetes.io/part-of: ingress-nginx
data:
  enable-opentracing: "true"
  datadog-collector-host: $HOST_IP
  # Valeurs par défaut
  # datadog-service-name: "nginx"
  # datadog-collector-port: "8126"
  # datadog-operation-name-override: "nginx.handle"

En outre, vérifiez que les spécifications de pod de votre contrôleur nginx-ingress définissent la variable d’environnement HOST_IP. Ajoutez cette entrée au bloc env: qui contient les variables d’environnement POD_NAME et POD_NAMESPACE.

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP

Pour définir un nom de service différent selon le contrôleur Ingress à l’aide d’annotations :

  nginx.ingress.kubernetes.io/configuration-snippet: |
            opentracing_tag "service.name" "custom-service-name";

Ce qui précède remplace le nom de service par défaut nginx-ingress-controller.ingress-nginx.

Datadog surveille chaque aspect de votre environnement Istio, afin que vous puissiez :

• Plonger au cœur des traces distribuées pour les applications qui effectuent des transactions sur le maillage avec l’APM (voir ci-dessous).
• Évaluer la santé d’Envoy et du plan de contrôle Istio grâce aux logs.
• Consulter en détail les performances de votre maillage de services avec des métriques sur les requêtes, la bande passante et la consommation de ressources
• Mapper les communications réseau entre les conteneurs, pods et services sur le maillage avec la solution Network Performance Monitoring

Pour en savoir plus sur la surveillance de votre environnement Istio avec Datadog, consultez l’article du blog à ce sujet (en anglais).

Configuration

L’APM Datadog est disponible pour Istio 1.1.3 et ultérieur sur les clusters Kubernetes.

Installation de l’Agent Datadog

1. Installez l’Agent Datadog.
2. Vérifiez que l’APM est activé pour votre Agent.
3. Supprimez la mise en commentaire du paramètre hostPort pour que les sidecars Istio puissent se connecter à l’Agent et envoyer des traces.

Installation et configuration d’Istio

Pour activer l’APM Datadog, une installation Istio personnalisée est requise afin de configurer deux options supplémentaires.

• --set values.global.proxy.tracer=datadog
• --set values.pilot.traceSampling=100.0

istioctl manifest apply --set values.global.proxy.tracer=datadog --set values.pilot.traceSampling=100.0

Les traces sont générées lorsque l’espace de nommage du pod dispose de la fonctionnalité d’injection de sidecar. Cette opération s’effectue en ajoutant l’étiquette istio-injection=enabled.

kubectl label namespace example-ns istio-injection=enabled

Les traces sont générées lorsqu’Istio parvient à déterminer si le trafic utilise un protocole basé sur HTTP. Par défaut, Istio effectue automatiquement cette vérification. Vous pouvez la configurer manuellement en nommant les ports dans le service et le déploiement de votre application. Reportez-vous à la section relative à la sélection de protocole de la documentation Istio (en anglais) pour en savoir plus.

Par défaut, le nom de service utilisé lors de la création des traces est généré à partir de l’espace de nommage et du nom du déploiement. Vous pouvez le définir manuellement en ajoutant une étiquette app au modèle de pod du déploiement :

template:
  metadata:
    labels:
      app: <NOM_SERVICE>

Pour les CronJobs, l’étiquette app doit être ajoutée au modèle du job, car le nom généré provient du Job, et non du CronJob de niveau supérieur.

Variables d’environnement

Les variables d’environnement des sidecars Istio peuvent être configurées pour chaque déploiement, à l’aide de l’annotation apm.datadoghq.com/env.

    metadata:
      annotations:
        apm.datadoghq.com/env: '{ "DD_ENV": "prod", "DD_TRACE_ANALYTICS_ENABLED": "true" }'

Les variables d’environnement disponibles dépendent de la version du traceur C++ intégré au proxy du sidecar Istio.

Déploiement et service

Si les Agents de votre cluster s’exécutent en tant que déploiement et service au lieu du DaemonSet par défaut, une option supplémentaire est alors nécessaire pour spécifier l’adresse DNS et le port de l’Agent. Pour un service datadog-agent dans l’espace de nommage default, l’adresse a pour valeur datadog-agent.default.svc.cluster.local:8126.

• --set values.global.tracer.datadog.address=datadog-agent.default:8126

Si l’authentification TLS mutuelle est activée pour le cluster, alors le déploiement de l’Agent doit désactiver l’injection de sidecar. De plus, vous devez ajouter une stratégie de trafic qui désactive l’authentification TLS.

Cette annotation est ajoutée au modèle de déploiement de l’Agent.

  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"

Pour la version v1.4.x d’Istio, la stratégie de trafic peut être configurée à l’aide d’une DestinationRule. La version v1.5.x et les versions plus récentes d’Istio ne nécessitent pas de stratégie de trafic supplémentaire.

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: datadog-agent
  namespace: istio-system
spec:
  host: datadog-agent.default.svc.cluster.local
  trafficPolicy:
    tls:
      mode: DISABLE

Le processus de sélection automatique du protocole peut déterminer que le trafic entre le sidecar et l’Agent s’effectue via HTTP, et ainsi activer le tracing. Cette fonction peut être désactivée en utilisant la sélection manuelle du protocole du service spécifique. Le nom du port dans le service datadog-agent peut être remplacé par tcp-traceport. Si vous utilisez Kubernetes 1.18+, vous pouvez ajouter appProtocol: tcp à la spécification du port.