Utilisation de l'agent CloudWatch pour envoyer des journaux au format de métrique intégrée - Amazon CloudWatch
Installation de l'agent CloudWatch Utilisation de l'agent CloudWatch pour envoyer des journaux au format de métrique intégrée

Utilisation de l'agent CloudWatch pour envoyer des journaux au format de métrique intégrée

Cette section décrit comment installer et utiliser l’agent CloudWatch. La première partie de cette section décrit comment installer l’agent CloudWatch. La deuxième partie de cette section décrit comment utiliser l’agent CloudWatch pour envoyer des journaux au format métrique intégré. Si vous voulez utiliser cette méthode, vous devez installer l’agent CloudWatch pour les Services AWS à partir desquels vous souhaitez envoyer des journaux au format métrique intégré. Vous pouvez ensuite commencer à envoyer les événements. L'agent CloudWatch doit être à la version 1.230621.0 ou ultérieure.

Note

Vous n'avez pas besoin d'installer l'agent CloudWatch pour envoyer des journaux à partir des fonctions Lambda.

Les délais d'expiration de la fonction Lambda ne sont pas gérés automatiquement. Cela signifie que si votre fonction expire avant que les mesures ne soient éliminées, les métriques de cette invocation ne seront pas capturées.

Installation de l'agent CloudWatch

Installez l'agent CloudWatch pour chaque service qui doit envoyer des journaux de format de métrique intégrée.

Installation de l'agent CloudWatch sur EC2

Commencez par installer l'agent CloudWatch sur l'instance. Pour de plus amples informations, consultez Installation de l'agent CloudWatch.

Une fois l'agent installé, configurez-le pour qu'il écoute sur un port UDP ou TCP pour les journaux de format de métrique intégrée. Voici un exemple de cette configuration qui écoute sur le socket par défaut tcp:25888. Pour en savoir plus sur la configuration de l'agent, consultez Création ou édition manuelle du fichier de configuration d'agent CloudWatch.

{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}

Installation de l'agent CloudWatch sur Amazon ECS

Le moyen le plus simple de déployer l'agent CloudWatch sur Amazon ECS consiste à l'exécuter en tant que complément, en le définissant dans la même définition de tâche que votre application.

Créer un fichier de configuration de l'agent

Créez votre fichier de configuration de l'agent CloudWatch de manière locale. Dans cet exemple, le chemin de fichier relatif sera amazon-cloudwatch-agent.json.

Pour en savoir plus sur la configuration de l'agent, consultez Création ou édition manuelle du fichier de configuration d'agent CloudWatch.

{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}

Configuration push vers le Parameter Store SSM

Entrez la commande suivante pour envoyer le fichier de configuration de l'agent CloudWatch vers le Parameter Store AWS Systems Manager (SSM).

aws ssm put-parameter \
    --name "cwagentconfig" \
    --type "String" \
    --value "`cat amazon-cloudwatch-agent.json`" \
    --region "{{region}}"

Configuration de la définition de tâche

Configurez votre définition de tâche pour utiliser l'agent CloudWatch et exposer le port TCP ou UDP. L'exemple de définition de tâche que vous devez utiliser dépend de votre mode de mise en réseau.

Notez que le webapp spécifie la variable d'environnement AWS_EMF_AGENT_ENDPOINT. Ceci est utilisé par la bibliothèque et doit pointer vers le point de terminaison sur lequel l'agent écoute. En outre, le cwagent spécifie le CW_CONFIG_CONTENT en tant que paramètre « valueFrom » qui pointe vers la configuration SSM que vous avez créée à l'étape précédente.

Cette section contient un exemple pour le mode pont et un exemple pour le mode hôte ou awsvpc. Pour plus d'exemples de configuration de l'agent CloudWatch sur Amazon ECS, consultez le référentiel d'exemples Github.

Voici un exemple pour le mode pont. Lorsque la mise en réseau en mode pont est activée, l'agent doit être lié à votre application à l'aide du paramètre links et doit être adressé à l'aide du nom du conteneur.

