Amazon ECS sur AWS Fargate

Agent Check Check de l'Agent

Supported OS Linux Mac OS Windows

Integrationv2.14.1

Présentation

Remarque : cette page concerne l’intégration ECS Fargate. Pour EKS Fargate, consultez la documentation de Datadog dédiée à l’intégration EKS Fargate.

Recueillez des métriques depuis tous vos conteneurs s’exécutant dans ECS Fargate :

  • Recueillez des métriques sur les limites et l’utilisation du processeur et de la mémoire.
  • Surveillez vos applications exécutées sur Fargate grâce aux intégrations ou aux métriques custom de Datadog.

L’Agent Datadog récupère des métriques sur les conteneurs des définitions de tâches via l’endpoint des métadonnées de tâches d’ECS. D’après la documentation ECS concernant cet endpoint :

Cet endpoint renvoie des statistiques Docker au format JSON pour tous les conteneurs associés à la tâche. Pour en savoir plus sur les statistiques transmises, consultez la section ContainerStats de la documentation relative à l’API Docker (en anglais).

L’endpoint Task Metadata est uniquement disponible au sein de la définition de la tâche. Ainsi, l’Agent Datadog doit être exécuté en tant que conteneur supplémentaire dans la définition de la tâche.

Pour recueillir des métriques, il vous suffit de définir la variable d’environnement ECS_FARGATE sur "true" dans la définition de la tâche.

Configuration

Les étapes ci-dessous détaillent la configuration de l’Agent de conteneur Datadog au sein d’AWS ECS Fargate. Attention : la version 6.11 de l’Agent Datadog, ou une version ultérieure, est requise pour profiter de l’ensemble des fonctionnalités de l’intégration Fargate.

Les tâches sans l’Agent Datadog envoient tout de même des métriques via Cloudwatch. Néanmoins, l’Agent est requis pour utiliser Autodiscovery, obtenir des métriques détaillées sur les conteneurs, exploiter le tracing, etc. En outre, les métriques Cloudwatch sont moins granulaires et entraînent une latence plus élevée que les métriques transmises directement par l’Agent Datadog.

Installation

Pour surveiller vos tâches ECS Fargate avec Datadog, exécutez l’Agent en tant que conteneur dans la même définition de tâche que votre application. Pour recueillir des métriques avec Datadog, chaque définition de tâche doit inclure un conteneur d’Agent Datadog en plus des conteneurs d’application. Voici les étapes de configuration à suivre :

  1. Créer une tâche ECS Fargate
  2. Créer ou modifier votre stratégie IAM
  3. Exécuter la tâche en tant que service de réplica

Créer une tâche ECS Fargate

Le fonctionnement de Fargate repose sur des tâches. Celles-ci sont configurées dans les définitions de tâches. Une définition de tâche fonctionne comme un pod dans Kubernetes et doit comprendre un ou plusieurs conteneurs. Pour exécuter l’Agent Datadog, créez une définition de tâche conçue pour lancer vos conteneurs d’application ainsi que le conteneur de l’Agent Datadog.

Les instructions ci-dessous vous expliquent comment configurer la tâche à l’aide des outils d’interface de ligne de commande d’AWS ou de la console Web d’Amazon.

