Référence de l'agent CloudWatch Logs - Amazon CloudWatch Logs
Fichier de configuration de l'agentUtilisation de l'agent CloudWatch Logs avec les proxys HTTPCloisonnement des fichiers de configuration de l'agent CloudWatch LogsFAQ sur l'agent CloudWatch Logs

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Référence de l'agent CloudWatch Logs

Important

Cette référence concerne l'ancien agent CloudWatch Logs. Si vous utilisez Instance Metadata Service Version 2 (IMDSv2), vous devez utiliser le nouvel agent CloudWatch unifié. Si vous n'utilisez pas IMDSv2, nous vous recommandons fortement d'utiliser le nouvel agent CloudWatch unifié plutôt que l'ancien agent. Pour plus d'informations sur ce nouvel agent unifié, consultez Collecte de métriques et de journaux à partir d'instances Amazon EC2 et de serveurs sur site avec l'agent CloudWatch.

Pour plus d'informations sur la migration de l'ancien agent CloudWatch Logs vers l'agent unifié, consultez ‏Création du fichier de configuration d'agent CloudWatch à l'aide de l'assistant.

L'agent CloudWatch Logs offre un moyen automatisé d'envoyer des données de journal à CloudWatch Logs à partir des instances Amazon EC2. L'agent comprend les éléments suivants :

  • Plug-in pour l'AWS CLI qui effectue une transmission de type push des données de journal vers CloudWatch Logs.

  • Script (démon) qui lance le processus d'envoi de données push vers CloudWatch Logs.

  • Une tâche cron qui garantit que le programme démon s'exécute en permanence.

Fichier de configuration de l'agent

Le fichier de configuration de l'agent CloudWatch Logs décrit les informations nécessaires à l'agent CloudWatch Logs. La section [general] du fichier de configuration de l'agent définit les configurations courantes qui s'appliquent à tous les flux de journaux. La section [logstream] définit les informations nécessaires pour envoyer un fichier local à un flux de journaux à distance. Vous pouvez avoir plusieurs sections [logstream], mais chacune doit porter un nom unique dans le fichier de configuration, par exemple [logstream1], [logstream2] et ainsi de suite. La valeur [logstream], ainsi que la première ligne de données du fichier journal, définissent l'identités du fichier journal.

[general]
state_file = value
logging_config_file = value
use_gzip_http_content_encoding = [true | false]

[logstream1]
log_group_name = value
log_stream_name = value
datetime_format = value
time_zone = [LOCAL|UTC]
file = value
file_fingerprint_lines = integer | integer-integer
multi_line_start_pattern = regex | {datetime_format}
initial_position = [start_of_file | end_of_file]
encoding = [ascii|utf_8|..]
buffer_duration = integer
batch_count = integer
batch_size = integer

[logstream2]
...
state_file

Spécifie l'emplacement où est stocké le fichier d'état.

logging_config_file

(Facultatif) Spécifie l'emplacement du fichier de configuration de la journalisation de l'agent. Si vous ne spécifiez pas de fichier de configuration de la journalisation de l'agent ici, le fichier par défaut awslogs.conf est utilisé. L'emplacement du fichier par défaut est /var/awslogs/etc/awslogs.conf si vous avez installé l'agent à l'aide d'un script, et /etc/awslogs/awslogs.conf si vous avez installé l'agent avec rpm. Le fichier est au format de fichier de configuration Python (https://docs.python.org/2/library/logging.config.html#logging-config-fileformat). Il est possible de personnaliser les enregistreurs suivants.

cwlogs.push
cwlogs.push.reader
cwlogs.push.publisher
cwlogs.push.event
cwlogs.push.batch
cwlogs.push.stream
cwlogs.push.watcher

L'exemple ci-dessous fait passer le niveau du lecteur et de l'éditeur à WARNING, alors que la valeur par défaut est INFO.

[loggers]
keys=root,cwlogs,reader,publisher
            
[handlers]
keys=consoleHandler
            
[formatters]
keys=simpleFormatter
           
[logger_root]
level=INFO
handlers=consoleHandler
            
[logger_cwlogs]
level=INFO
handlers=consoleHandler
qualname=cwlogs.push
propagate=0
            
[logger_reader]
level=WARNING
handlers=consoleHandler
qualname=cwlogs.push.reader
propagate=0
            
[logger_publisher]
level=WARNING
handlers=consoleHandler
qualname=cwlogs.push.publisher
propagate=0
            
[handler_consoleHandler]
class=logging.StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stderr,)
            
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(process)d - %(threadName)s - %(message)s
use_gzip_http_content_encoding

