CloudWatch Logs 代理参考 - Amazon CloudWatch 日志
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

CloudWatch Logs 代理参考

重要

此参考适用于已弃用的较旧 CloudWatch Logs 代理。如果您使用 Instance Metadata Service Version 2 (IMDSv2),则必须使用新的统一 CloudWatch 代理。即便您未使用 IMDSv2,我们强烈建议您使用较新的统一 CloudWatch 代理,而不是较旧的日志代理。有关较新的统一代理的更多信息,请参阅使用 CloudWatch 代理从 Amazon EC2 实例和本地服务器中收集指标和日志

有关从较旧 CloudWatch Logs 代理迁移到统一代理的信息,请参阅通过向导创建 CloudWatch 代理配置文件

CloudWatch Logs 代理提供一种从 Amazon EC2 实例将日志数据发送到 CloudWatch Logs 的自动化方式。该代理包括以下组件:

  • 一个将日志数据推送到 CloudWatch Logs 的 Amazon CLI 插件。

  • 一个启动进程以将数据推送到 CloudWatch Logs 的脚本(守护进程)。

  • 一个确保该守护程序始终运行的 cron 作业。

代理配置文件

CloudWatch Logs 代理配置文件描述 CloudWatch Logs 代理所需的信息。代理配置文件的 [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_file

指定状态文件的存储位置。

logging_config_file

(可选)指定代理日志记录配置文件的位置。如果您未在此处指定代理日志记录配置文件,系统将使用默认文件 awslogs.conf。如果使用脚本安装代理,默认文件位置是 /var/awslogs/etc/awslogs.conf,如果使用 rpm 安装代理,默认文件位置是 /etc/awslogs/awslogs.conf。此文件采用 Python 配置文件格式 (https://docs.python.org/2/library/logging.config.html#logging-config-fileformat)。可自定义具有以下名称的日志记录程序。

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_gzip_http_content_encoding

在设置为 true(默认值)时,启用 gzip http 内容编码来将压缩的负载发送到 CloudWatch Logs。这可以降低 CPU 使用率,减少 NetworkOut,并降低放入延迟。要禁用该功能,请在 CloudWatch Logs 代理配置文件的 [general] 节中添加 use_gzip_http_content_encoding = false,然后重新启动代理。

注意

此设置只在 awscli-cwlogs 版本 1.3.3 和更高版本中可用。

log_group_name

指定目标日志组。如果还没有日志组,则会自动创建一个日志组。日志组名称的长度可介于 1 和 512 个字符之间。允许的字符包括 a–z、A–Z、0–9、“_”(下划线)、“-”(连字符)、“/”(正斜杠)和“.”(句点)。

log_stream_name

指定目标日志流。您可以使用文字字符串或预定义的变量({instance_id}、{hostname}、{ip_address}),或这两者的组合来定义日志流名称。如果还没有日志流,则会自动创建一个日志流。

datetime_format

指定如何从日志提取时间戳。时间戳用于检索日志事件和生成指标。如果未提供 datetime_format,则将当前时间用于每个日志事件。如果提供的 datetime_format 值对于给定日志消息无效,则使用时间戳成功解析的最近日志事件的时间戳。如果不存在以前的日志事件,则使用当前时间。

下面列出了常见 datetime_format 代码。您也可以使用 Python datetime.strptime() 支持的所有 datetime_format 代码。时区偏移量 (%z) 也受支持(即使 Python 3.2 之前的版本都不支持它),[+-]HHMM,不带冒号 (:)。有关更多信息,请参阅 strftime() 和 strptime() 行为

%y:年份,以零填充的十进制数字表示,不包括代表世纪的数字。00, 01, ..., 99

%Y:年份,以十进制数字形式表示且包括表示世纪的数字。如 1970、1988、2001、2013

%b:月份,使用区域设置的缩写名称形式。Jan、Feb...Dec (en_US);

%B:月份,使用区域设置的完整名称形式。January,February...December (en_US);

%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 偏移量,采用 +HHMM 或 -HHMM 形式。+0000、-0400、+1030

示例格式:

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

指定日志事件时间戳的时区。支持的两个值为 UTC 和 LOCAL。默认值为 LOCAL,如果无法基于 datetime_format 推断时区,则将使用此默认值。

file

指定您要推送到 CloudWatch Logs 的日志文件。File 可以指向一个特定文件或多个文件(使用通配符,如 /var/log/system.log*)。根据文件修改时间,只有最新文件才会推送到 CloudWatch Logs。我们建议您使用通配符指定同一类型的一系列文件(如 access_log.2014-06-01-01、access_log.2014-06-01-02 等)而不是多个类型的文件(如 access_log_80 和 access_log_443)。要指定多个类型的文件,请在配置文件中再添加一个日志流条目,让每一种日志文件转到不同的日志流。不支持压缩文件。

file_fingerprint_lines

指定用于识别文件的行范围。有效值是一个数字或两个用短划线分隔的数字,如“1”、“2-5”。默认值是“1”,因此第一行用于计算指纹。除非所有指定行都可用,否则指纹不会发送到 CloudWatch Logs。

multi_line_start_pattern

指定用于识别日志消息开头的模式。日志消息由与模式匹配的行以及与模式不匹配的任何以下行组成。有效值为正则表达式或 {datetime_format}。使用 {datetime_format} 时,应指定 datetime_format 选项。默认值为“^[^\s]”,因此以非空格字符开头的任何行都会使上一个日志消息结束,并开始新的日志消息。

initial_position

指定从何处开始读取数据(start_of_file 或 end_of_file)。默认位置是 start_of_file。仅当日志流没有持续状态时才会使用它。

编码

指定日志文件的编码,以便正确读取该文件。默认编码为 utf_8。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_duration

指定日志事件批量处理的时间段。最小值为 5000ms,默认值为 5000ms。

batch_count

指定批处理中的日志事件的最大数量(最大为 10000)。默认值是 10000。

batch_size

指定批处理中的日志事件的最大大小(以字节为单位,最大为 1048576 字节)。默认值为 1048576 字节。此大小的计算方式是 UTF-8 格式的所有事件消息之和加上代表每个日志事件的 26 字节。

结合使用 CloudWatch Logs 代理与 HTTP 代理

您可以结合使用 CloudWatch Logs 代理与 HTTP 代理。

注意

在 awslogs-agent-setup.py 版本 1.3.8 或更高版本中支持 HTTP 代理。

结合使用 CloudWatch Logs 代理与 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(建议)。有关更多信息,请参阅适用于 Linux 实例的 Amazon EC2 用户指南中的实例元数据和用户数据

      http-proxyhttps-proxy 的值中,您指定完整 URL。

    2. 对于 CloudWatch Logs 代理的现有安装,请编辑 /var/awslogs/etc/proxy.conf,然后添加您的代理:

      HTTP_PROXY= HTTPS_PROXY= NO_PROXY=
  2. 重新启动代理以使更改生效:

    sudo service awslogs restart

    如果您使用的是 Amazon Linux 2,请使用以下命令重新启动代理:

    sudo service awslogsd restart

划分 CloudWatch Logs 代理配置文件

如果您正在将 awslogs-agent-setup.py 版本 1.3.8 或更高版本与 awscli-cwlogs 1.3.3 或更高版本结合使用,可以通过在 /var/awslogs/etc/config/ 目录中创建额外配置文件,独立于其他组件来导入各种组件的不同流配置。在 CloudWatch Logs 代理启动时,将在这些额外的配置文件中包含所有流配置。[general] 节中的配置属性必须在主配置文件 (/var/awslogs/etc/awslogs.conf) 中定义,并且在 /var/awslogs/etc/config/ 中找到的任何额外配置文件中将被忽略。

如果您是使用 rpm 安装的代理,因此没有 /var/awslogs/etc/config/ 目录,则可以使用 /etc/awslogs/config/ 目录代替。

重新启动代理以使更改生效:

sudo service awslogs restart

如果您使用的是 Amazon Linux 2,请使用以下命令重新启动代理:

sudo service awslogsd restart

CloudWatch Logs 代理常见问题

支持哪些类型的文件轮换?

支持以下文件轮换机制:

  • 用数字后缀为现有日志文件命名,然后重新创建原始的空日志文件。例如,/var/log/syslog.log 重命名为 /var/log/syslog.log.1。如果 /var/log/syslog.log.1 从上次轮换起就已存在,则重命名为 /var/log/syslog.log.2。

  • 在创建副本后截断原始日志文件。例如,/var/log/syslog.log 复制到 /var/log/syslog.log.1,会截断 /var/log/syslog.log。这种情况下可能会有数据丢失,因此请谨慎使用这种文件轮换机制。

  • 使用与旧文件相同的通用模式创建新文件。例如,/var/log/syslog.log.2014-01-01 仍然保留,将创建 /var/log/syslog.log.2014-01-02。

文件的指纹(源 ID)是通过将日志流键和文件内容第一行进行哈希处理计算得到的。要覆盖此行为,可以使用 file_fingerprint_lines 选项。当文件进行轮换时,新文件应该有新内容,旧文件不应追加内容;代理将在完成旧文件的读取后推送新文件。

如何确定我使用的是哪个版本的代理?

如果您使用设置脚本安装了 CloudWatch Logs 代理,则可以使用 /var/awslogs/bin/awslogs-version.sh 来检查您使用的是哪个版本的代理。它会打印代理的版本及其主要依赖关系。如果您用 yum 安装了 CloudWatch Logs 代理,则可以使用“yum info awslogs”“yum info aws-cli-plugin-cloudwatch-logs”来检查 CloudWatch Logs 代理和插件的版本。

日志条目如何转换为日志事件?

日志事件包含两个属性:事件发生时的时间戳,以及原始日志消息。默认情况下,以非空格字符开头的任何行都会使上一个日志消息结束(如果存在),并开始新的日志消息。要覆盖此行为,可以使用 multi_line_start_pattern,与模式匹配的任何行都开始新的日志消息。模式可以是任何正则表达式或“{datetime_format}”。例如,如果每个日志消息的第一行都包含类似于“2014-01-02T13:13:01Z”的时间戳,则 multi_line_start_pattern 可以设置为“\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z”。要简化配置,可以在指定 datetime_format 选项的情况下使用“{datetime_format}”变量。对于同一个示例,如果 datetime_format 设置为“%Y-%m-%dT%H:%M:%S%z”,则 multi_line_start_pattern 可以仅仅是“{datetime_format}”。

如果未提供 datetime_format,则将当前时间用于每个日志事件。如果提供的 datetime_format 对于给定日志消息无效,则使用时间戳成功解析的最近日志事件的时间戳。如果不存在以前的日志事件,则使用当前时间。当日志事件回退到当前时间或上一个日志事件的时间时,会记录一个警告消息。

时间戳用于检索日志事件和生成指标,因此,如果您指定错误的格式,则可能无法检索日志事件,生成错误的指标。

日志事件如何批处理?

满足以下任意条件时,表示批次已满并且将发布:

  1. 从添加第一个日志事件以来,时间已经过了 buffer_duration

  2. 累积的日志事件小于 batch_size,但添加新的日志事件则会超出 batch_size

  3. 日志事件的数量已达到 batch_count

  4. 批处理中的日志事件的时间跨度不超过 24 小时,但添加新日志事件会超出 24 小时的限制。

什么原因可能导致跳过或截断日志条目、日志事件或批次?

为遵循 PutLogEvents 操作的限制,需注意,以下问题可能导致跳过日志事件或批次。

注意

当跳过数据时,CloudWatch Logs 代理会在其日志中写入一条警告。

  1. 如果日志事件的大小超过 256 KB,则将完全跳过日志事件。

  2. 如果日志事件的时间戳晚于未来 2 小时,则跳过日志事件。

  3. 如果日志事件的时间戳早于过去 14 天,则跳过日志事件。

  4. 如果任何日志事件的存在时间超过日志组的保留期,则跳过整个批次。

  5. 如果单个 PutLogEvents 请求中的一批日志事件时间跨度超过 24 小时,则 PutLogEvents 操作将失败。

停止代理会导致数据丢失/重复条目吗?

只要状态文件可用,且从上次运行以来没有发生文件轮换,则不会。CloudWatch Logs 代理可以从它停止的地方启动,并继续推送日志数据。

我可以将来自相同或不同主机的不同日志文件指向同一个日志流吗?

不支持配置多个日志源将数据发送到单个日志流。

代理调用哪些 API(或我应该将哪些操作添加到 IAM 策略中)?

CloudWatch Logs 代理需要 CreateLogGroupCreateLogStreamDescribeLogStreamsPutLogEvents 操作。如果您使用最新的代理,则不需要 DescribeLogStreams。请参阅以下 IAM 策略示例。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Resource": [ "arn:aws:logs:*:*:*" ] } ] }
我不希望 CloudWatch Logs 代理自动创建日志组或日志流。我如何阻止代理重新创建日志组和日志流?

在您的 IAM 策略中,您可以限制该代理仅执行以下操作:DescribeLogStreamsPutLogEvents

在撤销代理的 CreateLogGroupCreateLogStream 权限之前,请确保创建希望代理使用的日志组和日志流。如果日志代理没有 CreateLogGroupCreateLogStream 权限,它将无法在您创建的日志组中创建日志流。

在进行故障排除时我应当查看哪些日志?

代理安装日志位于 /var/log/awslogs-agent-setup.log,代理日志位于 /var/log/awslogs.log