Interface utilisateur Web
  1. Connectez-vous à votre console Web AWS et accédez à la section ECS.
  2. Cliquez sur Task Definitions dans le menu de gauche, puis cliquez sur le bouton Create new Task Definition.
  3. Sélectionnez le type de lancement Fargate, puis cliquez sur le bouton Next step.
  4. Saisissez un Task Definition Name, tel que my-app-and-datadog.
  5. Sélectionnez un rôle IAM d’exécution de tâche. Consultez les exigences des différentes autorisations dans la section Créer ou modifier votre stratégie IAM ci-dessous.
  6. Choisissez une valeur pour Task memory et Task CPU en fonction de vos besoins.
  7. Cliquez sur le bouton Add container.
  8. Pour Container name, saisissez datadog-agent.
  9. Pour Image, saisissez datadog/agent:latest.
  10. Pour le champ Memory Limits, saisissez 256 comme limite logicielle.
  11. Faites défiler jusqu’à atteindre la section Advanced container configuration, puis saisissez 10 pour CPU units.
  12. Pour le champ Env Variables, ajoutez la clé DD_API_KEY et saisissez votre clé d’API Datadog en tant que valeur. Si vous préférez stocker vos secrets dans S3, consultez le guide de configuration d’ECS.
  13. Ajoutez une autre variable d’environnement avec la clé ECS_FARGATE et la valeur true. Cliquez sur Add pour ajouter le conteneur.
  14. Ajoutez une autre variable d’environnement en utilisant la clé DD_SITE et la valeur . Le site datadoghq.com est utilisé par défaut si vous ne le définissez pas.
  15. (Windows uniquement) Sélectionnez C:\ comme répertoire de travail.
  16. Ajoutez vos autres conteneurs, tels que celui de votre application. Pour en savoir plus sur la collecte de métriques d’intégration, consultez la section Configuration d’intégration pour ECS Fargate.
  17. Cliquez sur Create pour créer la définition de tâche.
Interface de ligne de commande d’AWS
  1. Téléchargez datadog-agent-ecs-fargate. Remarque : si vous utilisez Internet Explorer, il est possible que le fichier téléchargé soit au format gzip, celui-ci contenant le fichier JSON mentionné ci-dessous.
  2. Mettez à jour le fichier JSON en ajoutant un TASK_NAME, votre clé d’API Datadog et le DD_SITE approprié (). Remarque : la variable d’environnement ECS_FARGATE est déjà définie sur "true".
  3. Ajoutez vos autres conteneurs, tels que celui de votre application. Pour en savoir plus sur la collecte de métriques d’intégration, consultez la section Configuration d’intégration pour ECS Fargate.
  4. Exécutez la commande suivante pour enregistrer la définition de tâche ECS :
aws ecs register-task-definition --cli-input-json file://<CHEMIN_VERS_FICHIER>/datadog-agent-ecs-fargate.json
AWS CloudFormation

Vous pouvez tirer parti des modèles AWS CloudFormation pour configurer vos conteneurs Fargate. Utilisez la ressource AWS::ECS::TaskDefinition dans votre modèle CloudFormation pour définir la tâche Amazon ECS et spécifier FARGATE comme type de lancement requis pour cette tâche. Vous pouvez ensuite définir l’option Datadog de façon à configurer la gestion des logs, comme dans l’exemple ci-dessous :

Resources:
  ECSTDNJH3:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              Host: http-intake.logs.datadoghq.com
              TLS: 'on'
              dd_service: test-service
              dd_source: test-source
              provider: ecs
              apikey: <CLÉ_API>
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Remarque : utilisez un secret TaskDefinition pour éviter d’exposer votre apikey en texte brut.

Pour en savoir plus sur les modèles et la syntaxe CloudFormation, consultez la documentation relative à AWS CloudFormation.

Créer ou modifier votre stratégie IAM

Ajoutez les autorisations suivantes à votre stratégie IAM Datadog afin de recueillir des métriques ECS Fargate. Pour en savoir plus, consultez la section relative aux stratégies ECS de la documentation AWS.

Autorisation AWSDescription
ecs:ListClustersÉnumère tous les clusters disponibles.
ecs:ListContainerInstancesÉnumère les instances d’un cluster.
ecs:DescribeContainerInstancesDécrit les instances pour ajouter des métriques sur les ressources et les tâches en cours d’exécution.

Exécuter la tâche en tant que service de réplica

Dans ECS Fargate, vous êtes contraint d’exécuter la tâche en tant que service de réplica. L’Agent Datadog s’exécute dans la même définition de tâche que vos conteneurs d’application et d’intégration.

Interface de ligne de commande d’AWS

Exécutez les commandes suivantes à l’aide des outils d’interface de ligne de commande d’AWS.

