Pilote de logging Amazon CloudWatch Logs

Le pilote de logging awslogs envoie les logs de conteneur à Amazon CloudWatch Logs. Les entrées de log peuvent être récupérées via la Console de gestion AWS ou les SDK AWS et outils de ligne de commande.

Utilisation

Pour utiliser le pilote awslogs comme pilote de logging par défaut, définissez les clés log-driver et log-opt aux valeurs appropriées dans le fichier daemon.json, qui se trouve dans /etc/docker/ sur les hôtes Linux ou C:\ProgramData\docker\config\daemon.json sur Windows Server. Pour plus d'informations sur la configuration de Docker en utilisant daemon.json, voir daemon.json. L'exemple suivant définit le pilote de log à awslogs et définit l'option awslogs-region.

{
  "log-driver": "awslogs",
  "log-opts": {
    "awslogs-region": "us-east-1"
  }
}

Redémarrez Docker pour que les changements prennent effet.

Vous pouvez définir le pilote de logging pour un conteneur spécifique en utilisant l'option --log-driver avec docker run :

$ docker run --log-driver=awslogs ...

Si vous utilisez Docker Compose, définissez awslogs en utilisant l'exemple de déclaration suivant :

myservice:
  logging:
    driver: awslogs
    options:
      awslogs-region: us-east-1

Options Amazon CloudWatch Logs

Vous pouvez ajouter des options de logging au daemon.json pour définir des valeurs par défaut Docker-wide, ou utiliser le drapeau --log-opt NAME=VALUE pour spécifier les options du pilote de logging Amazon CloudWatch Logs lors du démarrage d'un conteneur.

awslogs-region

Le pilote de logging awslogs envoie vos logs Docker vers une région spécifique. Utilisez l'option de log awslogs-region ou la variable d'environnement AWS_REGION pour définir la région. Par défaut, si votre daemon Docker fonctionne sur une instance EC2 et qu'aucune région n'est définie, le pilote utilise la région de l'instance.

$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ...

awslogs-endpoint

Par défaut, Docker utilise soit l'option de log awslogs-region soit la région détectée pour construire le point de terminaison API CloudWatch Logs distant. Utilisez l'option de log awslogs-endpoint pour remplacer le point de terminaison par défaut par le point de terminaison fourni.

Note

L'option de log awslogs-region ou la région détectée contrôle la région utilisée pour la signature. Vous pourriez rencontrer des erreurs de signature si le point de terminaison que vous avez spécifié avec awslogs-endpoint utilise une région différente.

awslogs-group

Vous devez spécifier un groupe de logs pour le pilote de logging awslogs. Vous pouvez spécifier le groupe de logs avec l'option de log awslogs-group :

$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ...

awslogs-stream

Pour configurer quel flux de logs devrait être utilisé, vous pouvez spécifier l'option de log awslogs-stream. Si non spécifié, l'ID du conteneur est utilisé comme flux de logs.

Note

Les flux de logs au sein d'un groupe de logs donné ne devraient être utilisés que par un conteneur à la fois. Utiliser le même flux de logs pour plusieurs conteneurs simultanément peut causer une performance de logging réduite.

awslogs-create-group

Le pilote de log retourne une erreur par défaut si le groupe de logs n'existe pas. Cependant, vous pouvez définir awslogs-create-group à true pour créer automatiquement le groupe de logs selon le besoin. L'option awslogs-create-group est par défaut false.

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-create-group=true \
    ...

Note

Votre politique AWS IAM doit inclure la permission logs:CreateLogGroup avant que vous tentiez d'utiliser awslogs-create-group.

awslogs-create-stream

Par défaut, le pilote de log crée le flux AWS CloudWatch Logs utilisé pour la persistance des logs de conteneur.

Définissez awslogs-create-stream à false pour désactiver la création de flux de logs. Quand désactivé, le daemon Docker assume que le flux de logs existe déjà. Un cas d'utilisation où ceci est bénéfique est quand la création de flux de logs est gérée par un autre processus évitant les appels API AWS CloudWatch Logs redondants.

Si awslogs-create-stream est défini à false et que le flux de logs n'existe pas, la persistance des logs vers CloudWatch échoue pendant l'exécution du conteneur, résultant en messages d'erreur Failed to put log events dans les logs du daemon.

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-stream=myLogStream \
    --log-opt awslogs-create-stream=false \
    ...

awslogs-datetime-format

L'option awslogs-datetime-format définit un modèle de début multi-ligne en format Python strftime. Un message de log consiste en une ligne qui correspond au modèle et toutes les lignes suivantes qui ne correspondent pas au modèle. Ainsi la ligne correspondante est le délimiteur entre les messages de log.

