本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在擷取期間轉換日誌 透過日誌轉換和擴充，您可以在擷取至 CloudWatch Logs 時，以一致且內容豐富的格式將所有日誌標準化。您可以使用 AWS WAF 和 Amazon Route 53 等常見 AWS 服務的預先設定範本，或使用 [Grok](CloudWatch-Logs-Transformation-Configurable.md#CloudWatch-Logs-Transformation-Grok) 等原生剖析器建置自訂轉換器，將結構新增至日誌。您也可以重新命名現有的屬性，並將其他中繼資料新增至您的日誌，例如帳戶 ID 和區域。 日誌轉換有助於簡化和縮短跨應用程式的日誌查詢，並有助於簡化在日誌上建立提醒。此功能使用 VPC Flow 日誌、Route 53 和 等主要日誌來源out-of-the-box轉換範本，為常見的 AWS 日誌類型提供轉換 Amazon RDS for PostgreSQL。您可以使用預先設定的轉換範本，或建立自訂轉換器以符合您的需求。 日誌轉換可協助您管理從各種來源發出的日誌，這些來源的格式和屬性名稱差異很大。 建立轉換器之後，擷取的日誌事件會以標準格式轉換和儲存。您可以使用下列功能，利用這些轉換的日誌來加速分析體驗： + [欄位索引](CloudWatchLogs-Field-Indexing.md) + [CloudWatch Logs Insights 探索的欄位](CWL_AnalyzeLogData-discoverable-fields.md) + 使用[指標篩選條件](MonitoringLogData.md)警示的彈性 + 透過[訂閱篩選條件](Subscriptions.md)轉送 + 使用 [ Contributor Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html) 從日誌事件建立指標資料，您可以選擇讓 Contributor Insights 規則在日誌事件轉換之前或之後評估日誌事件。 轉換只會在日誌擷取期間發生。您無法轉換已擷取的日誌事件。轉換無法還原。原始日誌和轉換日誌都存放在具有相同保留政策的 CloudWatch Logs 中。日誌轉換和擴充功能包含在現有的標準日誌類別擷取價格中。日誌儲存成本將根據轉換後的日誌大小而定，這可能超過原始日誌磁碟區。 **重要** 日誌事件轉換後，您必須使用 CloudWatch Logs Insights 查詢來檢視日誌的轉換版本。[ GetLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetLogEvents.html) 和 [ FilterLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FilterLogEvents.html) 動作只會在轉換日誌事件之前傳回原始版本的日誌事件。 **重要** 雖然 PutLogEvents 中允許最多 1MB 的單一日誌事件，但日誌轉換只能處理大小小於 512kb 的日誌事件。任何大於 512kb 的日誌事件都會在轉換中失敗並發出錯誤。PutLogEvents 的總大小仍然可以超過 512kb。 除了轉換為不同的格式之外，您還可以使用帳戶 ID、區域和關鍵字等其他內容來豐富您的日誌。這些是從日誌群組名稱和靜態關鍵字擷取。 日誌轉換可協助您處理從各種來源發出的日誌，這些來源的格式和屬性名稱差異很大。 只有標準日誌類別中的日誌群組才支援日誌轉換和擴充。 您可以為個別日誌群組建立轉換器，也可以建立套用至您帳戶中所有或多個日誌群組的帳戶層級轉換器。如果日誌群組具有日誌群組層級轉換器，則該轉換器會覆寫任何帳戶層級轉換器，否則會套用至該日誌群組。 **Topics** + [建立和管理日誌轉換器](CloudWatch-Logs-Transformation-Create.md) + [可設定的剖析器類型處理器](CloudWatch-Logs-Transformation-Configurable.md) + [適用於 AWS 付費日誌的內建處理器](CloudWatch-Logs-Transformation-BuiltIn.md) + [字串變動處理器](CloudWatch-Logs-Transformation-StringMutate.md) + [JSON 變動處理器](CloudWatch-Logs-Transformation-JSONMutate.md) + [資料類型轉換器處理器](CloudWatch-Logs-Transformation-Datatype.md) + [轉換指標和錯誤](Transformation-Errors-Metrics.md) # 建立和管理日誌轉換器 日誌轉換器包含一或多個位於邏輯管道中的*處理器*。每個處理器都會套用到日誌事件，依序按照轉換器組態中列出的順序。 有些處理器屬於*剖析器*類型。每個轉換器必須至少有一個剖析器，而且轉換器中的第一個處理器必須是剖析器。 有些剖析器是內建的剖析器，這些剖析器針對特定類型的 AWS 付費日誌進行設定。 其他處理器類型包括字串變動器、JSON 變動器和資料處理器。 您可以為個別日誌群組建立轉換器，也可以建立套用至您帳戶中所有或多個日誌群組的帳戶層級轉換器。如果日誌群組具有日誌群組層級轉換器，則該轉換器會覆寫任何帳戶層級轉換器，否則會套用至該日誌群組。您帳戶中的區域最多可有 20 個帳戶層級轉換器。 建立轉換器時，必須遵循下列準則： + 如果您包含已 AWS 佈建日誌類型的預先設定剖析器，它必須是轉換器中列出的第一個處理器。您只能在轉換器中包含一個此類處理器。 + 您只能在轉換器中包含一個`grok`處理器。 + 您必須在轉換器中至少有一個剖析器類型處理器。您可以包含最多五個剖析器類型處理器。此限制為 5 個，包括內建剖析器和可設定的剖析器。 + 您可以在轉換器中擁有多達 20 個處理器。 + 您只能在轉換器中包含一個 **addKeys** 處理器。 + 您只能在轉換器中包含一個 **copyValue** 處理器。 + 每個轉換器最多可以從日誌事件中擷取 200 個欄位。 + 每個日誌事件**都必須**低於 512KB。日誌事件的總大小仍然可以超過 512KB。 **Topics** + [建立帳戶層級轉換器政策](CloudWatchLogs-Transformer-CreateAccountLevel.md) + [編輯或刪除帳戶層級轉換器政策](CloudWatchLogs-Transformer-EditAccountLevel.md) + [從頭開始建立log-group-level日誌轉換器](CloudWatch-Logs-Transformation-CreateNew.md) + [複製現有的log-group-level轉換器](CloudWatch-Logs-Transformation-Copy.md) + [編輯log-group-level轉換器](CloudWatch-Logs-Transformation-Edit.md) + [刪除log-group-level轉換器](CloudWatch-Logs-Transformation-Delete.md) # 建立帳戶層級轉換器政策 使用本節中的步驟來建立適用於帳戶中的所有日誌群組，或是具有以相同字串 （字首） 開頭之日誌群組名稱的多個日誌群組的轉換器政策。一個區域中最多可以有 20 個帳戶層級轉換器政策。 您無法在相同區域中建立兩個使用相同字首的轉換器政策，或另一個字首包含一個字首。例如，如果您為字串字首 建立一個轉換器政策`/aws/lambda`，則無法建立字首為 的另一個轉換器政策`/aws`。但是，您可以有一個轉換器用於 `/aws/lambda`，另一個用於 `/aws/waf` **建立帳戶層級轉換器政策** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在左側導覽窗格中，選擇**設定**，然後選擇**日誌**索引標籤。 1. 在**帳戶轉換器政策**區段中，選擇**建立轉換器政策**。 1. 針對**轉換器政策名稱**，輸入新 poiicy 的名稱。 1. 對於**選取日誌群組**，請執行下列其中一項操作： + 選擇**所有標準日誌群組**，讓轉換器政策套用至帳戶中的所有標準類別日誌群組。 + **依字首比對選擇日誌群組**，將政策套用至名稱以相同字串開頭的日誌群組子集。然後，在**選擇條件**中輸入這些日誌群組的字首。 1. 在**選取剖析器**區域中，使用**剖析器**選取要包含在轉換器中的剖析器。 如果這是已 AWS 佈建日誌類型的預先設定剖析器，則不需要為其指定任何組態。 如果是不同的剖析器，您需要指定其組態。如需詳細資訊，請參閱 中該處理器的資訊[可設定的剖析器類型處理器](CloudWatch-Logs-Transformation-Configurable.md)。 1. 若要新增另一個處理器，請選擇**選取處理器**。然後在處理器方塊中選取您想要的**處理器**，然後填入組態參數。 請記住，處理器會以您將其新增至轉換器的順序在日誌事件上操作。 1. （選用） 若要新增其他處理器，請選擇 **\$1 處理器**並重複上一個步驟。 1. （選用） 您可以隨時測試您目前在範例日誌事件上建置的轉換器。若要這樣做，請在**轉換器預覽**區段中執行下列其中一項操作： + 在選取日誌群組中選取最多五個**日誌群組**，然後選擇**載入最新的日誌事件**。然後選擇**測試轉換器**。 + 將日誌事件直接複製到**範例日誌事件**，然後選擇**測試轉換器**。 接著會出現轉換後的日誌版本。 1. 當您完成新增處理器並對範例日誌的測試感到滿意時，請選擇**儲存**。 1. 當您完成時，請選擇 **Create (建立)**。 # 編輯或刪除帳戶層級轉換器政策 使用本節中的步驟來編輯或刪除帳戶層級轉換器政策。 **編輯或刪除帳戶層級轉換器政策** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在左側導覽窗格中，選擇**設定**，然後選擇**日誌**索引標籤。 1. 在**轉換器帳戶政策**區段中，選擇**管理**。 1. 依您要管理的轉換器政策選取按鈕，然後選擇**編輯****或刪除**。 如果您要編輯政策，請參閱 中的步驟 5-11[可設定的剖析器類型處理器](CloudWatch-Logs-Transformation-Configurable.md)，查看您的選項。 # 從頭開始建立log-group-level日誌轉換器 使用這些步驟從頭開始建立log-group-level轉換器。 **使用主控台為日誌群組建立日誌轉換器** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中依序選擇 **Logs** (日誌)、**Log groups** (日誌群組)。 1. 選擇您要為其建立轉換器的日誌群組。 1. 選擇**轉換器**索引標籤。您可能需要將標籤清單向右捲動才能查看。 1. 選擇**建立轉換器**。 1. 在**選擇剖析器**方塊中，選取要包含在轉換器中的剖析器。 如果這是已 AWS 佈建日誌類型的預先設定剖析器，則不需要為其指定任何組態。 如果是不同的剖析器，您需要指定其組態。如需詳細資訊，請參閱 中該處理器的資訊[可設定的剖析器類型處理器](CloudWatch-Logs-Transformation-Configurable.md)。 1. 若要新增另一個處理器，請選擇 **\$1 新增處理器**。然後在選擇處理器方塊中選取您想要的**處理器**，然後填入組態參數。 請記住，處理器會以您將其新增至轉換器的順序在日誌事件上操作。 1. （選用） 您可以隨時測試您目前在範例日誌事件上建置的轉換器。若要這樣做，請執行下列操作： 1. 在**轉換預覽**區段中，選擇**載入範例日誌**，以從此轉換器所在的日誌群組載入範例日誌事件，或將日誌事件貼到文字方塊中。 選擇**測試轉換器**。日誌的轉換版本隨即出現 1. 當您完成新增處理器並對範例日誌的測試感到滿意時，請選擇**儲存**。 **使用 從頭 AWS CLI 建立日誌轉換器** + 使用 `aws logs put-transformer` 命令。使用 `parseJSON`做為第一個處理器時，您必須使用 `@message`做為來源欄位來剖析整個日誌事件。在初始 JSON 剖析之後，您可以在後續處理器中操作特定欄位。以下是建立包含 `parseJSON`和 `addKeys` 處理器之轉換器的範例： ``` aws logs put-transformer \ --transformer-config '[{"parseJSON":{"source":"@message"}},{"addKeys":{"entries":[{"key":"metadata.transformed_in","value":"CloudWatchLogs"},{"key":"feature","value":"Transformation"}]}},{"trimString":{"withKeys":["status"]}}]' \ --log-group-identifier my-log-group-name ``` # 複製現有的log-group-level轉換器 您可以使用 主控台來複製現有轉換器的 JSON 組態。然後，您可以使用該程式碼，使用 建立相同的轉換器 AWS CLI，也可以先修改組態。 **若要透過複製現有的日誌轉換器來建立日誌轉換器** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中依序選擇 **Logs** (日誌)、**Log groups** (日誌群組)。 1. 選擇具有您要複製之轉換器的日誌群組。 1. 選擇**轉換**索引標籤。您可能需要將標籤清單向右捲動才能查看。 1. 選擇**管理轉換器**。 1. 選擇**複製轉換器**。這會將轉換器 JSON 複製到剪貼簿。 1. 建立 檔案並貼入轉換器組態。在此範例中，我們將呼叫 檔案 `CopiedTransformer.json` 1. 使用 AWS CLI 建立具有該組態的新轉換器。 ``` aws logs put-transformer --log-group-identifier my-log-group-name \ --transformer-config file://CopiedTransformer.json ``` # 編輯log-group-level轉換器 使用這些步驟來編輯現有的日誌轉換器。 **編輯日誌轉換器** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中依序選擇 **Logs** (日誌)、**Log groups** (日誌群組)。 1. 選擇具有您要編輯之轉換器的日誌群組。 1. 選擇**轉換**索引標籤。您可能需要將標籤清單向右捲動才能查看。 1. 選擇**管理轉換器**。 1. 在**剖析器**和**處理器**區段中，進行變更。 1. 若要新增另一個處理器，請選擇 **\$1 新增處理器**。然後在處理器方塊中選取您想要的**處理器**，然後填入組態參數。 請記住，處理器會以您將其新增至轉換器的順序在日誌事件上操作。 1. （選用） 您可以隨時測試您目前在範例日誌事件上建置的轉換器。若要這樣做，請執行下列操作： 1. 在**轉換預覽**區段中，選擇**載入範例日誌**，從此轉換器的日誌群組載入範例日誌事件，或將日誌事件貼到文字方塊中。 選擇**測試轉換**。日誌的轉換版本隨即出現 1. 當您完成新增處理器並對範例日誌的測試感到滿意時，請選擇**儲存**。 # 刪除log-group-level轉換器 使用這些步驟來刪除日誌轉換器。 **刪除日誌轉換器** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中依序選擇 **Logs** (日誌)、**Log groups** (日誌群組)。 1. 選擇具有您要編輯之轉換器的日誌群組。 1. 選擇**轉換**索引標籤。您可能需要將標籤清單向右捲動才能查看。 1. 選擇 **刪除**。 1. 在確認方塊中，選擇**刪除政策**。 # 可設定的剖析器類型處理器 本節包含您可以在日誌事件轉換器中使用的可設定資料剖析器處理器的相關資訊。 **Contents** + [parseJSON](#CloudWatch-Logs-Transformation-parseJSON) + [grok](#CloudWatch-Logs-Transformation-Grok) + [Grok 範例](#Grok-Examples) + [範例 1：使用 grok 從非結構化日誌中擷取欄位](#Grok-Example1) + [範例 2：使用 grok 搭配 parseJSON 從 JSON 日誌事件擷取欄位](#Grok-Example3) + [範例 3：FIELD\$1NAME 中具有虛線註釋的 Grok 模式](#Grok-Example4) + [支援的 grok 模式](#Grok-Patterns) + [常見日誌格式範例](#Common-Log-Examples) + [Apache 日誌範例](#Apache-Log-Example) + [NGINX 日誌範例](#NGINX-Log-Example) + [Syslog 通訊協定 (RFC 5424) 日誌範例](#syslog5424-Log-Example) + [csv](#CloudWatch-Logs-Transformation-csv) + [parseKeyValue](#CloudWatch-Logs-Transformation-parseKeyValue) ## parseJSON **parseJSON** 處理器會剖析 JSON 日誌事件，並在目的地下插入擷取的 JSON 鍵值對。如果您未指定目的地，處理器會將索引鍵/值對放在根節點下方。使用 `parseJSON`做為第一個處理器時，您必須使用 `@message`做為來源欄位來剖析整個日誌事件。在初始 JSON 剖析之後，您可以在後續處理器中操作特定欄位。 原始`@message`內容不會變更，新的金鑰會新增至訊息。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | source | 要剖析之日誌事件中 欄位的路徑。使用點符號來存取子欄位。例如 store.book | 否 | `@message` | 長度上限：128 巢狀金鑰深度上限：3 | | 目的地 | 剖析 JSON 的目的地欄位 | 否 | `Parent JSON node` | 長度上限：128 巢狀金鑰深度上限：3 | **範例** 假設擷取的日誌事件如下所示： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 然後，如果我們有此 **parseJSON** 處理器： ``` [ { "parseJSON": { "destination": "new_key" } } ] ``` 轉換的日誌事件如下。 ``` { "new_key": { "outer_key": { "inner_key": "inner_value" } } } ``` ## grok 使用 grok 處理器來剖析和建構使用模式比對的非結構化資料。此處理器也可以從日誌訊息中擷取欄位。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | 備註 | | --- | --- | --- | --- | --- | --- | | source | 在 上套用 Grok 比對的欄位路徑 | 否 | `@message` | 長度上限：128 巢狀金鑰深度上限：3 | | match | 要比對日誌事件的 grok 模式 | 是 | | 長度上限：512 grok 模式上限：20 某些 grok 模式類型具有個別用量限制。下列模式的任意組合最多可以使用五次：\$1URI， URIPARAM， URIPATHPARAM， SPACE， DATA， GREEDYDATA， GREEDYDATA\$1MULTILINE\$1 Grok 模式不支援類型轉換。 對於常見日誌格式模式 (APACHE\$1ACCESS\$1LOG、NGINX\$1ACCESS\$1LOG、SYSLOG5424)，在常見日誌模式之後僅支援 DATA、GREEDYDATA 或 GREEDYDATA\$1MULTILINE 模式。 | [查看所有支援的 Grok 模式](#Grok-Patterns) | **Grok 模式的結構** 這是支援的 grok 模式結構： ``` %{PATTERN_NAME:FIELD_NAME} ``` + **PATTERN\$1NAME**：指符合特定資料類型的預先定義規則運算式。僅支援預先定義的 [grok 模式](#Grok-Patterns)。不允許建立自訂模式。 + **FIELD\$1NAME**：將名稱指派給擷取的值。 `FIELD_NAME`是選用的，但如果您未指定此值，則會從轉換的日誌事件中捨棄擷取的資料。如果 `FIELD_NAME`使用虛線表示法 （例如 "parent.child")，則會將其視為 JSON 路徑。 + **類型轉換**：不支援明確類型轉換。使用 [TypeConverter 處理器](CloudWatch-Logs-Transformation-Datatype.md#CloudWatch-Logs-Transformation-typeConverter)來轉換 grok 擷取之任何值的資料類型。 若要建立更複雜的相符表達式，您可以結合多個 grok 模式。最多可結合 20 個 grok 模式以符合日誌事件。例如，此模式組合`%{NUMBER:timestamp} [%{NUMBER:db} %{IP:client_ip}:%{NUMBER:client_port}] %{GREEDYDATA:data}`可用來從 Redis 慢速日誌項目擷取欄位，如下所示： `1629860738.123456 [0 127.0.0.1:6379] "SET" "key1" "value1"` ### Grok 範例 #### 範例 1：使用 grok 從非結構化日誌中擷取欄位 範例日誌： ``` 293750 server-01.internal-network.local OK "[Thread-000] token generated" ``` 使用的轉換器： ``` [ { "grok": { "match": "%{NUMBER:version} %{HOSTNAME:hostname} %{NOTSPACE:status} %{QUOTEDSTRING:logMsg}" } } ] ``` 輸出： ``` { "version": "293750", "hostname": "server-01.internal-network.local", "status": "OK", "logMsg": "[Thread-000] token generated" } ``` 範例日誌： ``` 23/Nov/2024:10:25:15 -0900 172.16.0.1 200 ``` 使用的轉換器： ``` [ { "grok": { "match": "%{HTTPDATE:timestamp} %{IPORHOST:clientip} %{NUMBER:response_status}" } } ] ``` 輸出： ``` { "timestamp": "23/Nov/2024:10:25:15 -0900", "clientip": "172.16.0.1", "response_status": "200" } ``` #### 範例 2：使用 grok 搭配 parseJSON 從 JSON 日誌事件擷取欄位 範例日誌： ``` { "timestamp": "2024-11-23T16:03:12Z", "level": "ERROR", "logMsg": "GET /page.html HTTP/1.1" } ``` 使用的轉換器： ``` [ { "parseJSON": {} }, { "grok": { "source": "logMsg", "match": "%{WORD:http_method} %{NOTSPACE:request} HTTP/%{NUMBER:http_version}" } } ] ``` 輸出： ``` { "timestamp": "2024-11-23T16:03:12Z", "level": "ERROR", "logMsg": "GET /page.html HTTP/1.1", "http_method": "GET", "request": "/page.html", "http_version": "1.1" } ``` #### 範例 3：FIELD\$1NAME 中具有虛線註釋的 Grok 模式 範例日誌： ``` 192.168.1.1 GET /index.html?param=value 200 1234 ``` 使用的轉換器： ``` [ { "grok": { "match": "%{IP:client.ip} %{WORD:method} %{URIPATHPARAM:request.uri} %{NUMBER:response.status} %{NUMBER:response.bytes}" } } ] ``` 輸出： ``` { "client": { "ip": "192.168.1.1" }, "method": "GET", "request": { "uri": "/index.html?param=value" }, "response": { "status": "200", "bytes": "1234" } } ``` ### 支援的 grok 模式 下表列出`grok`處理器支援的模式。 **一般 grok 模式** | Grok 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | USERNAME 或 USER | 符合一個或多個字元，可包含小寫字母 (a-z)、大寫字母 (A-Z)、數字 (0-9)、點 (.)、底線 (\$1) 或連字號 (-) | 20 | 輸入： `user123.name-TEST` 模式：`%{USERNAME:name}` 輸出： `{"name": "user123.name-TEST"}` | | INT | 符合選用的加號或減號，後面接著一個或多個數字。 | 20 | 輸入： `-456` 模式：`%{INT:num}` 輸出： `{"num": "-456"}` | | BASE10NUM | 比對整數或浮點數與選用的符號和小數點 | 20 | 輸入： `-0.67` 模式：`%{BASE10NUM:num}` 輸出： `{"num": "-0.67"}` | | BASE16NUM | 將小數和十六進位數字與選用的符號 (\$1 或 -) 和選用的 0x 字首配對 | 20 | 輸入： `+0xA1B2` 模式：`%{BASE16NUM:num}` 輸出： `{"num": "+0xA1B2"}` | | POSINT | 比對沒有前導零的完整正整數，包含一或多個數字 (1-9 後接 0-9) | 20 | 輸入： `123` 模式：`%{POSINT:num}` 輸出： `{"num": "123"}` | | NONNEGINT | 符合任何整數 （包含一或多個數字 0-9)，包括零和開頭為零的數字。 | 20 | 輸入： `007` 模式：`%{NONNEGINT:num}` 輸出： `{"num": "007"}` | | WORD | 比對由一或多個單字字元 (\$1w) 組成的整個單字，包括字母、數字和底線 | 20 | 輸入： `user_123` 模式：`%{WORD:user}` 輸出： `{"user": "user_123"}` | | NOTSPACE | 符合一或多個非空格字元。 | 5 | 輸入： `hello_world123` 模式：`%{NOTSPACE:msg}` 輸出： `{"msg": "hello_world123"}` | | SPACE | 符合零個或多個空格字元。 | 5 | 輸入： `" "` 模式：`%{SPACE:extra}` 輸出： `{"extra": " "}` | | DATA | 符合任何字元 （新行除外） 零次或多次，非貪婪。 | 5 | 輸入： `abc def ghi` 模式：`%{DATA:x} %{DATA:y}` 輸出： `{"x": "abc", "y": "def ghi"}` | | GREEDYDATA | 符合任何字元 （新行除外） 零次或多次，歡迎。 | 5 | 輸入： `abc def ghi` 模式：`%{GREEDYDATA:x} %{GREEDYDATA:y}` 輸出： `{"x": "abc def", "y": "ghi"}` | | GREEDYDATA\$1MULTILINE | 符合任何角色 （包括換行） 零次或多次，歡迎。 | 1 | 輸入: `abc` `def` `ghi` 模式：`%{GREEDYDATA_MULTILINE:data}` 輸出： `{"data": "abc\ndef\nghi"}` | | QUOTEDSTRING | 將引號字串 （單引號或雙引號） 與逸出字元相符。 | 20 | 輸入： `"Hello, world!"` 模式：`%{QUOTEDSTRING:msg}` 輸出： `{"msg": "Hello, world!"}` | | UUID | 符合標準 UUID 格式：8 個十六進位字元，後面接著三個 4 個十六進位字元群組，並以 12 個十六進位字元結尾，全部以連字號分隔。 | 20 | 輸入： `550e8400-e29b-41d4-a716-446655440000` 模式：`%{UUID:id}` 輸出： `{"id": "550e8400-e29b-41d4-a716-446655440000"}` | | URN | 符合 URN （統一資源名稱） 語法。 | 20 | 輸入： `urn:isbn:0451450523` 模式：`%{URN:urn}` 輸出： `{"urn": "urn:isbn:0451450523"}` | **AWS grok 模式** | 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | ARN | 符合 AWS Amazon Resource Name (ARNs)`aws-cn`、擷取分割區 (`aws`、 或 `aws-us-gov`)、服務、區域、帳戶 ID，以及最多 5 個以斜線分隔的階層資源識別符。它將不符合冒號之間缺少資訊的 ARNs。 | 5 | 輸入： `arn:aws:iam:us-east-1:123456789012:user/johndoe` 模式：`%{ARN:arn}` 輸出： `{"arn": "arn:aws:iam:us-east-1:123456789012:user/johndoe"}` | **網路 grok 模式** | Grok 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | CISCOMAC | 符合 4-4-4 十六進位格式的 MAC 地址。 | 20 | 輸入： `0123.4567.89AB` 模式：`%{CISCOMAC:MacAddress}` 輸出： `{"MacAddress": "0123.4567.89AB"}` | | WINDOWSMAC | 將十六進位格式的 MAC 地址與連字號相符 | 20 | 輸入： `01-23-45-67-89-AB` 模式：`%{WINDOWSMAC:MacAddress}` 輸出： `{"MacAddress": "01-23-45-67-89-AB"}` | | COMMONMAC | 比對十六進位格式的 MAC 地址與冒號。 | 20 | 輸入： `01:23:45:67:89:AB` 模式：`%{COMMONMAC:MacAddress}` 輸出： `{"MacAddress": "01:23:45:67:89:AB"}` | | MAC | 符合其中一個 CISCOMAC、WINDOWSMAC 或 COMMONMAC grok 模式 | 20 | 輸入： `01:23:45:67:89:AB` 模式：`%{MAC:m1}` 輸出： `{"m1":"01:23:45:67:89:AB"}` | | IPV6 | 符合 IPv6 地址，包括壓縮表單和 IPv4-mapped IPv6 地址。 | 5 | 輸入： `2001:db8:3333:4444:5555:6666:7777:8888` 模式：`%{IPV6:ip}` 輸出： `{"ip": "2001:db8:3333:4444:5555:6666:7777:8888"}` | | IPV4 | 符合 IPv4 地址。 | 20 | 輸入： `192.168.0.1` 模式：`%{IPV4:ip}` 輸出： `{"ip": "192.168.0.1"}` | | IP | 符合 %\$1IPvIPv6\$1 支援的 IPv6 地址或 %\$1IPv4\$1 支援的 IPv4 地址IPv4 | 5 | 輸入： `192.168.0.1` 模式：`%{IP:ip}` 輸出： `{"ip": "192.168.0.1"}` | | HOSTNAME 或 HOST | 符合網域名稱，包括子網域 | 5 | 輸入： `server-01.internal-network.local` 模式：`%{HOST:host}` 輸出： `{"host": "server-01.internal-network.local"}` | | IPORHOST | 符合主機名稱或 IP 地址 | 5 | 輸入： `2001:db8:3333:4444:5555:6666:7777:8888` 模式：`%{IPORHOST:ip}` 輸出： `{"ip": "2001:db8:3333:4444:5555:6666:7777:8888"}` | | HOSTPORT | 符合 %\$1IPORHOST\$1 模式支援的 IP 地址或主機名稱，後面接著冒號和連接埠號碼，在輸出中擷取連接埠做為「PORT」。 | 5 | 輸入： `192.168.1.1:8080` 模式：`%{HOSTPORT:ip}` 輸出： `{"ip":"192.168.1.1:8080","PORT":"8080"}` | | URIHOST | 符合 %\$1IPORHOST\$1 模式支援的 IP 地址或主機名稱，選擇性地後面接著冒號和連接埠號碼，如果有的話，擷取連接埠為「連接埠」。 | 5 | 輸入： `example.com:443 10.0.0.1` 模式：`%{URIHOST:host} %{URIHOST:ip}` 輸出： `{"host":"example.com:443","port":"443","ip":"10.0.0.1"}` | **路徑grok 模式** | Grok 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | UNIXPATH | 符合 URL 路徑，可能包括查詢參數。 | 20 | 輸入： `/search?q=regex` 模式：`%{UNIXPATH:path}` 輸出： `{"path":"/search?q=regex"}` | | WINPATH | 符合 Windows 檔案路徑。 | 5 | 輸入： `C:\Users\John\Documents\file.txt` 模式：`%{WINPATH:path}` 輸出： `{"path": "C:\\Users\\John\\Documents\\file.txt"}` | | PATH | 符合 URL 或 Windows 檔案路徑 | 5 | 輸入： `/search?q=regex` 模式：`%{PATH:path}` 輸出： `{"path":"/search?q=regex"}` | | TTY | 比對終端機和虛擬終端機的 Unix 裝置路徑。 | 20 | 輸入： `/dev/tty1` 模式：`%{TTY:path}` 輸出： `{"path":"/dev/tty1"}` | | URIPROTO | 符合字母，選擇性後接加號 (＋) 字元和其他字母或加號 (＋) 字元 | 20 | 輸入： `web+transformer` 模式：`%{URIPROTO:protocol}` 輸出： `{"protocol":"web+transformer"}` | | URIPATH | 符合 URI 的路徑元件 | 20 | 輸入： `/category/sub-category/product_name` 模式：`%{URIPATH:path}` 輸出： `{"path":"/category/sub-category/product_name"}` | | URIPARAM | 符合 URL 查詢參數 | 5 | 輸入： `?param1=value1¶m2=value2` 模式：`%{URIPARAM:url}` 輸出： `{"url":"?param1=value1¶m2=value2"}` | | URIPATHPARAM | 選擇性地比對 URI 路徑，後面接著查詢參數 | 5 | 輸入： `/category/sub-category/product?id=12345&color=red` 模式：`%{URIPATHPARAM:path}` 輸出： `{"path":"/category/sub-category/product?id=12345&color=red"}` | | URI | 符合完整的 URI | 5 | 輸入： `https://user:password@example.com/path/to/resource?param1=value1¶m2=value2` 模式：`%{URI:uri}` 輸出： `{"path":"https://user:password@example.com/path/to/resource?param1=value1¶m2=value2"}` | **日期和時間 grok 模式** | Grok 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | MONTH | 將完整或縮寫的英文月份名稱配對為完整單字 | 20 | 輸入： `Jan` 模式：`%{MONTH:month}` 輸出： `{"month":"Jan"}` 輸入： `January` 模式：`%{MONTH:month}` 輸出： `{"month":"January"}` | | MONTHNUM | 比對從 1 到 12 的月份編號，單位數月份的選用前導零。 | 20 | 輸入： `5` 模式：`%{MONTHNUM:month}` 輸出： `{"month":"5"}` 輸入： `05` 模式：`%{MONTHNUM:month}` 輸出： `{"month":"05"}` | | MONTHNUM2 | 符合從 01 到 12 的兩位數月編號。 | 20 | 輸入： `05` 模式：`%{MONTHNUM2:month}` 輸出： `{"month":"05"}` | | 週一 | 將月份中的某天從 1 比對到 31，加上選用的前導零。 | 20 | 輸入： `31` 模式：`%{MONTHDAY:monthDay}` 輸出： `{"monthDay":"31"}` | | YEAR | 符合兩或四位數的年份 | 20 | 輸入： `2024` 模式：`%{YEAR:year}` 輸出： `{"year":"2024"}` 輸入： `24` 模式：`%{YEAR:year}` 輸出： `{"year":"24"}` | | DAY | 符合完整或縮寫的日名稱。 | 20 | 輸入： `Tuesday` 模式：`%{DAY:day}` 輸出： `{"day":"Tuesday"}` | | HOUR | 將 24 小時格式的小時與選用的前導零 (0)0-23 配對。 | 20 | 輸入： `22` 模式：`%{HOUR:hour}` 輸出： `{"hour":"22"}` | | MINUTE | 符合分鐘數 (00-59)。 | 20 | 輸入： `59` 模式：`%{MINUTE:min}` 輸出： `{"min":"59"}` | | SECOND | 比對代表秒數 (0)0-60 的數字，選擇性地後接小數點或冒號，以及小數分鐘的一個或多個數字 | 20 | 輸入： `3` 模式：`%{SECOND:second}` 輸出： `{"second":"3"}` 輸入： `30.5` 模式：`%{SECOND:minSec}` 輸出： `{"minSec":"30.5"}` 輸入： `30:5` 模式：`%{SECOND:minSec}` 輸出： `{"minSec":"30:5"}` | | TIME | 以小時、分鐘和秒的格式 (H)H：mm：(s) 比對時間格式。秒包括閏秒 (0)0-60。 | 20 | 輸入： `09:45:32` 模式：`%{TIME:time}` 輸出： `{"time":"09:45:32"}` | | DATE\$1US | 符合 (M)M/(d)d/(yy)y 或 (M)M-(d)d-(yy)yy 格式的日期。 | 20 | 輸入： `11/23/2024` 模式：`%{DATE_US:date}` 輸出： `{"date":"11/23/2024"}` 輸入： `1-01-24` 模式：`%{DATE_US:date}` 輸出： `{"date":"1-01-24"}` | | DATE\$1EU | 符合 (d)d/(M)M/(yy)yy、(d)d-(M)M-(yy)yy 或 (d)d.(M)M.(yy)yy。 | 20 | 輸入： `23/11/2024` 模式：`%{DATE_EU:date}` 輸出： `{"date":"23/11/2024"}` 輸入： `1.01.24` 模式：`%{DATE_EU:date}` 輸出： `{"date":"1.01.24"}` | | ISO8601\$1TIMEZONE | 將 UTC 位移 'Z' 或時區位移與選用冒號的格式 【\$1-】(H)H(：)mm 比對。 | 20 | 輸入： `+05:30` 模式：`%{ISO8601_TIMEZONE:tz}` 輸出： `{"tz":"+05:30"}` 輸入： `-530` 模式：`%{ISO8601_TIMEZONE:tz}` 輸出： `{"tz":"-530"}` 輸入： `Z` 模式：`%{ISO8601_TIMEZONE:tz}` 輸出： `{"tz":"Z"}` | | ISO8601\$1SECOND | 比對代表秒數 (0)0-60 的數字，選擇性地後接小數點或冒號，以及小數秒的一個或多個數字 | 20 | 輸入： `60` 模式：`%{ISO8601_SECOND:second}` 輸出： `{"second":"60"}` | | TIMESTAMP\$1ISO8601 | 比對 ISO8601 日期時間格式 (yy)yy-(M)M-(d)dT(H)H：mm：((s)s)(Z\$1【\$1-】(H)H：mm) 與選用的秒和時區。 | 20 | 輸入： `2023-05-15T14:30:00+05:30` 模式：`%{TIMESTAMP_ISO8601:timestamp}` 輸出： `{"timestamp":"2023-05-15T14:30:00+05:30"}` 輸入： `23-5-1T1:25+5:30` 模式：`%{TIMESTAMP_ISO8601:timestamp}` 輸出： `{"timestamp":"23-5-1T1:25+5:30"}` 輸入： `23-5-1T1:25Z` 模式：`%{TIMESTAMP_ISO8601:timestamp}` 輸出： `{"timestamp":"23-5-1T1:25Z"}` | | DATE | 使用 %\$1DATE\$1US\$1 比對美國格式的日期，或使用 %\$1DATE\$1EU\$1 比對歐洲格式的日期 | 20 | 輸入： `11/29/2024` 模式：`%{DATE:date}` 輸出： `{"date":"11/29/2024"}` 輸入： `29.11.2024` 模式：`%{DATE:date}` 輸出： `{"date":"29.11.2024"}` | | DATESTAMP | 符合 %\$1DATE\$1 後接 %\$1TIME\$1 模式，以空格或連字號分隔。 | 20 | 輸入： `29-11-2024 14:30:00` 模式：`%{DATESTAMP:dateTime}` 輸出： `{"dateTime":"29-11-2024 14:30:00"}` | | TZ | 符合常見時區縮寫 (PST、PDT、MST、MDT、CST CDT、EST、EDT、UTC)。 | 20 | 輸入： `PDT` 模式：`%{TZ:tz}` 輸出： `{"tz":"PDT"}` | | DATESTAMP\$1RFC822 | 符合格式的日期和時間：Day MonthName (D)D (YY)YY (H)H：mm：(s)s 時區 | 20 | 輸入： `Monday Jan 5 23 1:30:00 CDT` 模式：`%{DATESTAMP_RFC822:dateTime}` 輸出： `{"dateTime":"Monday Jan 5 23 1:30:00 CDT"}` 輸入： `Mon January 15 2023 14:30:00 PST` 模式：`%{DATESTAMP_RFC822:dateTime}` 輸出： `{"dateTime":"Mon January 15 2023 14:30:00 PST"}` | | DATESTAMP\$1RFC2822 | 符合 RFC2822 日期時間格式：Day， (d)d MonthName (yy)yy (H)H：mm：(s)s Z\$1【\$1-】(H)H：mm | 20 | 輸入： `Mon, 15 May 2023 14:30:00 +0530` 模式：`%{DATESTAMP_RFC2822:dateTime}` 輸出： `{"dateTime":"Mon, 15 May 2023 14:30:00 +0530"}` 輸入： `Monday, 15 Jan 23 14:30:00 Z` 模式：`%{DATESTAMP_RFC2822:dateTime}` 輸出： `{"dateTime":"Monday, 15 Jan 23 14:30:00 Z"}` | | DATESTAMP\$1OTHER | 符合格式的日期和時間：Day MonthName (d)d (H)H：mm：(s)s Timezone (yy)yy | 20 | 輸入： `Mon May 15 14:30:00 PST 2023` 模式：`%{DATESTAMP_OTHER:dateTime}` 輸出： `{"dateTime":"Mon May 15 14:30:00 PST 2023"}` | | DATESTAMP\$1EVENTLOG | 符合不含分隔符號的精簡日期時間格式：(yy)yyMM(d)d(H)Hmm(s)s | 20 | 輸入： `20230515143000` 模式：`%{DATESTAMP_EVENTLOG:dateTime}` 輸出： `{"dateTime":"20230515143000"}` | **日誌 grok 模式** | Grok 模式 | Description | 模式上限 | 範例 | | --- | --- | --- | --- | | LOGLEVEL | 符合不同大寫和縮寫中的標準日誌層級，包括下列項目：Alert/ALERT、Trace/TRACE、Debug/DEBUG、Notice/NOTICEInfo/INFO、Warn/Warning/WARN/WARNING、Err/Error/ERR/ERROR、Crit/Critical/CRIT/CRITICAL、Fatal/FATAL、、 Severe/SEVERE Emerg/Emergency/EMERG/EMERGENCY | 20 | 輸入： `INFO` 模式：`%{LOGLEVEL:logLevel}` 輸出： `{"logLevel":"INFO"}` | | HTTPDATE | 符合日誌檔案中常用的日期和時間格式。格式：(d)d/MonthName/(yy)yy：(H)H：mm：(s)s 時區 MonthName： 符合完整或縮寫的英文月份名稱 （範例：「Jan」或「January」) 時區： 符合 %\$1INT\$1 grok 模式 | 20 | 輸入： `23/Nov/2024:14:30:00 +0640` 模式：`%{HTTPDATE:date}` 輸出： `{"date":"23/Nov/2024:14:30:00 +0640"}` | | SYSLOGTIMESTAMP | 與 MonthName (d)d (H)H：mm：(s)s MonthName 相符的日期格式：符合完整或縮寫的英文月份名稱 （範例：「1 月」或「1 月」) | 20 | 輸入： `Nov 29 14:30:00` 模式：`%{SYSLOGTIMESTAMP:dateTime}` 輸出： `{"dateTime":"Nov 29 14:30:00"}` | | PROG | 符合由字母、數字、點、底線、正斜線、百分比符號和連字號字元組成的程式名稱。 | 20 | 輸入： `user.profile/settings-page` 模式：`%{PROG:program}` 輸出： `{"program":"user.profile/settings-page"}` | | SYSLOGPROG | 選擇性地比對 PROG grok 模式，後面接著方括號中的程序 ID。 | 20 | 輸入： `user.profile/settings-page[1234]` 模式：`%{SYSLOGPROG:programWithId}` 輸出： `{"programWithId":"user.profile/settings-page[1234]","program":"user.profile/settings-page","pid":"1234"}` | | SYSLOGHOST | 符合 %\$1HOST\$1 或 %\$1IP\$1 模式 | 5 | 輸入： `2001:db8:3333:4444:5555:6666:7777:8888` 模式：`%{SYSLOGHOST:ip}` 輸出： `{"ip": "2001:db8:3333:4444:5555:6666:7777:8888"}` | | SYSLOGFACILITY | 符合十進位格式的 syslog 優先順序。該值應該用角括號括住 (<>)。 | 20 | 輸入： `<13.6>` 模式：`%{SYSLOGFACILITY:syslog}` 輸出： `{"syslog":"<13.6>","facility":"13","priority":"6"}` | **常見日誌 grok 模式** 您可以使用預先定義的自訂 grok 模式來比對 Apache、NGINX 和 Syslog Protocol (RFC 5424) 日誌格式。當您使用這些特定模式時，它們必須是相符組態中的第一個模式，而且前面沒有其他模式。此外，您只能使用一個 **DATA** 來追蹤它們。**GREEDYDATA** 或 **GREEDYDATA\$1MULTILINE** 模式。 | Grok 模式 | Description | 模式上限 | | --- | --- | --- | | APACHE\$1ACCESS\$1LOG | 符合 Apache 存取日誌 | 1 | | NGINX\$1ACCESS\$1LOG | 符合 NGINX 存取日誌 | 1 | | SYSLOG5424 | 符合 Syslog 通訊協定 (RFC 5424) 日誌 | 1 | 以下顯示使用這些常見日誌格式模式的有效和無效範例。 ``` "%{NGINX_ACCESS_LOG} %{DATA}" // Valid "%{SYSLOG5424}%{DATA:logMsg}" // Valid "%{APACHE_ACCESS_LOG} %{GREEDYDATA:logMsg}" // Valid "%{APACHE_ACCESS_LOG} %{SYSLOG5424}" // Invalid (multiple common log patterns used) "%{NGINX_ACCESS_LOG} %{NUMBER:num}" // Invalid (Only GREEDYDATA and DATA patterns are supported with common log patterns) "%{GREEDYDATA:logMsg} %{SYSLOG5424}" // Invalid (GREEDYDATA and DATA patterns are supported only after common log patterns) ``` #### 常見日誌格式範例 ##### Apache 日誌範例 範例日誌： ``` 127.0.0.1 - - [03/Aug/2023:12:34:56 +0000] "GET /page.html HTTP/1.1" 200 1234 ``` 轉換器： ``` [ { "grok": { "match": "%{APACHE_ACCESS_LOG}" } } ] ``` 輸出： ``` { "request": "/page.html", "http_method": "GET", "status_code": 200, "http_version": "1.1", "response_size": 1234, "remote_host": "127.0.0.1", "timestamp": "2023-08-03T12:34:56Z" } ``` ##### NGINX 日誌範例 範例日誌： ``` 192.168.1.100 - Foo [03/Aug/2023:12:34:56 +0000] "GET /account/login.html HTTP/1.1" 200 42 "https://www.amazon.com/" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36" ``` 轉換器： ``` [ { "grok": { "match": "%{NGINX_ACCESS_LOG}" } } ] ``` 輸出： ``` { "request": "/account/login.html", "referrer": "https://www.amazon.com/", "agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36", "http_method": "GET", "status_code": 200, "auth_user": "Foo", "http_version": "1.1", "response_size": 42, "remote_host": "192.168.1.100", "timestamp": "2023-08-03T12:34:56Z" } ``` ##### Syslog 通訊協定 (RFC 5424) 日誌範例 範例日誌： ``` <165>1 2003-10-11T22:14:15.003Z mymachine.example.com evntslog - ID47 [exampleSDID@32473 iut="3" eventSource= "Application" eventID="1011"][examplePriority@32473 class="high"] ``` 轉換器： ``` [ { "grok": { "match": "%{SYSLOG5424}" } } ] ``` 輸出： ``` { "pri": 165, "version": 1, "timestamp": "2003-10-11T22:14:15.003Z", "hostname": "mymachine.example.com", "app": "evntslog", "msg_id": "ID47", "structured_data": "exampleSDID@32473 iut=\"3\" eventSource= \"Application\" eventID=\"1011\"", "message": "[examplePriority@32473 class=\"high\"]" } ``` ## csv **csv** 處理器會將逗號分隔值 (CSV) 從日誌事件剖析為資料欄。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | source | 要剖析之日誌事件中 欄位的路徑 | 否 | `@message` | 長度上限：128 巢狀金鑰深度上限：3 | | 分隔符號 | 用來分隔原始逗號分隔值日誌事件中每個資料欄的字元 | 否 | `,` | 長度上限：1，除非值為 `\t`或 `\s` | | quoteCharacter | 用作單一資料欄文字限定詞的字元 | 否 | `"` | 長度上限：1 | | 欄 | 要用於轉換日誌事件中資料欄的名稱清單。 | 否 | `[column_1, column_2 ...]` | CSV 資料欄上限：100 長度上限：128 巢狀金鑰深度上限：3 | | 目的地 | 要在 下放置轉換金鑰值對的父欄位 | 否 | `Root node` | 長度上限：128 巢狀金鑰深度上限：3 | `delimiter` 將 設定為 `\t`會將標籤字元上的每個資料欄分開，並將單一空格字元上的每個資料欄`\t`分開。 **範例** 假設部分擷取的日誌事件如下所示： ``` 'Akua Mansa':28:'New York: USA' ``` 假設我們僅使用 **csv** 處理器： ``` [ { "csv": { "delimiter": ":", "quoteCharacter": "'" } } ] ``` 轉換的日誌事件如下。 ``` { "column_1": "Akua Mansa", "column_2": "28", "column_3": "New York: USA" } ``` **範例 2** 假設擷取的日誌事件如下所示： ``` { "timestamp": "2024-11-23T16:03:12Z", "type": "user_data", "logMsg": "'Akua Mansa':28:'New York: USA'" } ``` 假設我們將事件剖析為 JSON，它們會使用 **csv** 處理器剖析 JSON 欄位，並指定資料欄名稱和目的地： ``` [ { "parseJSON": {} }, { "csv": { "source": "logMsg", "delimiter": ":", "quoteCharacter": "'", "columns":["name","age","location"], "destination": "msg" } } ] ``` 轉換的日誌事件如下。 ``` { "timestamp": "2024-11-23T16:03:12Z", "logMsg": "'Akua Mansa':28:'New York: USA'", "type": "user_data", "msg": { "name": "Akua Mansa", "age": "28", "location": "New York: USA" } } ``` ## parseKeyValue 使用 **parseKeyValue** 處理器將指定的欄位剖析為鍵/值對。您可以使用下列選項自訂處理器來剖析欄位資訊。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | source | 要剖析之日誌事件中 欄位的路徑 | 否 | `@message` | 長度上限：128 巢狀金鑰深度上限：3 | | 目的地 | 要將擷取的鍵/值對放入其中的目的地欄位 | 否 | | 長度上限：128 | | fieldDelimiter | 在原始日誌事件的鍵值對之間使用的欄位分隔符號字串 | 否 | `&` | 長度上限：128 | | keyValueDelimiter | 在轉換日誌事件中每對索引鍵和值之間使用的分隔符號字串 | 否 | `=` | 長度上限：128 | | nonMatchValue | 當鍵/值對未成功分割時，要插入結果中值欄位的值。 | 否 | | 長度上限：128 | | keyPrefix | 如果您想要新增字首所有轉換的金鑰，請在此處指定它。 | 否 | | 長度上限：128 | | overwriteIfExists | 如果目的地金鑰已存在，是否覆寫該值 | 否 | `false` | | **範例** 採用下列範例日誌事件： ``` key1:value1!key2:value2!key3:value3!key4 ``` 假設我們使用下列處理器組態： ``` [ { "parseKeyValue": { "destination": "new_key", "fieldDelimiter": "!", "keyValueDelimiter": ":", "nonMatchValue": "defaultValue", "keyPrefix": "parsed_" } } ] ``` 轉換的日誌事件如下。 ``` { "new_key": { "parsed_key1": "value1", "parsed_key2": "value2", "parsed_key3": "value3", "parsed_key4": "defaultValue" } } ``` # 適用於 AWS 付費日誌的內建處理器 本節包含有關內建處理器的資訊，您可以將這些處理器與提供日誌 AWS 的服務搭配使用。 **Contents** + [parseWAF](#CloudWatch-Logs-Transformation-parseWAF) + [parsePostgres](#CloudWatch-Logs-Transformation-parsePostGres) + [parseCloudfront](#CloudWatch-Logs-Transformation-parseCloudFront) + [parseRoute53](#CloudWatch-Logs-Transformation-parseRoute53) + [parseVPC](#CloudWatch-Logs-Transformation-parseVPC) + [parseToOCSF](CloudWatch-Logs-Transformation-parseToOCSF.md) ## parseWAF 使用此處理器來剖析已 AWS WAF 結束的日誌，它會採用 的內容，`httpRequest.headers`並從每個標頭名稱建立具有對應值的 JSON 金鑰。它也會對 執行相同的操作`labels`。這些轉換可讓您更輕鬆地查詢 AWS WAF 日誌。如需 AWS WAF 日誌格式的詳細資訊，請參閱 [ Web ACL 流量的日誌範例](https://docs.aws.amazon.com/waf/latest/developerguide/logging-examples.html)。 此處理器僅接受 `@message`做為輸入。 **重要** 如果您使用此處理器，它必須是轉換器中的第一個處理器。 **範例** 採用下列範例日誌事件： ``` { "timestamp": 1576280412771, "formatVersion": 1, "webaclId": "arn:aws:wafv2:ap-southeast-2:111122223333:regional/webacl/STMTest/1EXAMPLE-2ARN-3ARN-4ARN-123456EXAMPLE", "terminatingRuleId": "STMTest_SQLi_XSS", "terminatingRuleType": "REGULAR", "action": "BLOCK", "terminatingRuleMatchDetails": [ { "conditionType": "SQL_INJECTION", "sensitivityLevel": "HIGH", "location": "HEADER", "matchedData": ["10", "AND", "1"] } ], "httpSourceName": "-", "httpSourceId": "-", "ruleGroupList": [], "rateBasedRuleList": [], "nonTerminatingMatchingRules": [], "httpRequest": { "clientIp": "1.1.1.1", "country": "AU", "headers": [ { "name": "Host", "value": "localhost:1989" }, { "name": "User-Agent", "value": "curl/7.61.1" }, { "name": "Accept", "value": "*/*" }, { "name": "x-stm-test", "value": "10 AND 1=1" } ], "uri": "/myUri", "args": "", "httpVersion": "HTTP/1.1", "httpMethod": "GET", "requestId": "rid" }, "labels": [{ "name": "value" }] } ``` 處理器組態如下： ``` [ { "parseWAF": {} } ] ``` 轉換的日誌事件如下。 ``` { "httpRequest": { "headers": { "Host": "localhost:1989", "User-Agent": "curl/7.61.1", "Accept": "*/*", "x-stm-test": "10 AND 1=1" }, "clientIp": "1.1.1.1", "country": "AU", "uri": "/myUri", "args": "", "httpVersion": "HTTP/1.1", "httpMethod": "GET", "requestId": "rid" }, "labels": { "name": "value" }, "timestamp": 1576280412771, "formatVersion": 1, "webaclId": "arn:aws:wafv2:ap-southeast-2:111122223333:regional/webacl/STMTest/1EXAMPLE-2ARN-3ARN-4ARN-123456EXAMPLE", "terminatingRuleId": "STMTest_SQLi_XSS", "terminatingRuleType": "REGULAR", "action": "BLOCK", "terminatingRuleMatchDetails": [ { "conditionType": "SQL_INJECTION", "sensitivityLevel": "HIGH", "location": "HEADER", "matchedData": ["10", "AND", "1"] } ], "httpSourceName": "-", "httpSourceId": "-", "ruleGroupList": [], "rateBasedRuleList": [], "nonTerminatingMatchingRules": [] } ``` ## parsePostgres 使用此處理器來剖析 Amazon RDS for PostgreSQL 付費日誌、擷取欄位，並將它們轉換為 JSON 格式。如需 RDS for PostgreSQL 日誌格式的詳細資訊，請參閱 [ RDS for PostgreSQL 資料庫日誌檔案](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_LogAccess.Concepts.PostgreSQL.html#USER_LogAccess.Concepts.PostgreSQL.Log_Format.log-line-prefix)。 此處理器僅接受 `@message`做為輸入。 **重要** 如果您使用此處理器，它必須是轉換器中的第一個處理器。 **範例** 採用下列範例日誌事件： ``` 2019-03-10 03:54:59 UTC:10.0.0.123(52834):postgres@logtestdb:[20175]:ERROR: column "wrong_column_name" does not exist at character 8 ``` 處理器組態如下： ``` [ { "parsePostgres": {} } ] ``` 轉換的日誌事件如下。 ``` { "logTime": "2019-03-10 03:54:59 UTC", "srcIp": "10.0.0.123(52834)", "userName": "postgres", "dbName": "logtestdb", "processId": "20175", "logLevel": "ERROR" } ``` ## parseCloudfront 使用此處理器來剖析 Amazon CloudFront 付費日誌、擷取欄位，並將它們轉換為 JSON 格式。編碼的欄位值會解碼。整數和雙數的值會被視為這樣。如需 Amazon CloudFront 日誌格式的詳細資訊，請參閱[設定和使用標準日誌 （存取日誌）](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html)。 此處理器僅接受 `@message`做為輸入。 **重要** 如果您使用此處理器，它必須是轉換器中的第一個處理器。 **範例** 採用下列範例日誌事件： ``` 2019-12-04 21:02:31 LAX1 392 192.0.2.24 GET d111111abcdef8.cloudfront.net /index.html 200 - Mozilla/5.0%20(Windows%20NT%2010.0;%20Win64;%20x64)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/78.0.3904.108%20Safari/537.36 - - Hit SOX4xwn4XV6Q4rgb7XiVGOHms_BGlTAC4KyHmureZmBNrjGdRLiNIQ== d111111abcdef8.cloudfront.net https 23 0.001 - TLSv1.2 ECDHE-RSA-AES128-GCM-SHA256 Hit HTTP/2.0 - - 11040 0.001 Hit text/html 78 - - ``` 處理器組態如下： ``` [ { "parseCloudfront": {} } ] ``` 轉換的日誌事件如下。 ``` { "date": "2019-12-04", "time": "21:02:31", "x-edge-location": "LAX1", "sc-bytes": 392, "c-ip": "192.0.2.24", "cs-method": "GET", "cs(Host)": "d111111abcdef8.cloudfront.net", "cs-uri-stem": "/index.html", "sc-status": 200, "cs(Referer)": "-", "cs(User-Agent)": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.108 Safari/537.36", "cs-uri-query": "-", "cs(Cookie)": "-", "x-edge-result-type": "Hit", "x-edge-request-id": "SOX4xwn4XV6Q4rgb7XiVGOHms_BGlTAC4KyHmureZmBNrjGdRLiNIQ==", "x-host-header": "d111111abcdef8.cloudfront.net", "cs-protocol": "https", "cs-bytes": 23, "time-taken": 0.001, "x-forwarded-for": "-", "ssl-protocol": "TLSv1.2", "ssl-cipher": "ECDHE-RSA-AES128-GCM-SHA256", "x-edge-response-result-type": "Hit", "cs-protocol-version": "HTTP/2.0", "fle-status": "-", "fle-encrypted-fields": "-", "c-port": 11040, "time-to-first-byte": 0.001, "x-edge-detailed-result-type": "Hit", "sc-content-type": "text/html", "sc-content-len": 78, "sc-range-start": "-", "sc-range-end": "-" } ``` ## parseRoute53 使用此處理器來剖析 Amazon Route 53 Public Data Plane 付費日誌、擷取欄位，並將它們轉換為 JSON 格式。編碼的欄位值會解碼。此處理器不支援 Amazon Route 53 Resolver 日誌。 此處理器僅接受 `@message`做為輸入。 **重要** 如果您使用此處理器，它必須是轉換器中的第一個處理器。 **範例** 採用下列範例日誌事件： ``` 1.0 2017-12-13T08:15:50.235Z Z123412341234 example.com AAAA NOERROR TCP IAD12 192.0.2.0 198.51.100.0/24 ``` 處理器組態如下： ``` [ { "parseRoute53": {} } ] ``` 轉換的日誌事件如下。 ``` { "version": 1.0, "queryTimestamp": "2017-12-13T08:15:50.235Z", "hostZoneId": "Z123412341234", "queryName": "example.com", "queryType": "AAAA", "responseCode": "NOERROR", "protocol": "TCP", "edgeLocation": "IAD12", "resolverIp": "192.0.2.0", "ednsClientSubnet": "198.51.100.0/24" } ``` ## parseVPC 使用此處理器剖析 Amazon VPC 提供的日誌、擷取欄位，並將它們轉換為 JSON 格式。編碼的欄位值會解碼。 此處理器僅接受 `@message`做為輸入。 **重要** 如果您使用此處理器，它必須是轉換器中的第一個處理器。 **範例** 採用下列範例日誌事件： ``` 2 123456789010 eni-abc123de 192.0.2.0 192.0.2.24 20641 22 6 20 4249 1418530010 1418530070 ACCEPT OK ``` 處理器組態如下： ``` [ { "parseVPC": {} } ] ``` 轉換的日誌事件如下。 ``` { "version": 2, "accountId": "123456789010", "interfaceId": "eni-abc123de", "srcAddr": "192.0.2.0", "dstAddr": "192.0.2.24", "srcPort": 20641, "dstPort": 22, "protocol": 6, "packets": 20, "bytes": 4249, "start": 1418530010, "end": 1418530070, "action": "ACCEPT", "logStatus": "OK" } ``` # parseToOCSF `parseToOCSF` 處理器會將日誌轉換為開放網路安全結構描述架構 (OCSF) 事件。OCSF 是一項開放標準，提供常見的安全資料結構描述，可在不同的安全工具和平台上提供更好的互通性和分析。 此處理器特別適用於您需要將各種 AWS 服務的日誌格式標準化為一致結構描述以進行下游分析的安全分析工作流程。 **參數** `eventSource` (必要) 指定產生要轉換之日誌事件 AWS 的服務或程序。有效的值如下： + `CloudTrail` - CloudTrail 日誌 + `Route53Resolver` - Route 53 Resolver 日誌 + `VPCFlow` - Amazon VPC 流程日誌 + `EKSAudit` - Amazon EKS 稽核日誌 + `AWSWAF` - AWS WAF logs `ocsfVersion` (必要) 指定要用於轉換日誌事件的 OCSF 結構描述版本。目前支援的版本： `V1.1, V1.5` `mappingVersion` (選用) 指定 OCSF 轉換映射版本。控制將日誌轉換為 OCSF 格式時套用哪些轉換邏輯。如果未指定， 會在政策建立時使用最新的可用版本。發佈新的映射版本時，現有的政策不會自動升級。目前最新版本：`v1.5.0`。 **注意：**當 `ocsfVersion`為 時，不支援 `V1.1`。 `source` (選用) 您要剖析之日誌事件中 欄位的路徑。如果省略，則會剖析整個日誌訊息。 **範例** 下列範例示範如何使用 `parseToOCSF`將 VPC 流程日誌轉換為 OCSF 格式： ``` { "parseToOCSF": { "eventSource": "VPCFlow", "ocsfVersion": "V1.1" } } ``` 下列範例示範如何指定特定映射版本，以實現一致的轉換行為： ``` { "parseToOCSF": { "eventSource": "CloudTrail", "ocsfVersion": "V1.5", "mappingVersion": "v1.5.0" } } ``` # 字串變動處理器 本節包含您可以與日誌事件轉換器搭配使用的字串變動處理器相關資訊。 **Contents** + [lowerCaseString](#CloudWatch-Logs-Transformation-lowerCaseString) + [upperCaseString](#CloudWatch-Logs-Transformation-upperCaseString) + [splitString](#CloudWatch-Logs-Transformation-splitString) + [substituteString](#CloudWatch-Logs-Transformation-substituteString) + [trimString](#CloudWatch-Logs-Transformation-trimString) ## lowerCaseString `lowerCaseString` 處理器會將字串轉換為小寫版本。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | withKeys | 要轉換為小寫的索引鍵清單 | 是 | | 項目上限：10 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "INNER_VALUE" } } ``` 轉換器組態是這樣，使用 `lowerCaseString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "lowerCaseString": { "withKeys":["outer_key.inner_key"] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": "inner_value" } } ``` ## upperCaseString `upperCaseString` 處理器會將字串轉換為其大寫版本。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | withKeys | 要轉換為大寫的金鑰清單 | 是 | | 項目上限：10 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是這樣，使用 `upperCaseString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "upperCaseString": { "withKeys":["outer_key.inner_key"] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": "INNER_VALUE" } } ``` ## splitString `splitString` 處理器是一種字串變動處理器，使用分隔字元將欄位分割為陣列。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都必須包含 source和 delimiter 欄位。 | 是 | | 項目上限：10 | | source | 要分割之欄位值的索引鍵 | 是 | | 長度上限：128 | | 分隔符號 | 要在 上分割欄位值的分隔符號字串 | 是 | | 長度上限：128 | **範例 1** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是如此，使用 `splitString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "splitString": { "entries": [ { "source": "outer_key.inner_key", "delimiter": "_" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": [ "inner", "value" ] } } ``` **範例 2** 要在 上分割字串的分隔符號長度可以是多個字元。 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "item1, item2, item3" } } ``` 轉換器組態如下所示： ``` [ { "parseJSON": {} }, { "splitString": { "entries": [ { "source": "outer_key.inner_key", "delimiter": ", " } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": [ "item1", "item2", "item3" ] } } ``` ## substituteString `substituteString` 處理器是一種字串變動處理器，會將索引鍵的值與規則表達式比對，並以取代字串取代所有比對。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目必須包含 source、 from和 to 欄位。 | 是 | | 項目上限：10 | | source | 要修改的欄位索引鍵 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | from | 要取代的規則表達式字串。使用雙引號時必須使用 \$1\$1 逸出 【 和 】 等特殊規則運算式字元，使用單引號時或從 設定時必須使用 \$1 逸出 AWS 管理主控台。如需詳細資訊，請參閱 Oracle 網站上的[類別模式](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html)。 您可以在 中包裝模式`(...)`，以建立編號的擷取群組，並建立可在 `to` 欄位中參考的`(?P...)`具名擷取群組。 | 是 | | 長度上限：128 | | 至 | 對於擷取群組的每個 from Backreference 配對，可以使用要取代的字串。將 \$1n 格式用於編號群組，例如 \$11，並將 \$1\$1group\$1name\$1用於具名群組，例如 \$1\$1my\$1group\$1。> | 是 | | 長度上限：128 最大反引數數：10 重複的反向參考數目上限：2 | **範例 1** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key1": "[]", "inner_key2": "123-345-567", "inner_key3": "A cat takes a catnap." } } ``` 轉換器組態是如此，使用 `substituteString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "substituteString": { "entries": [ { "source": "outer_key.inner_key1", "from": "\\[\\]", "to": "value1" }, { "source": "outer_key.inner_key2", "from": "[0-9]{3}-[0-9]{3}-[0-9]{3}", "to": "xxx-xxx-xxx" }, { "source": "outer_key.inner_key3", "from": "cat", "to": "dog" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key1": "value1", "inner_key2": "xxx-xxx-xxx", "inner_key3": "A dog takes a dognap." } } ``` **範例 2** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key1": "Tom, Dick, and Harry", "inner_key2": "arn:aws:sts::123456789012:assumed-role/MyImportantRole/MySession" } } ``` 轉換器組態是如此，使用 `substituteString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "substituteString": { "entries": [ { "source": "outer_key.inner_key1", "from": "(\w+), (\w+), and (\w+)", "to": "$1 and $3" }, { "source": "outer_key.inner_key2", "from": "^arn:aws:sts::(?P\\d{12}):assumed-role/(?P[\\w+=,.@-]+)/(?P[\\w+=,.@-]+)$", "to": "${account_id}:${role_name}:${role_session_name}" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key1": "Tom and Harry", "inner_key2": "123456789012:MyImportantRole:MySession" } } ``` ## trimString `trimString` 處理器會從金鑰的開頭和結尾移除空格。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | withKeys | 要修剪的金鑰清單 | 是 | | 項目上限：10 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": " inner_value " } } ``` 轉換器組態是如此，使用 `trimString`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "trimString": { "withKeys":["outer_key.inner_key"] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": "inner_value" } } ``` # JSON 變動處理器 本節包含您可以與日誌事件轉換器搭配使用的 JSON 變動處理器相關資訊。 **Contents** + [addKeys](#CloudWatch-Logs-Transformation-addKeys) + [deleteKeys](#CloudWatch-Logs-Transformation-deleteKeys) + [moveKeys](#CloudWatch-Logs-Transformation-moveKeys) + [renameKeys](#CloudWatch-Logs-Transformation-renameKeys) + [copyValue](#CloudWatch-Logs-Transformation-copyValue) + [listToMap](#CloudWatch-Logs-Transformation-listToMap) ## addKeys 使用`addKeys`處理器將新的鍵/值對新增至日誌事件。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都可以包含 key、 value和 overwriteIfExists 欄位。 | 是 | | 項目上限：5 | | 金鑰 | 要新增之新項目的索引鍵 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | value | 要新增的新項目值 | 是 | | 長度上限：256 | | overwriteIfExists | 如果您將此設定為 true，則如果事件中key已存在，則會覆寫現有的值。預設值為 false。 | 否 | false | 沒有限制 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是這樣，使用 `addKeys`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "addKeys": { "entries": [ { "key": "outer_key.new_key", "value": "new_value" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": "inner_value", "new_key": "new_value" } } ``` ## deleteKeys 使用`deleteKeys`處理器從日誌事件中刪除欄位。這些欄位可以包含鍵/值對。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | withKeys | 要刪除的金鑰清單。 | 是 | 沒有限制 | 項目上限：5 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是這樣，使用 `deleteKeys`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "deleteKeys": { "withKeys":["outer_key.inner_key"] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": {} } ``` ## moveKeys 使用`moveKeys`處理器將金鑰從一個欄位移至另一個欄位。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都可以包含 source、 target和 overwriteIfExists 欄位。 | 是 | | 項目上限：5 | | source | 要移動的金鑰 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | 目標 | 要移至的金鑰 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | overwriteIfExists | 如果您將此設定為 true，則如果事件中key已存在，則會覆寫現有的值。預設值為 false。 | 否 | false | 沒有限制 | **範例** 採用下列範例日誌事件： ``` { "outer_key1": { "inner_key1": "inner_value1" }, "outer_key2": { "inner_key2": "inner_value2" } } ``` 轉換器組態是這樣，使用 `moveKeys`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "moveKeys": { "entries": [ { "source": "outer_key1.inner_key1", "target": "outer_key2" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key1": {}, "outer_key2": { "inner_key2": "inner_value2", "inner_key1": "inner_value1" } } ``` ## renameKeys 使用`renameKeys`處理器重新命名日誌事件中的金鑰。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都可以包含 key、 target和 overwriteIfExists 欄位。 | 是 | 沒有限制 | 項目上限：5 | | 金鑰 | 要重新命名的金鑰 | 是 | 沒有限制 | 長度上限：128 | | 目標 | 新的金鑰名稱 | 是 | 沒有限制 | 長度上限：128 巢狀金鑰深度上限：3 | | overwriteIfExists | 如果您將此設定為 true，則如果事件中key已存在，則會覆寫現有的值。預設值為 false。 | 否 | false | 沒有限制 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是這樣，使用 `renameKeys`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "renameKeys": { "entries": [ { "key": "outer_key", "target": "new_key" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "new_key": { "inner_key": "inner_value" } } ``` ## copyValue 使用`copyValue`處理器在日誌事件中複製值。您也可以使用此處理器，透過將下列中繼資料金鑰的值複製到日誌事件，將中繼資料新增至日誌事件：`@logGroupName`、`@logGroupStream`、`@accountId`、`@regionName`。這會在下列範例中說明。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都可以包含 source、 target和 overwriteIfExists 欄位。 | 是 | | 項目上限：5 | | source | 要複製的金鑰 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | 目標 | 將值複製到 的金鑰 | 是 | 沒有限制 | 長度上限：128 巢狀金鑰深度上限：3 | | overwriteIfExists | 如果您將此設定為 true，則如果事件中key已存在，則會覆寫現有的值。預設值為 false。 | 否 | false | 沒有限制 | **範例** 採用下列範例日誌事件： ``` { "outer_key": { "inner_key": "inner_value" } } ``` 轉換器組態是這樣，使用 `copyValue`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "copyValue": { "entries": [ { "key": "outer_key.new_key", "target": "new_key" }, { "source": "@logGroupName", "target": "log_group_name" }, { "source": "@logGroupStream", "target": "log_group_stream" }, { "source": "@accountId", "target": "account_id" }, { "source": "@regionName", "target": "region_name" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": { "inner_key": "inner_value" }, "new_key": "inner_value", "log_group_name": "myLogGroupName", "log_group_stream": "myLogStreamName", "account_id": "012345678912", "region_name": "us-east-1" } ``` ## listToMap `listToMap` 處理器會取得包含金鑰欄位的物件清單，並將其轉換為目標金鑰的映射。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | source | ProcessingEvent 中的金鑰，其中包含將轉換為映射的物件清單 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | 金鑰 | 要擷取為所產生映射中索引鍵的欄位索引鍵 | 是 | | 長度上限：128 | | valueKey | 如果指定此值，您在此參數中指定的值將從source物件中擷取，並放入產生的映射值中。否則，來源清單中的原始物件會放入產生的映射值中。 | 否 | | 長度上限：128 | | 目標 | 將存放所產生映射之欄位的索引鍵 | 否 | 根節點 | 長度上限：128 巢狀金鑰深度上限：3 | | flatten | 布林值，指出清單是否將扁平化為單一項目，或產生的映射中的值是否將是清單。 根據預設，相符索引鍵的值會以陣列表示。`flatten` 設定為 `true` 以根據 的值將陣列轉換為單一值`flattenedElement`。 | 否 | false | | | flattenedElement | 如果您將 flatten設定為 true，請使用 flattenedElement指定要保留的元素 lastfirst或 。 | `flatten` 當 設定為 時為必要 `true` | | 值只能為 first或 last | **範例** 採用下列範例日誌事件： ``` { "outer_key": [ { "inner_key": "a", "inner_value": "val-a" }, { "inner_key": "b", "inner_value": "val-b1" }, { "inner_key": "b", "inner_value": "val-b2" }, { "inner_key": "c", "inner_value": "val-c" } ] } ``` **使用案例 1 的轉換器：** `flatten`是 `false` ``` [ { "parseJSON": {} }, { "listToMap": { "source": "outer_key" "key": "inner_key", "valueKey": "inner_value", "flatten": false } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": [ { "inner_key": "a", "inner_value": "val-a" }, { "inner_key": "b", "inner_value": "val-b1" }, { "inner_key": "b", "inner_value": "val-b2" }, { "inner_key": "c", "inner_value": "val-c" } ], "a": [ "val-a" ], "b": [ "val-b1", "val-b2" ], "c": [ "val-c" ] } ``` **使用案例 2 的轉換器：** `flatten` 是 `true`， `flattenedElement`是 `first` ``` [ { "parseJSON": {} }, { "listToMap": { "source": "outer_key" "key": "inner_key", "valueKey": "inner_value", "flatten": true, "flattenedElement": "first" } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": [ { "inner_key": "a", "inner_value": "val-a" }, { "inner_key": "b", "inner_value": "val-b1" }, { "inner_key": "b", "inner_value": "val-b2" }, { "inner_key": "c", "inner_value": "val-c" } ], "a": "val-a", "b": "val-b1", "c": "val-c" } ``` **使用案例 3 的轉換器：** `flatten` 是 `true`， `flattenedElement`是 `last` ``` [ { "parseJSON": {} }, { "listToMap": { "source": "outer_key" "key": "inner_key", "valueKey": "inner_value", "flatten": true, "flattenedElement": "last" } } ] ``` 轉換的日誌事件如下。 ``` { "outer_key": [ { "inner_key": "a", "inner_value": "val-a" }, { "inner_key": "b", "inner_value": "val-b1" }, { "inner_key": "b", "inner_value": "val-b2" }, { "inner_key": "c", "inner_value": "val-c" } ], "a": "val-a", "b": "val-b2", "c": "val-c" } ``` # 資料類型轉換器處理器 本節包含您可以與日誌事件轉換器搭配使用之資料類型轉換器處理器的相關資訊。 **Contents** + [typeConverter](#CloudWatch-Logs-Transformation-typeConverter) + [datetimeConverter](#CloudWatch-Logs-Transformation-datetimeConverter) ## typeConverter 使用`typeConverter`處理器將與指定索引鍵相關聯的值類型轉換為指定的類型。它是一種轉換處理器，可變更指定欄位的類型。值可以轉換為下列其中一種資料類型：`integer`、 `double``string`和 `boolean`。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | 項目 | 項目陣列。陣列中的每個項目都必須包含 key和 type 欄位。 | 是 | | 項目上限：10 | | 金鑰 | 具有要轉換為不同類型之值的金鑰 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | type | 要轉換的類型。有效值為 integer、 doublestring和 boolean。 | 是 | | | **範例** 採用下列範例日誌事件： ``` { "name": "value", "status": "200" } ``` 轉換器組態是這樣，使用 `typeConverter`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "typeConverter": { "entries": [ { "key": "status", "type": "integer" } ] } } ] ``` 轉換的日誌事件如下。 ``` { "name": "value", "status": 200 } ``` ## datetimeConverter 使用`datetimeConverter`處理器將日期時間字串轉換為您指定的格式。 | 欄位 | Description | 是否為必要？ | 預設 | 限制 | | --- | --- | --- | --- | --- | | source | 要套用日期轉換的金鑰。 | 是 | | 項目上限：10 | | matchPatterns | 要比對 source 欄位的模式清單 | 是 | | 項目上限：5 | | 目標 | 存放結果的 JSON 欄位。 | 是 | | 長度上限：128 巢狀金鑰深度上限：3 | | targetFormat | 用於目標欄位中轉換資料的日期時間格式。 | 否 | ` yyyy-MM-dd'T'HH:mm:ss.SSS'Z` | 長度上限：64 | | sourceTimezone | 來源欄位的時區。 如需可能值的清單，請參閱 [ Java 支援的區域 ID 和位移](https://howtodoinjava.com/java/date-time/supported-zone-ids-offsets/#3-java-supported-zone-ids-and-offsets)。 | 否 | UTC | 長度下限：1 | | targetTimezone | 目標欄位的時區。 如需可能值的清單，請參閱 [ Java 支援的區域 ID 和位移](https://howtodoinjava.com/java/date-time/supported-zone-ids-offsets/#3-java-supported-zone-ids-and-offsets)。 | 否 | UTC | 長度下限：1 | | locale | 來源欄位的地區設定。 如需可能值的清單，請參閱 [ Java 中的 Locale getAvailableLocales() 方法與範例](https://www.geeksforgeeks.org/locale-getavailablelocales-method-in-java-with-examples/)。 | 是 | | 長度下限：1 | **範例** 採用下列範例日誌事件： ``` {"german_datetime": "Samstag 05. Dezember 1998 11:00:00"} ``` 轉換器組態是這樣，使用 `dateTimeConverter`搭配 `parseJSON`： ``` [ { "parseJSON": {} }, { "dateTimeConverter": { "source": "german_datetime", "target": "target_1", "locale": "de", "matchPatterns": ["EEEE dd. MMMM yyyy HH:mm:ss"], "sourceTimezone": "Europe/Berlin", "targetTimezone": "America/New_York", "targetFormat": "yyyy-MM-dd'T'HH:mm:ss z" } } ] ``` 轉換的日誌事件如下。 ``` { "german_datetime": "Samstag 05. Dezember 1998 11:00:00", "target_1": "1998-12-05T17:00:00 MEZ" } ``` # 轉換指標和錯誤 CloudWatch Logs 會將轉換指標發佈至 CloudWatch。這些指標包括 `TransformedLogEvents`、 `TransformedBytes`和 `TransformationErrors`。如需詳細資訊，請參閱[日誌轉換器指標和維度](CloudWatch-Logs-Monitoring-CloudWatch-Metrics.md#CloudWatchLogs-Transformer-Metrics)。 每當 CloudWatch Logs 嘗試轉換日誌事件而失敗時，就會將`@transformationError`系統欄位新增至該日誌事件。當您執行 CloudWatch Logs Insights 查詢時，您會在所有發生轉換失敗的日誌事件中看到此欄位。您可以使用 等查詢來查詢此欄位，`filter ispresent(@transformationError)`以尋找所有失敗的轉換事件。