本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # CloudWatch 日志代理参考 **重要** 本节仅供那些使用已弃用的 Log CloudWatch s 代理的用户参考。如果您使用的是实例元数据服务版本 2 (IMDSv2)，则必须使用新的统一 CloudWatch 代理。但是，即使您没有使用 IMDSv2，我们也强烈建议您使用较新的统一 CloudWatch 代理，而不是已弃用的 CloudWatch Logs 代理。有关更新的统一 CloudWatch 代理的信息，请参阅[使用代理从 Amazon EC2 实例和本地服务器收集指标和日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 CloudWatch 有关从已弃用的 CloudWatch Logs 代理迁移到统一代理的信息，[请使用向导创建 CloudWatch 代理配置文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file-wizard.html)。 CloudWatch 日志代理提供了一种自动将日志数据从 Amazon EC2 实例发送到 CloudWatch 日志的方法。该代理包括以下组件： + 的插件，可 AWS CLI 将日志数据推送到 CloudWatch 日志。 + 一个脚本（守护程序），用于启动将数据推送到 Logs 的 CloudWatch 进程。 + 一个确保该守护程序始终运行的 cron 作业。 ## 代理配置文件 CloudWatch 日志代理配置文件描述了 CloudWatch 日志代理所需的信息。代理配置文件的 [general] 一节定义适用于所有日志流的通用配置。[logstream] 一节定义将本地文件发送到远程日志流所必需的信息。您可以有多个 [logstream] 节，但是每一节的名称在该配置文件中都必须唯一，如 [logstream1]、[logstream2] 等等。[logstream] 值和日志文件第一行数据共同定义日志文件的标识。 ``` [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\$1file** 指定状态文件的存储位置。 **logging\$1config\$1file** （可选）指定代理日志记录配置文件的位置。如果您未在此处指定代理日志记录配置文件，系统将使用默认文件 awslogs.conf。如果使用脚本安装代理，默认文件位置是 `/var/awslogs/etc/awslogs.conf`，如果使用 rpm 安装代理，默认文件位置是 `/etc/awslogs/awslogs.conf`。该文件采用 Python 配置文件格式（thon.org/2/library/l https://docs.py ogging.config.h logging-config-fileformat tml\$1）。可自定义具有以下名称的日志记录程序。 ``` cwlogs.push cwlogs.push.reader cwlogs.push.publisher cwlogs.push.event cwlogs.push.batch cwlogs.push.stream cwlogs.push.watcher ``` 尽管默认值为 INFO，以下示例仍会将阅读者和发布者的级别更改为 WARNING。 ``` [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\$1gzip\$1http\$1content\$1encoding** 设置为 true（默认）时，启用 gzip http 内容编码以将压缩的负载发送到 CloudWatch 日志。这可以降低 CPU 使用率 NetworkOut、降低和减少放置延迟。要禁用此功能，请将 **use\$1gzip\$1http\$1content\$1encoding = false 添加到日志代理配置文件的** **[常规]** 部分，然后重新启动代理。 CloudWatch 此设置只在 awscli-cwlogs 版本 1.3.3 和更高版本中可用。 **log\$1group\$1name** 指定目标日志组。如果还没有日志组，则会自动创建一个日志组。日志组名称的长度可介于 1 和 512 个字符之间。允许的字符包括 a–z、A–Z、0–9、“\$1”（下划线）、“-”（连字符）、“/”（正斜杠）和“.”（句点）。 **log\$1stream\$1name** 指定目标日志流。您可以使用文字字符串或预定义的变量（\$1instance\$1id\$1、\$1hostname\$1、\$1ip\$1address\$1），或这两者的组合来定义日志流名称。如果还没有日志流，则会自动创建一个日志流。 **datetime\$1format** 指定如何从日志提取时间戳。时间戳用于检索日志事件和生成指标。如果未提供 **datetime\$1format**，则将当前时间用于每个日志事件。如果提供的 **datetime\$1format** 值对于给定日志消息无效，则使用时间戳成功解析的最近日志事件的时间戳。如果不存在以前的日志事件，则使用当前时间。 下面列出了常见 datetime\$1format 代码。您也可以使用 Python datetime.strptime() 支持的所有 datetime\$1format 代码。时区偏移量（%z）也受支持（即使 Python 3.2 之前的版本都不支持它），[\$1-]HHMM，不带冒号（:）。有关更多信息，请参阅 [strftime() 和 strptime() 行为](https://docs.python.org/2/library/datetime.html#strftime-strptime-behavior)。 **%y**：年份，以零填充的十进制数字表示，不包括代表世纪的数字。00, 01, ..., 99 **%Y**：年份，以十进制数字形式表示且包括表示世纪的数字。如 1970、1988、2001、2013 **%b**：月份，使用区域设置的缩写名称形式。Jan、Feb...Dec（en\$1US）； **%B**：月份，使用区域设置的完整名称形式。January、February...December（en\$1US）； **%m**：月份，使用以零填充的十进制数字形式。01, 02, ..., 12 **%d**：月份中的日期，使用以零填充的十进制数字形式。01, 02, ..., 31 **%H**：小时（24 小时制），使用以零填充的十进制数字形式。00, 01, ..., 23 **%I**：小时（12 小时制），使用以零填充的十进制数字形式。01, 02, ..., 12 **%p**：区域设置中等效于 AM 或 PM 的表示形式。 **%M**：分钟，使用以零填充的十进制数字形式。00, 01, ..., 59 **%S**：秒，使用以零填充的十进制数字形式。00, 01, ..., 59 **%f**：微秒，在左边使用以零填充的十进制数字形式。000000, ..., 999999 **%z**：UTC 偏移量，采用 \$1HHMM 或 -HHMM 形式。\$10000、-0400、\$11030 **示例格式：** `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\$1zone** 指定日志事件时间戳的时区。支持的两个值为 UTC 和 LOCAL。默认值为 LOCAL，如果无法基于 **datetime\$1format** 推断时区，则将使用此默认值。 **文件** 指定要推送到 Lo CloudWatch gs 的日志文件。文件可以指向一个或多个文件（使用通配符，例如/var/log/system.log\$1）。根据文件修改时间，只有最新的文件才会被推送到 CloudWatch 日志。我们建议您使用通配符指定同一类型的一系列文件（如 access\$1log.2014-06-01-01、access\$1log.2014-06-01-02 等）而不是多个类型的文件（如 access\$1log\$180 和 access\$1log\$1443）。要指定多个类型的文件，请在配置文件中再添加一个日志流条目，让每一种日志文件转到不同的日志流。不支持压缩文件。 **file\$1fingerprint\$1lines** 指定用于识别文件的行范围。有效值是一个数字或两个用短划线分隔的数字，如“1”、“2-5”。默认值是“1”，因此第一行用于计算指纹。除非所有指定的行都可用，否则指纹线不会发送到 CloudWatch 日志。 **multi\$1line\$1start\$1pattern** 指定用于识别日志消息开头的模式。日志消息由与模式匹配的行以及与模式不匹配的任何以下行组成。有效值为正则表达式或 \$1datetime\$1format\$1。使用 \$1datetime\$1format\$1 时，应指定 datetime\$1format 选项。默认值为“^[^\$1s]”，因此以非空格字符开头的任何行都会使上一个日志消息结束，并开始新的日志消息。 **initial\$1position** 指定从何处开始读取数据（start\$1of\$1file 或 end\$1of\$1file）。默认位置是 start\$1of\$1file。仅当日志流没有持续状态时才会使用它。 **编码** 指定日志文件的编码，以便正确读取该文件。默认编码为 utf\$18。Python codecs.decode() 支持的编码可在此处使用。 指定错误的编码可能导致数据丢失，因为无法解码的字符将被其他字符替代。 以下是一些常见编码： `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\$1duration** 指定日志事件批量处理的时间段。最小值为 5000ms，默认值为 5000ms。 **batch\$1count** 指定批处理中的日志事件的最大数量（最大为 10000）。默认值是 10000。 **batch\$1size** 指定批处理中的日志事件的最大大小（以字节为单位，最大为 1048576 字节）。默认值为 1048576 字节。此大小的计算方式是 UTF-8 格式的所有事件消息之和加上代表每个日志事件的 26 字节。 ## 使用带有 HTTP 代理的 CloudWatch 日志代理 您可以将 CloudWatch 日志代理与 HTTP 代理一起使用。 **注意** awslogs-agent-setup.py 版本 1.3.8 或更高版本支持 HTTP 代理。 **将 CloudWatch 日志代理与 HTTP 代理配合使用** 1. 请执行以下操作之一： 1. 要全新安装 CloudWatch Logs 代理，请运行以下命令： ``` 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 ``` 为了维护在 EC2 实例上对 Amazon EC2 元数据服务的访问，请使用 **--no-proxy 169.254.169.254**（建议）。有关更多信息，请参阅《*Amazon EC2 用户指南*》中的[实例元数据和用户数据](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)。 在 `http-proxy` 和 `https-proxy` 的值中，您指定完整 URL。 1. 要安装现有的 CloudWatch Logs 代理，请编辑/ var/awslogs/etc/proxy .conf，然后添加您的代理： ``` HTTP_PROXY= HTTPS_PROXY= NO_PROXY= ``` 1. 重新启动代理以使更改生效： ``` sudo service awslogs restart ``` 如果您使用的是 Amazon Linux 2，请使用以下命令重新启动代理： ``` sudo service awslogsd restart ``` ## 划分 CloudWatch 日志代理配置文件 **如果您在 awscli-cwlogs 1.3.3 或更高版本中使用 awslogs-agent-setup .py 版本 1.3.8 或更高版本，则可以通过在//目录中创建其他配置文件来为各种组件独立导入不同的流配置。var/awslogs/etc/config**当 CloudWatch Logs 代理启动时，它会在这些附加配置文件中包含所有流配置。[常规] 部分中的配置属性必须在主配置文件中定义 (/var/awslogs/etc/awslogs.conf) and are ignored in any additional configuration files found in /var/awslogs/etc/config/. 如果因为使用 rpm 安装代理而没有 **var/awslogs/etc/config//**目录，则可以改用 **etc/awslogs/config//**目录。 重新启动代理以使更改生效： ``` sudo service awslogs restart ``` 如果您使用的是 Amazon Linux 2，请使用以下命令重新启动代理： ``` sudo service awslogsd restart ``` ## CloudWatch 日志代理常见问题解答 **支持哪些类型的文件轮换？** 支持以下文件轮换机制： + 用数字后缀为现有日志文件命名，然后重新创建原始的空日志文件。例如，/var/log/syslog.log is renamed /var/log/syslog.log.1. If /var/log/syslog.log.1 already exists from a previous rotation, it is renamed /var/log/syslog.log.2。 + 在创建副本后截断原始日志文件。例如，/var/log/syslog.log is copied to /var/log/syslog.log.1 and /var/log/syslog.log 被截断。这种情况下可能会有数据丢失，因此请谨慎使用这种文件轮换机制。 + 使用与旧文件相同的通用模式创建新文件。例如，/var/log/syslog.log.2014-01-01 remains and /var/log/syslog.log.2014-01-02 已创建。 文件的指纹（源 ID）是通过将日志流键和文件内容第一行进行哈希处理计算得到的。要覆盖此行为，可以使用 **file\$1fingerprint\$1lines** 选项。当文件进行轮换时，新文件应该有新内容，旧文件不应追加内容；代理将在完成旧文件的读取后推送新文件。 **如何确定我使用的是哪个版本的代理？** 如果您使用安装脚本来安装 CloudWatch Logs 代理，则可以使用**/var/awslogs/bin/awslogs-version.sh** 来检查您使用的代理版本。它会打印代理的版本及其主要依赖关系。如果你使用 yum 安装 CloudWatch 日志代理，你可以使用 **“yum info awslogs” 和 “yum info aws-cli-plugin-cloudwatch** **-logs”** 来检查 Logs 代理和插件的版本。 CloudWatch **日志条目如何转换为日志事件？** 日志事件包含两个属性：事件发生时的时间戳，以及原始日志消息。默认情况下，以非空格字符开头的任何行都会使上一个日志消息结束（如果存在），并开始新的日志消息。要覆盖此行为，可以使用 **multi\$1line\$1start\$1pattern**，与模式匹配的任何行都开始新的日志消息。模式可以是任何正则表达式或“\$1datetime\$1format\$1”。例如，如果每个日志消息的第一行都包含类似于“2014-01-02T13:13:01Z”的时间戳，则 **multi\$1line\$1start\$1pattern** 可以设置为“\$1d\$14\$1-\$1d\$12\$1-\$1d\$12\$1T\$1d\$12\$1:\$1d\$12\$1:\$1d\$12\$1Z”。要简化配置，可以在指定 **datetime\$1format 选项**的情况下使用“\$1datetime\$1format\$1”变量。对于同一个示例，如果 **datetime\$1format** 设置为“%Y-%m-%dT%H:%M:%S%z”，则 multi\$1line\$1start\$1pattern 可以仅仅是“\$1datetime\$1format\$1”。 如果未提供 **datetime\$1format**，则将当前时间用于每个日志事件。如果提供的 **datetime\$1format** 对于给定日志消息无效，则使用时间戳成功解析的最近日志事件的时间戳。如果不存在以前的日志事件，则使用当前时间。当日志事件回退到当前时间或上一个日志事件的时间时，会记录一个警告消息。 时间戳用于检索日志事件和生成指标，因此，如果您指定错误的格式，则可能无法检索日志事件，生成错误的指标。 **日志事件如何批处理？** 满足以下任意条件时，表示批次已满并且将发布： 1. 从添加第一个日志事件以来，时间已经过了 **buffer\$1duration**。 1. 累积的日志事件小于 **batch\$1size**，但添加新的日志事件则会超出 **batch\$1size**。 1. 日志事件的数量已达到 **batch\$1count**。 1. 批处理中的日志事件的时间跨度不超过 24 小时，但添加新日志事件会超出 24 小时的限制。 **什么原因可能导致跳过或截断日志条目、日志事件或批次？** 为遵循 `PutLogEvents` 操作的限制，需注意，以下问题可能导致跳过日志事件或批次。 跳过数据时，Log CloudWatch s 代理会在其日志中写入警告。 1. 如果日志事件的大小超过 256 KB，则将完全跳过日志事件。 1. 如果日志事件的时间戳晚于未来 2 小时，则跳过日志事件。 1. 如果日志事件的时间戳早于过去 14 天，则跳过日志事件。 1. 如果任何日志事件的存在时间超过日志组的保留期，则跳过整个批次。 1. 如果单个 `PutLogEvents` 请求中的一批日志事件时间跨度超过 24 小时，则 `PutLogEvents` 操作将失败。 **停止代理会导致数据丢失/重复条目吗？** 只要状态文件可用，且从上次运行以来没有发生文件轮换，则不会。 CloudWatch Logs 代理可以从其停止的地方开始并继续推送日志数据。 **我可以将来自相同或不同主机的不同日志文件指向同一个日志流吗？** 不支持配置多个日志源将数据发送到单个日志流。 **代理调用哪些 API（或我应该将哪些操作添加到 IAM 策略中）？** L CloudWatch ogs 代理需要权限才能执行`CreateLogGroup``CreateLogStream`、`DescribeLogStreams`、`DescribeLogGrooupd`、`PutLogEvents`和`PutRetentionPolicy`操作。如果您使用最新的代理，则不需要 `DescribeLogStreams`。请参阅以下 IAM 策略示例。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "logs:DescribeLogGroups", "logs:PutRetentionPolicy" ], "Resource": [ "arn:aws:logs:*:*:*" ] } ] } ``` **我不想让 L CloudWatch ogs 代理自动创建日志组或日志流。我如何阻止代理重新创建日志组和日志流？** 在您的 IAM 策略中，您可以限制该代理仅执行以下操作：`DescribeLogStreams` 和 `PutLogEvents`。 在撤销代理的 `CreateLogGroup` 和 `CreateLogStream` 权限之前，请确保创建希望代理使用的日志组和日志流。如果日志代理没有 `CreateLogGroup` 和 `CreateLogStream` 权限，它将无法在您创建的日志组中创建日志流。 **在进行故障排除时我应当查看哪些日志？** 代理安装日志位于 `/var/log/awslogs-agent-setup.log`，代理日志位于 `/var/log/awslogs.log`。