Remarque : la version 1.1.0 ou une version ultérieure de Fargate est requise. La commande ci-dessous spécifie donc la version de la plateforme.

Si besoin, créez un cluster :

aws ecs create-cluster --cluster-name "<NOM_CLUSTER>"

Exécutez la tâche en tant que service pour votre cluster :

aws ecs run-task --cluster <NOM_CLUSTER> \
--network-configuration "awsvpcConfiguration={subnets=["<SOUS-RÉSEAU_PRIVÉ>"],securityGroups=["<GROUPE_SÉCURITÉ>"]}" \
--task-definition arn:aws:ecs:us-east-1:<NUMÉRO_COMPTE_AWS>:task-definition/<NOM_TÂCHE>:1 \
--region <RÉGION_AWS> --launch-type FARGATE --platform-version 1.1.0
Interface utilisateur Web
  1. Connectez-vous à votre console Web AWS et accédez à la section ECS. Si besoin, créez un cluster avec le modèle de cluster Networking only.
  2. Choisissez le cluster sur lequel exécuter l’Agent Datadog.
  3. Dans l’onglet Services, cliquez sur le bouton Create.
  4. Pour le champ Launch type, choisissez FARGATE.
  5. Pour le champ Task Definition, sélectionnez la tâche créée lors des précédentes étapes.
  6. Saisissez un Service name.
  7. Pour le champ Number of tasks, saisissez 1, puis cliquez sur le bouton Next step.
  8. Sélectionnez le VPC de cluster, les sous-réseaux et les groupes de sécurité.
  9. Les champs Load balancing et Service discovery sont facultatifs et peuvent être remplis selon vos préférences.
  10. Cliquez sur le bouton Next step.
  11. Le champ Auto Scaling est facultatif et peut être rempli selon vos préférences.
  12. Cliquez sur le bouton Next step, puis sur le bouton Create service.

Collecte de métriques

Une fois l’Agent Datadog configuré conformément aux instructions ci-dessus, le check ecs_fargate recueille des métriques lorsqu’Autodiscovery est activé. Ajoutez des étiquettes Docker aux autres conteneurs dans la même tâche pour recueillir des métriques supplémentaires.

Pour en savoir plus sur la collecte de métriques d’intégration, consultez la section Configuration d’intégration pour ECS Fargate.

DogStatsD

Les métriques sont recueillies avec DogStatsD via UDP sur le port 8125.

Pour envoyer des métriques custom en écoutant les paquets DogStatsD issus d’autres conteneurs, définissez la variable d’environnement DD_DOGSTATSD_NON_LOCAL_TRAFFIC sur true au sein du conteneur de l’Agent Datadog.

Autres variables d’environnement

Pour consulter les variables d’environnement disponibles avec le conteneur de l’Agent Datadog Docker, consultez la section Agent Docker. Remarque : certaines variables ne sont pas disponibles pour Fargate.

Variable d’environnementDescription
DD_DOCKER_LABELS_AS_TAGSExtrait les étiquettes de conteneur Docker
DD_DOCKER_ENV_AS_TAGSExtrait les variables d’environnement de conteneur Docker
DD_KUBERNETES_POD_LABELS_AS_TAGSExtrait les étiquettes de pod.
DD_CHECKS_TAG_CARDINALITYAjoute des tags aux métriques de check
DD_DOGSTATSD_TAG_CARDINALITYAjoute des tags aux métriques custom

Pour le tagging global, il est conseillé d’utiliser DD_DOCKER_LABELS_AS_TAGS. Avec cette méthode, l’Agent récupère les tags depuis les étiquettes de vos conteneurs Docker. Cela vous oblige à ajouter les étiquettes appropriées à vos autres conteneurs Docker. Il est possible d’ajouter des étiquettes directement dans la définition de tâche.

Format du conteneur de l’Agent :