{
  "containerDefinitions": [
          {
              "name": "webapp",
              "links": [ "cwagent" ],
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://cwagent:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}

Voici un exemple pour le mode hôte ou awsvpc. Lors de l'exécution sur ces modes réseau, l'agent peut être adressé via localhost.

{
  "containerDefinitions": [
          {
              "name": "webapp",
              "image": "my-org/web-app:latest",
              "memory": 256,
              "cpu": 256,
              "environment": [{
                "name": "AWS_EMF_AGENT_ENDPOINT",
                "value": "tcp://127.0.0.1:25888"
              }],
          },
          {
              "name": "cwagent",
              "mountPoints": [],
              "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
              "memory": 256,
              "cpu": 256,
              "portMappings": [{
                  "protocol": "tcp",
                  "containerPort": 25888
              }],
              "environment": [{
                "name": "CW_CONFIG_CONTENT",
                "valueFrom": "cwagentconfig"
              }],
          }
      ],
}
Note

En mode awsvpc, vous devez soit donner une adresse IP publique au VPC ( Fargate uniquement), configurer une passerelle NAT ou configurer un point de terminaison VPC CloudWatch Logs. Pour de plus amples informations sur la configuration d'un NAT, veuillez consulter Passerelles NAT. Pour de plus amples informations sur la configuration d'un point de terminaison VPC CloudWatch Logs, consultez Utilisation de CloudWatch Logs avec des points de terminaison VPC d'interface.

Voici un exemple d'attribution d'une adresse IP publique à une tâche qui utilise le type de lancement Fargate.

aws ecs run-task \ 
--cluster {{cluster-name}} \
--task-definition cwagent-fargate \
--region {{region}} \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}"

Assurer les autorisations

Assurez-vous que le rôle IAM exécutant vos tâches a l'autorisation de lire à partir du magasin de paramètres SSM. Vous pouvez ajouter cette autorisation en joignant la stratégie AmazonSSMReadOnlyAccess. Pour ce faire, entrez la commande suivante.

aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole

Installation de l'agent CloudWatch sur Amazon EKS

Certaines parties de ce processus peuvent être ignorées si vous avez déjà installé CloudWatch Container Insights sur ce cluster.

Autorisations

Si vous n'avez pas déjà installé Container Insights, assurez-vous d'abord que vos nœuds Amazon EKS disposent des autorisations IAM appropriées. Ils doivent avoir la politique CloudWatchAgentServerPolicy attachée. Pour de plus amples informations, consultez Vérification des conditions préalables pour Container Insights dans CloudWatch.

Créer ConfigMap

Créez une ConfigMap pour l'agent. La ConfigMap indique également à l'agent d'écouter sur un port TCP ou UDP. Utilisez la ConfigMap suivante.

# cwagent-emf-configmap.yaml
apiVersion: v1
data:
  # Any changes here must not break the JSON format
  cwagentconfig.json: |
    {
      "agent": {
        "omit_hostname": true
      },
      "logs": {
        "metrics_collected": {
          "emf": { }
        }
      }
    }
kind: ConfigMap
metadata:
  name: cwagentemfconfig
  namespace: default

Si vous avez déjà installé Container Insights, ajoutez la ligne "emf": { } suivante à votre ConfigMap existante.

Appliquer la ConfigMap

Entrez la commande suivante pour appliquer la ConfigMap.

kubectl apply -f cwagent-emf-configmap.yaml

Deploy the agent (Déploiement de l'agent)

Pour déployer l'agent CloudWatch en tant que complément, ajoutez l'agent à votre définition de pod, comme dans l'exemple suivant.

apiVersion: v1
kind: Pod
metadata:
  name: myapp
  namespace: default
spec:
  containers:
    # Your container definitions go here
    - name: web-app
      image: my-org/web-app:latest
    # CloudWatch Agent configuration
    - name: cloudwatch-agent
      image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest
      imagePullPolicy: Always
      resources:
        limits:
          cpu: 200m
          memory: 100Mi
        requests:
          cpu: 200m
          memory: 100Mi
      volumeMounts:
        - name: cwagentconfig
          mountPath: /etc/cwagentconfig
      ports:
  # this should match the port configured in the ConfigMap
        - protocol: TCP
          hostPort: 25888
          containerPort: 25888
  volumes:
    - name: cwagentconfig
      configMap:
        name: cwagentemfconfig

Utilisation de l'agent CloudWatch pour envoyer des journaux au format de métrique intégrée

Une fois l'agent CloudWatch installé et en cours d'exécution, vous pouvez envoyer les journaux au format de métrique intégrée via TCP ou UDP. Il y a deux exigences lors de l'envoi des journaux par l'intermédiaire de l'agent :

  • Les journaux doivent contenir une clé LogGroupName indiquant à l'agent quel groupe de journaux utiliser.

  • Chaque événement de journal doit se trouver sur une seule ligne. En d'autres termes, un événement de journal ne peut pas contenir le caractère de nouvelle ligne (\n).

Les événements de journaux doivent également suivre la spécification de format de métrique intégrée. Pour de plus amples informations, consultez Spécifications : format de métrique intégrée.

Si vous prévoyez de créer des alertes sur des métriques créées à l'aide du format de métrique intégrée, consultez les recommandations de la rubrique Configuration d'alertes sur les métriques créées avec le format de métrique intégrée.

Voici un exemple d'envoi manuel d'événements du journal à partir d'un shell bash Linux. Vous pouvez plutôt utiliser les interfaces de socket UDP fournies par votre langage de programmation de choix. 

echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \
> /dev/udp/0.0.0.0/25888
Note

Avec le format de métrique intégré, vous pouvez suivre le traitement de vos journaux EMF par des métriques qui sont publiées dans l'espace de nom AWS/Logs de votre compte. Celles-ci peuvent être utilisées pour suivre les échecs de génération de métriques à partir d'EMF, ainsi que pour savoir si les échecs sont dus à l'analyse ou à la validation. Pour plus de détails, consultez Surveillance à l'aide des métriques CloudWatch.