CloudWatch Logs 代理程式參考 - Amazon CloudWatch 日誌
代理程式組態檔案透過 HTTP 代理使用 CloudWatch Logs 代理程式分隔 CloudWatch Logs 代理程式組態檔案CloudWatch Logs 代理程式常見問答集

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CloudWatch Logs 代理程式參考

重要

此參考適用於已廢除的舊版 CloudWatch Logs 代理程式。如果使用執行個體中繼資料服務第 2 版 (IMDSv2)，則必須使用新的統一 CloudWatch 代理程式。即使您不是使用 IMDSv2，我們仍強烈建議您使用較新的統一 CloudWatch 代理程式，不要使用舊版的日誌代理程式。如需較新的統一代理程式的詳細資訊，請參閱《使用 CloudWatch 代理程式從 Amazon EC2 執行個體和內部部署伺服器收集指標和日誌》。

有關從舊版 CloudWatch Logs 代理程式遷移到統一代理程式的資訊，請參閱藉助精靈建立 CloudWatch 代理程式組態檔案。

CloudWatch Logs 代理程式可自動將日誌資料從 Amazon EC2 執行個體傳送至 CloudWatch Logs。代理程式包含下列元件：

  • AWS CLI 的外掛程式，將日誌資料推送至 CloudWatch Logs。

  • 指令碼 (常駐程式)，起始將資料推送至 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

以下範例會將讀取者和發佈者的層級變更為 WARNING，而預設值為 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

設為 true (預設) 時會啟用 gzip http 內容編碼，將壓縮的酬載傳送至 CloudWatch Logs。這會降低 CPU 使用量、降低 NetworkOut 及減少推送延遲。若要停用此功能，請將 use_gzip_http_content_encoding = false 新增至 CloudWatch Logs 代理程式組態檔案的 [general] 區段，然後重新啟動代理程式。

注意

此設定僅適用於 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_format 代碼、datetime.strptime()。亦支援時區位移 (%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。如果無法依據 datetime_format 推斷時區，預設值為 LOCAL。

file

指定您要推送到 CloudWatch Logs 的日誌檔。檔案可指向特定檔案或多個檔案 (使用萬用字元，例如 /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

指定批次中的日誌事件最大數量，最多可達 10,000。預設值為 10000。

batch_size

指定批次中的日誌事件最大大小，以位元組為單位，最多可達 1048576 位元組。預設值為 1048576 位元組。這個大小的計算方式是以所有 UTF-8 事件訊息，加上每個記錄事件 26 個位元組。

透過 HTTP 代理使用 CloudWatch Logs 代理程式

您可以透過 HTTP 代理來使用 CloudWatch Logs 代理程式。

注意

awslogs-agent-setup.py 1.3.8 或更新版本支援 HTTP 代理。

透過 HTTP 代理使用 CloudWatch Logs 代理程式

  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 Linux 執行個體使用者指南》中的執行個體中繼資料和使用者資料。

      在 http-proxy 和 https-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，符合此模式的任何列都會開始新的日誌訊息。此模式可以是任何 regex 或「{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 option，您可以使用「{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 代理程式需要 CreateLogGroup、CreateLogStream、DescribeLogStreams 和 PutLogEvents 操作。如果您使用的是最新的代理程式，則不需要 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 政策中限制代理程式只能執行以下操作：DescribeLogStreams、PutLogEvents。

從代理程式撤銷 CreateLogGroup 和 CreateLogStream 許可前，請務必建立您要讓代理程式使用的日誌群組和日誌串流。日誌代理程式無法在您已建立的日誌群組中建立日誌串流，除非其擁有 CreateLogGroup 和 CreateLogStream 許可。

進行故障排除時，我應該查看哪些日誌？

代理程式安裝日誌位於 /var/log/awslogs-agent-setup.log，代理程式日誌位於 /var/log/awslogs.log。