{
  "name": "DD_DOCKER_LABELS_AS_TAGS",
  "value": "{\"<NOM_ÉTIQUETTE_À_RECUEILLIR>\":\"<CLÉ_TAG_POUR_DATADOG>\"}"
}

Exemple pour le conteneur de l’Agent :

{
  "name": "DD_DOCKER_LABELS_AS_TAGS",
  "value": "{\"com.docker.compose.service\":\"service_name\"}"
}

Remarque : la notion de host pour l’utilisateur étant inexistante dans Fargate, assurez-vous de ne pas utiliser DD_HOSTNAME. DD_TAGS est généralement utilisé pour assigner des tags de host, mais à partir de la version 6.13.0 de l’Agent Datadog, vous pouvez également utiliser une variable d’environnement pour appliquer des tags globaux à vos métriques d’intégration.

Métriques basées sur le crawler

Outre la collecte de métriques par l’Agent, Datadog propose également une intégration ECS basée sur CloudWatch. Celle-ci recueille les métriques d’Amazon ECS CloudWatch.

Comme nous l’avons mentionné, les tâches Fargate transmettent également des métriques de cette façon :

Les métriques disponibles varient en fonction du type de lancement des tâches et services de vos clusters. Si vous utilisez un type de lancement Fargate pour vos services, les métriques relatives à l’utilisation du processeur et de la mémoire vous sont fournies afin de faciliter la surveillance de vos services.

Puisque cette méthode n’utilise pas l’Agent Datadog, vous devez configurer l’intégration AWS en cochant ECS dans le carré d’intégration. Datadog récupère ensuite automatiquement ces métriques CloudWatch (avec l’espace de nommage aws.ecs.* dans Datadog). Consultez la section Données collectées de la documentation.

Si ce sont les seules métriques dont vous avez besoin, vous pouvez utiliser cette intégration pour effectuer la collecte via les métriques CloudWatch. Remarque : les données CloudWatch sont moins granulaires (une à cinq minutes en fonction du type de surveillance activé) et mettent plus de temps à parvenir à Datadog. En effet, la collecte des données depuis CloudWatch doit respecter les limites de l’API AWS. Les données ne peuvent pas être envoyées directement à Datadog avec l’Agent.

Le crawler CloudWatch par défaut de Datadog récupère les métriques toutes les 10 minutes. Si vous avez besoin d’un intervalle plus court, contactez l’assistance Datadog pour en discuter. Remarque : les appels d’API étant facturés par CloudWatch, cela entraînera une augmentation de votre facture AWS.

Collecte de logs

Vous avez la possibilité de surveiller les logs Fargate de deux façons différentes : en utilisant l’intégration AWS FireLens basée sur le plug-in de sortie Fluent Bit de Datadog afin d’envoyer les logs à Datadog, ou en utilisant le pilote de logs awslogs et une fonction Lambda afin d’acheminer les logs vers Datadog. Étant donné que Fluent Bit peut être directement configuré dans vos tâches Fargate, nous vous conseillons d’utiliser AWS FireLens.

Fluent Bit et FireLens