Lorsque la valeur est définie sur true (valeur par défaut), l'encodage de contenu http gzip peut envoyer des charges utiles compressés à CloudWatch Logs. Cela entraîne une diminution de l'utilisation de l'UC, réduit les sorties réseau et diminue la latence de Put. Pour désactiver cette fonctionnalité, ajoutez use_gzip_http_content_encoding = false à la section [general] du fichier de configuration de l'agent CloudWatch Logs, puis redémarrez l'agent.

Note

Ce paramètre est uniquement disponible pour la version awscli-cwlogs 1.3.3 et les versions ultérieures.

log_group_name

Spécifie le groupe de journaux de destination. Un groupe de journaux est créé automatiquement s'il n'en existe pas déjà. Les noms des groupes de journaux peuvent comporter entre 1 et 512 caractères. Les caractères autorisés sont : a-z, A-Z, 0-9, « _ » (trait de soulignement), « - » (tiret), « / » (barre oblique) et « . » (point).

log_stream_name

Spécifie le flux de journaux de destination. Vous pouvez définir un nom de flux de journal à l'aide d'une chaîne littérale, de variables prédéfinies ({instance_id}, {hostname} et {ip_address}), ou d'une combinaison de celles-ci. Un flux de journaux est créé automatiquement s'il n'en existe pas déjà.

datetime_format

Spécifie la façon dont l'horodatage est extrait des journaux. L'horodatage est utilisé pour récupérer les événements de journaux et générer des métriques. L'heure actuelle est utilisée pour chaque événement de journal si datetime_format n'est pas fourni. Si la valeur datetime_format fournie n'est pas valide pour un message de journal donné, l'horodatage du dernier événement de journal dont l'horodatage a été analysé avec succès sera utilisé. En cas d'absence d'événements de journaux précédents, l'heure actuelle est utilisée.

Les codes datetime_format courants sont répertoriées ci-dessous. Vous pouvez également utiliser n'importe quel code datetime_format pris en charge par Python, datetime.strptime(). Le décalage horaire (%z) est également pris en charge, même s'il n'est pas pris en charge par les versions antérieures ou égales à Python 3.2, [+-]HHMM deux points(:). Pour plus d'informations, consultez strftime() and strptime() Behavior.

%y : année sans siècle sous forme de nombre décimal auquel est ajouté un zéro. 00, 01, ..., 99

%Y : année avec siècle sous forme de nombre décimal.1970, 1988, 2001, 2013

%b : mois sous forme du nom abrégé dans la langue locale. jan, fév, ..., déc (fr_FR);

%B : mois sous forme du nom complet dans la langue locale. janvier, février, ..., décembre (fr_FR);

%m : mois sous forme de nombre décimal auquel est ajouté un zéro. 01, 02, ..., 12

%d : jour du mois sous forme de nombre décimal auquel est ajouté un zéro. 01, 02, ..., 31

%H : heure (au format 24 heures) sous forme de nombre décimal auquel est ajouté un zéro. 00, 01, ..., 23

%I : heure (au format 12 heures) sous forme de nombre décimal auquel est ajouté un zéro. 01, 02, ..., 12

%p : équivalent de AM ou PM dans les paramètres régionaux.

%M : minute sous forme de nombre décimal auquel est ajouté un zéro. 00, 01, ..., 59