Un exemple d'un cas d'utilisation pour utiliser ce format est pour analyser la sortie telle qu'un vidage de pile, qui pourrait autrement être loggé en plusieurs entrées. Le bon modèle permet qu'il soit capturé en une seule entrée.

Cette option prend toujours la précédence si à la fois awslogs-datetime-format et awslogs-multiline-pattern sont configurés.

Note

Le logging multi-ligne effectue l'analyse et la correspondance d'expressions régulières de tous les messages de log, ce qui peut avoir un impact négatif sur les performances de logging.

Considérez le flux de logs suivant, où de nouveaux messages de log commencent par un horodatage :

[May 01, 2017 19:00:01] A message was logged
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words
[May 01, 2017 19:01:32] Another message was logged

Le format peut être exprimé comme une expression strftime de [%b %d, %Y %H:%M:%S], et la valeur awslogs-datetime-format peut être définie à cette expression :

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-datetime-format='\[%b %d, %Y %H:%M:%S\]' \
    ...

Ceci analyse les logs en les événements de log CloudWatch suivants :

# Premier événement
[May 01, 2017 19:00:01] A message was logged

# Deuxième événement
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words

# Troisième événement
[May 01, 2017 19:01:32] Another message was logged

Les codes strftime suivants sont supportés :

awslogs-multiline-pattern

L'option awslogs-multiline-pattern définit un modèle de début multi-ligne utilisant une expression régulière. Un message de log consiste en une ligne qui correspond au modèle et toutes les lignes suivantes qui ne correspondent pas au modèle. Ainsi la ligne correspondante est le délimiteur entre les messages de log.

Cette option est ignorée si awslogs-datetime-format est aussi configuré.

Note

Le logging multi-ligne effectue l'analyse et la correspondance d'expressions régulières de tous les messages de log. Ceci peut avoir un impact négatif sur les performances de logging.

Considérez le flux de logs suivant, où chaque message de log devrait commencer par le modèle INFO :

INFO A message was logged
INFO Another multi-line message was logged
     Some random message
INFO Another message was logged

Vous pouvez utiliser l'expression régulière ^INFO :

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-multiline-pattern='^INFO' \
    ...

Ceci analyse les logs en les événements de log CloudWatch suivants :

# Premier événement
INFO A message was logged

# Deuxième événement
INFO Another multi-line message was logged
     Some random message

# Troisième événement
INFO Another message was logged

tag

Spécifiez tag comme alternative à l'option awslogs-stream. tag interprète le balisage de modèle Go, tel que {{.ID}}, {{.FullID}} ou {{.Name}} docker.{{.ID}}. Voir la documentation de l'option tag pour les détails sur les substitutions de modèle supportées.

Quand à la fois awslogs-stream et tag sont spécifiés, la valeur fournie pour awslogs-stream remplace le modèle spécifié avec tag.

Si non spécifié, l'ID du conteneur est utilisé comme flux de logs.

Note

L'API de log CloudWatch ne supporte pas : dans le nom de log. Ceci peut causer quelques problèmes lors de l'utilisation de {{ .ImageName }} comme tag, puisqu'une image Docker a un format IMAGE:TAG, tel que alpine:latest. Le balisage de modèle peut être utilisé pour obtenir le bon format. Pour obtenir le nom d'image et les 12 premiers caractères de l'ID du conteneur, vous pouvez utiliser :

--log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'

la sortie est quelque chose comme : alpine_latest-bf0072049c76

awslogs-force-flush-interval-seconds

Le pilote awslogs vide périodiquement les logs vers CloudWatch.

L'option awslogs-force-flush-interval-seconds change l'intervalle de vidage des logs en secondes.

Par défaut 5 secondes.

awslogs-max-buffered-events

Le pilote awslogs met les logs en mémoire tampon.

L'option awslogs-max-buffered-events change la taille de la mémoire tampon des logs.

Par défaut 4K.

Informations d'identification

Vous devez fournir des informations d'identification AWS au daemon Docker pour utiliser le pilote de logging awslogs. Vous pouvez fournir ces informations d'identification avec les variables d'environnement AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, et AWS_SESSION_TOKEN, le fichier d'informations d'identification partagées AWS par défaut (~/.aws/credentials de l'utilisateur root), ou si vous exécutez le daemon Docker sur une instance Amazon EC2, le profil d'instance Amazon EC2.

Les informations d'identification doivent avoir une politique appliquée qui permet les actions logs:CreateLogStream et logs:PutLogEvents, comme montré dans l'exemple suivant.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}