Configurez l’intégration AWS FireLens basée sur le plug-in de sortie Flutent Bit de Datadog de façon à connecter vos données de logs FireLens aux logs Datadog.

  1. Activez Fluent Bit dans le conteneur de routage de vos logs FireLens au sein de votre tâche Fargate. Pour en savoir plus sur l’activation de FireLens, consultez la documentation AWS FireLens dédiée. Pour en savoir plus sur les définitions de conteneur Fargate, consultez la documentation AWS à ce sujet. AWS conseille d’utiliser l’image Docker correspondant à votre région. Voici un exemple de définition de tâche où l’image Fluent Bit est configurée :

    {
      "essential": true,
      "image": "amazon/aws-for-fluent-bit:stable",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": { "enable-ecs-log-metadata": "true" }
      }
    }
    

    Si vos conteneurs publient des logs JSON sérialisés via stdout, vous devez utiliser cette configuration FireLens supplémentaire pour que leur parsing s’effectue correctement dans Datadog :

    {
      "essential": true,
      "image": "amazon/aws-for-fluent-bit:stable",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": {
          "enable-ecs-log-metadata": "true",
          "config-file-type": "file",
          "config-file-value": "/fluent-bit/configs/parse-json.conf"
        }
      }
    }
    

    Cet argument convertit le JSON sérialisé du champ log: en champs de niveau supérieur. Consultez un exemple pour AWS dans la section relative au parsing de logs sous forme de JSON sérialisé à partir du stdout d’un conteneur (en anglais) pour en savoir plus.

  2. Ensuite, toujours dans la même tâche Fargate, définissez une configuration de log en spécifiant AWS FireLens comme pilote de logs et en configurant l’envoi des logs à Fluent Bit. Voici un exemple de définition de tâche permettant d’envoyer les données de logs à Fluent Bit avec FireLens comme pilote de logs :

    {
      "logConfiguration": {
        "logDriver": "awsfirelens",
        "options": {
          "Name": "datadog",
          "apikey": "<DATADOG_API_KEY>",
          "Host": "http-intake.logs.datadoghq.com",
          "dd_service": "firelens-test",
          "dd_source": "redis",
          "dd_message_key": "log",
          "dd_tags": "project:fluentbit",
          "TLS": "on",
          "provider": "ecs"
        }
      }
    }
    

    Remarque : si votre organisation utilise le site européen de Datadog, utilisez plutôt http-intake.logs.datadoghq.eu pour l’option Host. La liste complète des paramètres acceptés est disponible dans la documentation Datadog sur Fluentbit.

  3. À chaque exécution d’une tâche Fargate, Fluent Bit envoie les logs de conteneur à Datadog, accompagnés d’informations sur l’ensemble des conteneurs gérés par vos tâches Fargate. Vous avez la possibilité de visualiser les logs bruts sur la page Log Explorer, de créer des monitors pour les logs et d’utiliser la vue Live Container.

Pilote de logs AWS