%S : seconde sous forme de nombre décimal auquel est ajouté un zéro. 00, 01, ..., 59

%f : microseconde sous forme de nombre décimal auquel est ajouté un zéro, à gauche. 000000, ..., 999999

%z : décalage UTC sous la forme +HHMM ou -HHMM. +0000, -0400, +1030

Exemples de formats :

Syslog: '%b %d %H:%M:%S', e.g. Jan 23 20:59:29

Log4j: '%d %b %Y %H:%M:%S', e.g. 24 Jan 2014 05:00:00

ISO8601: '%Y-%m-%dT%H:%M:%S%z', e.g. 2014-02-20T05:20:20+0000

time_zone

Spécifie le fuseau horaire de l'horodatage de l'événement de journal. Les deux valeurs prises en charge sont UTC et LOCAL. La valeur par défaut est LOCAL. Elle est utilisée s'il n'est pas possible de déduire le fuseau horaire d'après datetime_format.

dans le fichier

Spécifie les fichiers journaux que vous souhaitez transférer à CloudWatch Logs. file peut pointer vers un fichier spécifique ou plusieurs fichiers (à l'aide de caractères génériques tels que /var/log/system.log*). Seul le dernier fichier est transmis à CloudWatch Logs, selon l'heure de modification du fichier. Nous vous recommandons d'utiliser des caractères génériques pour spécifier une série de fichiers du même type, comme access_log.2014-06-01-01, access_log.2014-06-01-02 et ainsi de suite, mais pas pour différents types de fichiers, comme access_log_80 et access_log_443. Pour spécifier plusieurs types de fichiers, ajoutez une autre entrée de flux de journaux dans le fichier de configuration, afin que chaque type de fichier journal soit envoyé dans un flux de journal différent. Les fichiers zippés ne sont pas pris en charge.

file_fingerprint_lines

Spécifie la plage de lignes pour identifier un fichier. Les valeurs valides sont soit un nombre, soit deux nombres séparés par un tiret, par exemple, « 1 », « 2-5 ». La valeur par défaut est « 1 ». La première ligne est utilisée pour calculer l'empreinte. Les lignes d'empreinte ne sont pas envoyées à CloudWatch Logs, sauf si toutes les lignes spécifiées sont disponibles.

multi_line_start_pattern

Spécifie le modèle pour identifier le début d'un message de journal. Un message de journal est composé de plusieurs lignes : une ligne correspondant au modèle et les lignes suivantes qui ne correspondent pas au modèle. Les valeurs valides sont les expressions régulières ou {datetime_format}. Lorsque vous utilisez {datetime_format}, l'option datetime_format doit être spécifiée. La valeur par défaut est « ^[^\s] ». Ainsi, toute ligne commençant par un caractère autre qu'un espace ferme le message de journal précédent et commence un nouveau message de journal.

initial_position

Spécifie l'endroit où commencer à lire les données (start_of_file ou end_of_file). La valeur par défaut est start_of_file. Utilisé uniquement si aucun état n'est conservé pour ce flux de journaux.

encoding

Spécifie l'encodage du fichier journal pour que le fichier puisse être lu correctement. La valeur par défaut est utf_8. L'encodage pris en charge par Python codecs.decode() peut être utilisé ici.

Avertissement

Le fait de spécifier un encodage incorrect peut entraîner une perte de données, car les caractères qui ne peuvent pas être décodés seront remplacés par un autre caractère.

Voici une liste d'encodages courants :

ascii, big5, big5hkscs, cp037, cp424, cp437, cp500, cp720, cp737, cp775, cp850, cp852, cp855, cp856, cp857, cp858, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp875, cp932, cp949, cp950, cp1006, cp1026, cp1140, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, euc_jp, euc_jis_2004, euc_jisx0213, euc_kr, gb2312, gbk, gb18030, hz, iso2022_jp, iso2022_jp_1, iso2022_jp_2, iso2022_jp_2004, iso2022_jp_3, iso2022_jp_ext, iso2022_kr, latin_1, iso8859_2, iso8859_3, iso8859_4, iso8859_5, iso8859_6, iso8859_7, iso8859_8, iso8859_9, iso8859_10, iso8859_13, iso8859_14, iso8859_15, iso8859_16, johab, koi8_r, koi8_u, mac_cyrillic, mac_greek, mac_iceland, mac_latin2, mac_roman, mac_turkish, ptcp154, shift_jis, shift_jis_2004, shift_jisx0213, utf_32, utf_32_be, utf_32_le, utf_16, utf_16_be, utf_16_le, utf_7, utf_8, utf_8_sig

buffer_duration

Spécifie la durée du regroupement des événements de journaux. La valeur minimale est 5 000 m et la valeur par défaut est 5 000 ms.

batch_count

Spécifie le nombre maximal d'événements de journaux dans un lot. La valeur maximale est 10 000. La valeur par défaut est 10 000.

batch_size

Spécifie la taille maximale des événements de journaux dans un lot, en octets. La taille maximale est 1 048 576 octets. La valeur par défaut est 1 048 576 octets. Cette taille est calculée comme étant la somme de tous les messages d'événement au format UTF-8, plus 26 octets pour chaque événement de journal.

Utilisation de l'agent CloudWatch Logs avec les proxys HTTP

Vous pouvez utiliser l'agent CloudWatch Logs avec les proxys HTTP.

Note

Les proxys HTTP sont pris en charge dans les versions awslogs-agent-setup.py 1.3.8 ou ultérieures.

Pour utiliser l'agent CloudWatch Logs avec les proxys HTTP

  1. Effectuez l'une des actions suivantes :

    1. S'il s'agit d'une nouvelle installation de l'agent CloudWatch Logs, exécutez les commandes suivantes :

      curl https://s3.amazonaws.com/aws-cloudwatch/downloads/latest/awslogs-agent-setup.py -O
      sudo python awslogs-agent-setup.py --region us-east-1 --http-proxy http://your/proxy --https-proxy http://your/proxy --no-proxy 169.254.169.254

      Pour conserver l'accès au service de métadonnées Amazon EC2 sur les instances EC2, utilisez --no-proxy 169.254.169.254 (recommandé). Pour plus d'informations, consultez Métadonnées d'instance et données utilisateur dans le Guide de l'utilisateur Amazon EC2 pour les instances Linux.

      Dans les valeurs pour http-proxy et https-proxy, vous spécifiez la totalité de l'URL.

    2. S'il s'agit d'une installation existante de l'agent CloudWatch Logs, modifiez /var/awslogs/etc/proxy.conf et ajoutez vos proxys :

      HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=

  2. Redémarrez l'agent pour que les modifications prennent effet :

    sudo service awslogs restart

    Si vous utilisez Amazon Linux 2, utilisez la commande suivante pour redémarrer l'agent :

    sudo service awslogsd restart

Cloisonnement des fichiers de configuration de l'agent CloudWatch Logs

Si vous utilisez awslogs-agent-setup.py version 1.3.8 ou ultérieure avec awscli-cwlogs version 1.3.3 ou ultérieure, vous pouvez importer différentes configurations de flux pour différents composants indépendamment les uns des autres en créant des fichiers de configuration supplémentaires dans le répertoire /var/awslogs/etc/config/. Lorsque l'agent CloudWatch Logs démarre, il inclut les configurations de flux dans ces fichiers de configuration supplémentaires. Les propriétés de configuration de la section [general] doivent être définies dans le fichier de configuration principal (/var/awslogs/etc/awslogs.conf) et seront ignorées dans les fichiers de configuration supplémentaires enregistrés dans le répertoire /var/awslogs/etc/config/.

Si vous n'avez pas de répertoire /var/awslogs/etc/config/ car vous avez installé l'agent avec rpm, vous pouvez utiliser le répertoire /etc/awslogs/config/ à la place.

Redémarrez l'agent pour que les modifications prennent effet :

sudo service awslogs restart

Si vous utilisez Amazon Linux 2, utilisez la commande suivante pour redémarrer l'agent :

sudo service awslogsd restart

FAQ sur l'agent CloudWatch Logs

Quels sont les types de rotations de fichier pris en charge ?

Les mécanismes de rotation de fichier suivants sont pris en charge :

  • Ajout d'un suffixe numérique aux noms des fichiers journaux existants, puis recréation du fichier journal vide d'origine. Par exemple, /var/log/syslog.log est renommé /var/log/syslog.log.1. Si /var/log/syslog.log.1 existe déjà d'une rotation précédente, il est renommé /var/log/syslog.log.2.

  • Troncation du fichier journal d'origine après la création d'une copie. Par exemple, /var/log/syslog.log est copié dans /var/log/syslog.log.1 et /var/log/syslog.log est tronqué. Cela peut entraîner une perte de données. Soyez prudent lors de l'utilisation de ce mécanisme de rotation de fichier.

  • Création d'un fichier avec un modèle commun à l'ancien. Par exemple, /var/log/syslog.log.2014-01-01 est conservé et /var/log/syslog.log.2014-01-02 est créé.

L'empreinte (ID de la source) du fichier est calculée en hachant la clé du flux de journal et la première ligne du contenu du fichier. Pour remplacer ce comportement, l'option file_fingerprint_lines peut être utilisée. Lorsque la rotation de fichier se produit, le nouveau fichier doit comporter le nouveau contenu et aucun contenu ne doit être ajouté à l'ancien fichier. L'agent transfère le nouveau fichier une fois qu'il a terminé de lire l'ancien.

Comment déterminer la version de l'agent que j'utilise ?

Si vous avez utilisé le script d'installation pour installer l'agent CloudWatch Logs vous pouvez utiliser /var/awslogs/bin/awslogs-version.sh pour vérifier la version de l'agent que vous utilisez. Vous pouvez ainsi afficher la version de l'agent et ses principales dépendances. Si vous avez utilisé yum pour installer l'agent CloudWatch Logs, vous pouvez utiliser « yum info awslogs » et « yum info aws-cli-plugin-cloudwatch-logs » pour vérifier la version de l'agent CloudWatch Logs et le plug-in.

Comment les entrées de journaux sont-elles converties en événements de journaux ?

Les événements de journaux contiennent deux propriétés : l'horodatage du moment où l'événement s'est produit et le message brut du journal. Par défaut toute ligne commençant par un caractère autre qu'un espace ferme le message de journal précédent, le cas échéant, et commence un nouveau message de journal. Pour remplacer ce comportement, multi_line_start_pattern peut être utilisé et n'importe quelle ligne correspondant au modèle commence un nouveau message de journal. Le modèle peut être n'importe quelle expression régulière ou « {datetime_format} ». Par exemple, si la première ligne de chaque message de journal contient un horodatage comme « 2014-01-02T13:13:01Z », multi_line_start_pattern peut être défini sur « \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z ». Pour simplifier la configuration, la variable « {datetime_format} » peut être utilisée si l'option datetime_format a été spécifiée. Pour le même exemple, si l'option datetime_format est définie sur « %Y-%m-%dT%H:%M:%S%z », alors multi_line_start_pattern peut simplement être « {datetime_format} ».

L'heure actuelle est utilisée pour chaque événement de journal si datetime_format n'est pas fourni. Si la valeur datetime_format fournie n'est pas valide pour un message de journal donné, l'horodatage du dernier événement de journal dont l'horodatage a été analysé avec succès sera utilisé. En cas d'absence d'événements de journaux précédents, l'heure actuelle est utilisée. Un message d'avertissement est enregistré lorsqu'un événement de journal utilise l'heure actuelle ou l'heure de l'événement de journal précédent.

Les horodatages sont utilisés pour récupérer les événements de journaux et générer des métriques. Ainsi, si vous spécifiez un format incorrect, les événements des journaux peuvent ne plus être récupérables et générer des métriques incorrectes.

Comment les événements de journaux sont-ils regroupés par lot ?

Lorsque l'une des conditions suivantes est remplie, un lot devient plein et est publié :

  1. La durée buffer_duration s'est écoulée depuis l'ajout du premier événement de journal.

  2. Moins de batch_size d'événements de journaux ont été accumulés, mais l'ajout du nouvel événement de journal entraîne le dépassement défini par batch_size.

  3. Le nombre d'événements de journaux a atteint la valeur définie dans batch_count.

  4. Les événements de journaux du lot ne s'étendent pas sur plus de 24 heures, mais l'ajout du nouvel événement de journal entraîne le dépasse la limite de 24 heures.

Pour quelle raison des entrées de journal, des événements de journaux ou des lots seraient-ils ignorés ou tronqués ?

Pour respecter la contrainte de l'opération PutLogEvents, un événement de journal ou un lot peut être ignoré à cause des problèmes suivants.

Note

L'agent CloudWatch Logs écrit un avertissement dans le journal lorsque des données sont ignorées.

  1. Si la taille d'un événement de journal dépasse 256 Ko, ce dernier sera complètement ignoré.

  2. Si l'horodatage d'un événement de journal est supérieur à 2 heures par rapport à l'heure actuelle, l'événement de journal est ignoré.

  3. Si l'horodatage d'un événement de journal est antérieur de plus de 14 jours au jour actuel, l'événement de journal est ignoré.

  4. Si un événement de journal est antérieur à la période de conservation du groupe de journaux, l'ensemble du lot est ignoré.

  5. Si le lot des événements de journaux d'une seule requête PutLogEvents s'étend sur plus de 24 heures, l'opération PutLogEvents échoue.

L'arrêt de l'agent entraîne-t-il la perte ou la duplication de données ?

Non, à condition que le fichier d'état soit disponible et qu'aucune rotation de fichier ne se soit produite depuis la dernière exécution. L'agent CloudWatch Logs peut reprendre là où il s'est arrêté et continuer à transmettre les données de journaux.

Puis-je pointer différents fichiers journaux depuis un seul ou plusieurs hôtes vers le même flux de journaux ?

La configuration de plusieurs sources de journal pour envoyer des données dans un flux de journal unique n'est pas prise en charge.

Quels appels d'API l'agent effectue-t-il (ou quelles actions dois-je ajouter à ma politique IAM) ?

L'agent CloudWatch Logs requiert les opérations CreateLogGroup, CreateLogStream, DescribeLogStreams et PutLogEvents. Si vous utilisez le dernier agent, DescribeLogStreams n'est pas nécessaire. Consultez l'exemple de politique IAM ci-dessous.

{
"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action": [
      "logs:CreateLogGroup",
      "logs:CreateLogStream",
      "logs:PutLogEvents",
      "logs:DescribeLogStreams"
    ],
    "Resource": [
      "arn:aws:logs:*:*:*"
    ]
  }
 ]
}
Je ne souhaite pas que l'agent CloudWatch Logs crée automatiquement des groupes de journaux ou des flux de journaux. Comment puis-je empêcher l'agent de recréer des groupes de journaux et des flux de journaux ?

Dans la politique IAM, vous pouvez limiter l'agent afin qu'il puisse uniquement effectuer les opérations suivantes : DescribeLogStreams, PutLogEvents.

Avant de révoquer les autorisations CreateLogStream et CreateLogGroup à partir de l'agent, veillez à créer à la fois les groupes de journaux et les flux de journaux que vous souhaitez que l'agent utilise. L'agent de journaux ne peut pas créer de flux de journaux dans un groupe de journaux que vous avez créé, sauf s'il dispose des autorisations CreateLogGroup et CreateLogStream.

Quels journaux consulter pour résoudre les problèmes ?

Le journal d'installation de l'agent est enregistré à l'adresse /var/log/awslogs-agent-setup.log et le journal de l'agent à l'adresse /var/log/awslogs.log.