Surveillez les logs Fargate avec le pilote de logs awslogs et une fonction Lambda pour acheminer les logs vers Datadog.

  1. Définissez le pilote AwsLog Fargate dans votre tâche. Consultez le guide de développement d’AWS Fargate pour obtenir des instructions à ce sujet.

  2. Les définitions de tâche Fargate prennent uniquement en charge le pilote de log awslogs pour la configuration des logs. Vous pouvez ainsi configurer vos tâches Fargate de façon à envoyer des informations de journalisation à Amazon CloudWatch Logs. Voici un extrait de définition de tâche pour laquelle le pilote de log awslogs est configuré :

    {
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/fargate-task-definition",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
    

    Pour en savoir plus sur l’utilisation du pilote de log awslogs dans vos définitions de tâches afin d’envoyer des logs de conteneur à CloudWatch Logs, référez-vous à la section Utilisation du pilote de journal awslogs. Ce pilote recueille les logs générés par le conteneur et les envoie directement à CloudWatch.

  3. Enfin, utilisez une fonction Lambda pour recueillir les logs à partir de CloudWatch et les envoyer à Datadog.

Collecte de traces

  1. Suivez les instructions ci-dessus pour ajouter le conteneur de l’Agent Datadog à la définition de votre tâche en définissant la variable d’environnement supplémentaire DD_APM_ENABLED sur true, et configurez un port de host qui utilise 8126 avec le protocole tcp pour le mappage de port. Définissez la variable DD_SITE sur . Le site datadoghq.com sera utilisé par défaut si elle n’est pas définie.

  2. Instrumentez votre application en fonction de votre infrastructure.

  3. Assurez-vous que votre application s’exécute dans la même définition de tâche que le conteneur de l’Agent Datadog.

Données collectées

Métriques

ecs.fargate.io.ops.write
(rate)
# write operations to the disk (Linux only)
ecs.fargate.io.bytes.write
(rate)
# bytes written to the disk (Linux only)
Shown as byte
ecs.fargate.io.ops.read
(rate)
# read operation on the disk (Linux only)
ecs.fargate.io.bytes.read
(rate)
# bytes read on the disk (Linux only)
Shown as byte
ecs.fargate.cpu.user
(rate)
User CPU time
Shown as nanosecond
ecs.fargate.cpu.system
(rate)
System CPU time
Shown as nanosecond
ecs.fargate.cpu.usage
(rate)
Total CPU Usage
Shown as nanosecond
ecs.fargate.cpu.limit
(gauge)
Limit in percent of the CPU usage
Shown as percent
ecs.fargate.cpu.percent
(gauge)
Percentage of CPU used per container (Linux only)
Shown as percent
ecs.fargate.mem.cache
(gauge)
# of bytes of page cache memory (Linux only)
Shown as byte
ecs.fargate.mem.active_file
(gauge)
# of bytes of file-backed memory on active LRU list (Linux only)
Shown as byte
ecs.fargate.mem.inactive_file
(gauge)
# of bytes of file-backed memory on inactive LRU list (Linux only)
Shown as byte
ecs.fargate.mem.limit
(gauge)
# of bytes memory limit (Linux only)
Shown as byte
ecs.fargate.mem.active_anon
(gauge)
# of bytes of anonymous and swap cache memory on active LRU list (Linux only)
Shown as byte
ecs.fargate.mem.usage
(gauge)
# of bytes of memory used
Shown as byte
ecs.fargate.mem.rss
(gauge)
# of bytes of anonymous and swap cache memory (includes transparent hugepages) (Linux only)
Shown as byte
ecs.fargate.mem.pgpgout
(rate)
# of uncharging events to the memory cgroup. The uncharging event happens each time a page is unaccounted from the cgroup (Linux only)
ecs.fargate.mem.pgpgin
(rate)
# of charging events to the memory cgroup. The charging event happens each time a page is accounted as either mapped anon page(RSS) or cache page(Page Cache) to the cgroup. (Linux only)
ecs.fargate.mem.pgfault
(rate)
# of page faults per second (Linux only)
ecs.fargate.mem.pgmajfault
(rate)
# of major page faults per second (Linux only)
ecs.fargate.mem.mapped_file
(gauge)
# of bytes of mapped file (includes tmpfs/shmem) (Linux only)
Shown as byte
ecs.fargate.mem.max_usage
(gauge)
Show max memory usage recorded
Shown as byte
ecs.fargate.mem.hierarchical_memory_limit
(gauge)
# of bytes of memory limit with regard to hierarchy under which the memory cgroup is (Linux only)
Shown as byte
ecs.fargate.mem.hierarchical_memsw_limit
(gauge)
# of bytes of memory+swap limit with regard to hierarchy under which memory cgroup is (Linux only)
Shown as byte
ecs.fargate.net.rcvd_errors
(gauge)
# received errors (Fargate 1.4.0+ required)
Shown as error
ecs.fargate.net.sent_errors
(gauge)
# sent errors (Fargate 1.4.0+ required)
Shown as error
ecs.fargate.net.packet.in_dropped
(gauge)
# ingoing packets dropped (Fargate 1.4.0+ required)
Shown as packet
ecs.fargate.net.packet.out_dropped
(gauge)
# outgoing packets dropped (Fargate 1.4.0+ required)
Shown as packet
ecs.fargate.net.bytes_rcvd
(rate)
# bytes received (Fargate 1.4.0+ required)
Shown as byte
ecs.fargate.net.bytes_sent
(rate)
# bytes sent (Fargate 1.4.0+ required)
Shown as byte
Les descriptions précisent également lorsqu’une métrique est uniquement disponible sur Linux.

Événements

Le check ECS Fargate n’inclut aucun événement.

Checks de service

ecs_fargate.can_connect
Returns CRITICAL if the Agent is unable to connect to Fargate, otherwise returns OK.
Statuses: ok, critical

Dépannage

Besoin d’aide ? Contactez l’assistance Datadog.

Pour aller plus loin