本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 CloudWatch Logs Insights 分析日誌資料 使用 CloudWatch Logs Insights，您可以在 Amazon CloudWatch Logs 中以互動方式搜尋和分析日誌資料。您可以執行查詢，協助您更有效率且有效地回應操作問題。除了使用日誌群組查詢之外，您還可以使用面向、資料來源和資料類型進行查詢。如果發生問題，您可以使用 CloudWatch Logs 來識別可能的原因並驗證已部署的修正。每個帳戶僅限 100 個並行 CloudWatch Logs Insights QL，包括新增至儀表板的查詢。此外，您可以為 OpenSearch Service PPL 或 OpenSearch Service SQL 執行 15 個並行查詢。 CloudWatch Logs Insights 支援三種查詢語言，可用於查詢： + 專用 **Logs Insights 查詢語言 (Logs Insights QL)**，具有幾個簡單但強大的命令。 + **OpenSearch Service 管道處理語言 (PPL)**。OpenSearch PPL 可讓您使用一組以管道 (\$1) 分隔的命令來分析日誌。 使用 OpenSearch PPL，您可以使用一起輸送的命令來擷取、查詢和分析資料，讓您更輕鬆地了解和編寫複雜的查詢。語法可讓命令鏈結轉換和處理資料。使用 PPL，您可以篩選和彙總資料，並使用一組豐富的數學、字串、日期、條件式和其他函數進行分析。 + **OpenSearch Service 結構化查詢語言 (SQL)**。使用 OpenSearch SQL 查詢，您可以宣告方式分析日誌。您可以使用 SELECT、 FROM、WHERE、GROUP BY、HAVING 等命令，以及 SQL 中可用的各種其他命令和函數。您可以跨日誌群組執行 JOINs、使用子查詢關聯日誌之間的資料，並使用一組豐富的 JSON、數學、字串、條件式和其他 SQL 函數對日誌執行強大的分析。 當您使用 SQL 或 PPL 命令時，請務必在反引號中以特殊字元 （非字母和非數字） 括住欄位，以成功查詢它們。例如，將 `@message`、 `Operation.Export`和 括在反引號`Test::Field`中。您不需要在反引號中以純字母名稱括住欄位。 CloudWatch Logs Insights 提供下列功能，可與任何查詢語言搭配使用。 + 從 Amazon Route 53 AWS Lambda、 和 Amazon VPC 等服務 AWS CloudTrail自動[*探索日誌中的日誌欄位*](CWL_AnalyzeLogData-discoverable-fields.md)，以及以 JSON 形式發出日誌事件的任何應用程式或自訂日誌。 AWS + 建立[*欄位索引*](CloudWatchLogs-Field-Indexing.md)以降低成本和加速結果，尤其是針對大量日誌群組或日誌事件的查詢。在建立日誌事件中常見欄位的欄位索引之後，您可以在查詢中使用它們。查詢會略過處理已知不包含索引欄位的日誌事件，並處理較少的資料。 **注意** `filterIndex` 命令僅適用於 Logs Insights QL。 + [*偵測和分析日誌事件中的模式*](CWL_AnalyzeLogData_Patterns.md)。模式是在您的日誌欄位之間重複出現的共用文字結構。當您檢視查詢的結果時，您可以選擇**模式**索引標籤，以查看 CloudWatch Logs 根據結果範例找到的模式。 + [*儲存查詢*](CWL_Insights-Saving-Queries.md)、查看您的查詢歷史記錄、重新執行已儲存的查詢，以及[搭配參數使用已儲存的查詢](CWL_Insights-Saving-Queries.md#CWL_Insights-Parameterized-Queries)。 + [*將查詢新增至儀表板*](CWL_ExportQueryResults.md)。 + [*使用 加密查詢結果 AWS Key Management Service*](CloudWatchLogs-Insights-Query-Encrypt.md)。 + [使用自然語言產生查詢](CloudWatchLogs-Insights-Query-Assist.md)可讓您使用自然語言來建立 CloudWatch Logs Insights 查詢。您可以詢問問題或描述您要尋找的資料，然後 AI 會根據您的提示產生查詢，並提供查詢運作方式的line-by-line說明。 + [使用面向來分組、篩選和互動探索您的日誌](CloudWatchLogs-Facets.md)。 只有在您使用 Logs Insights QL 時，才支援下列 CloudWatch Logs Insights 功能。 + [比較查詢](CWL_AnalyzeLogData_Compare.md)，將日誌群組中的日誌事件與上一個時段的日誌事件進行比較。 **重要** CloudWatch Logs Insights 無法存取時間戳記早於日誌群組建立時間的日誌事件。 如果您登入的帳戶設定為 CloudWatch 跨帳戶觀察功能中的監控帳戶，則可以對連結至此監控帳戶之來源帳戶中的日誌群組執行 CloudWatch Logs Insights 查詢。您可以查詢位於不同帳戶中的多個日誌群組。如需詳細資訊，請參閱 [CloudWatch 跨帳戶觀察功能](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)。 當您使用 Logs Insights QL 建立查詢時，您也可以使用自然語言來建立 CloudWatch Logs Insights 查詢。因此，請提出問題或描述您正在尋找的資料。此 AI 輔助功能會根據您的提示產生查詢，並逐行說明查詢的運作方式。如需詳細資訊，請參閱[使用自然語言來產生和更新 CloudWatch Logs Insights 查詢](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs-Insights-Query-Assist.html)。 使用任何支援的查詢語言的查詢，如果尚未完成，會在 60 分鐘後逾時。查詢結果提供七天。 無論查詢語言為何，CloudWatch Logs Insights 查詢都會根據查詢的資料量產生費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。 您可以使用 CloudWatch Logs Insights 來搜尋在 2018 年 11 月 5 日或之後傳送至 CloudWatch Logs 的日誌資料。 **重要** 如果您的網路安全團隊不允許使用 web 通訊端，則您目前無法存取 CloudWatch 主控台的 CloudWatch Logs Insights 部分。您可以透過 API 來使用 CloudWatch Logs Insights 查詢功能。如需詳細資訊，請參閱《Amazon CloudWatch Logs API 參考》**中的 [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)。 **Topics** + [支援的查詢語言](CWL_AnalyzeLogData_Languages.md) + [使用自然語言來產生和更新 CloudWatch Logs Insights 查詢](CloudWatchLogs-Insights-Query-Assist.md) + [支援的日誌和探索的欄位](CWL_AnalyzeLogData-discoverable-fields.md) + [建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md) + [使用面向來分組和探索日誌](CloudWatchLogs-Facets.md) + [模式分析](CWL_AnalyzeLogData_Patterns.md) + [儲存並重新執行 CloudWatch Logs Insights 查詢](CWL_Insights-Saving-Queries.md) + [將查詢新增到儀表板或匯出查詢結果](CWL_ExportQueryResults.md) + [檢視執行中的查詢或查詢歷史記錄](CloudWatchLogs-Insights-Query-History.md) + [使用 加密查詢結果 AWS Key Management Service](CloudWatchLogs-Insights-Query-Encrypt.md) + [從 CloudWatch Logs Insights 查詢結果產生自然語言摘要](CloudWatchLogs-Insights-Query-Results-Summary.md) # 支援的查詢語言 下列各節列出每種查詢語言支援的命令。它們也會描述語法格式並提供範例查詢。 **Topics** + [CloudWatch Logs Insights 查詢語言 (Logs Insights QL)](CWL_AnalyzeLogData_LogsInsights.md) + [OpenSearch 管道處理語言 (PPL)](CWL_AnalyzeLogData_PPL.md) + [OpenSearch 結構化查詢語言 (SQL)](CWL_AnalyzeLogData_SQL.md) # CloudWatch Logs Insights 查詢語言 (Logs Insights QL) 本節包含 Logs Insights QL 命令和函數的完整文件。它也包含此語言的範例查詢。 如需有關您可以使用的其他查詢語言的資訊，請參閱 [OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html)、[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) 和 [CloudWatch。 Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html) **Topics** + [CloudWatch Logs Insights 語言查詢語法](CWL_QuerySyntax.md) + [Logs Insights QL 入門：查詢教學課程](CWL_AnalyzeLogData_Tutorials.md) + [範例查詢](CWL_QuerySyntax-examples.md) + [比較 （差異） 與先前的時間範圍](CWL_AnalyzeLogData_Compare.md) + [在圖表中視覺化日誌資料](CWL_Insights-Visualizing-Log-Data.md) # CloudWatch Logs Insights 語言查詢語法 本節提供有關 Logs Insights QL 的詳細資訊。查詢語法支援不同的函式和運算，包含但不限於一般函式、算術和比較運算，以及正規表達式。 **重要** 為了避免因執行大型查詢而產生過多費用，請記住下列最佳實務： 為每個查詢僅選取必要的日誌群組。 一律為您的查詢指定最窄的可能時間範圍。 當您使用主控台執行查詢時，請先取消所有查詢，再關閉 CloudWatch Logs Insights 主控台頁面。否則，查詢會繼續執行直到完成。 當您將 CloudWatch Logs Insights 小工具新增至儀表板時，請確定儀表板不會以高頻率重新整理，因為每次重新整理都會啟動新的查詢。 若要建立包含多個命令的查詢，請使用直立線符號字元 (**\$1**) 分隔命令。 若要建立包含註解的查詢，請使用雜湊字元 (**\$1**) 作為註解的開頭。 **注意** CloudWatch Logs Insights 會自動探索不同日誌類型的欄位，並產生以 **@** 字元開頭的欄位。如需進一步了解這些自動產生的欄位，請參閱《*Amazon CloudWatch 使用者指南*》中的[支援的日誌和探索的欄位](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData-discoverable-fields.html)。 下表簡要描述每個命令。此資料表下面是每個命令的詳細說明，並附有範例。 **注意** 標準日誌類別中的日誌群組支援所有 Logs Insights QL 查詢命令。不常存取日誌類別中的日誌群組支援所有 Logs Insights QL 查詢命令`pattern`，但 `diff`、 和 除外`unmask`。 | | | | --- |--- | | **` anomaly`** | 使用機器學習識別日誌資料中的異常模式。 | | **` display`** | 在查詢結果中顯示一個或多個特定欄位。 | | **` fields`** | 在查詢結果中顯示特定欄位，並支援可用於修改欄位值和建立要在查詢中使用之新欄位的函數和操作。 | | **` filter`** | 篩選查詢以僅傳回符合一個或多個條件的日誌事件。 | | **` filterIndex`** | 強制查詢只嘗試掃描在欄位索引中提到的欄位上編製索引的日誌群組，並同時包含該欄位索引的值。這透過嘗試僅掃描這些日誌群組中包含此欄位索引查詢中指定值的日誌事件來減少掃描的磁碟區。 不常存取日誌類別中的日誌群組不支援此命令。 | | **` pattern`** | 自動將您的日誌資料叢集化，以形成模式。模式是指日誌欄位之間反覆出現的共同文字結構。CloudWatch Logs Insights 可讓您分析日誌事件中找到的模式。如需詳細資訊，請參閱[模式分析](CWL_AnalyzeLogData_Patterns.md)。 | | **` diff`** | 將請求時段中找到的日誌事件與先前相同長度時段的日誌事件進行比較，以便您可以尋找趨勢並了解特定日誌事件是否為新事件。 | | **` parse`** | 從日誌欄位擷取資料，建立一個您可在查詢中處理的擷取欄位。**`parse`** 支援使用萬用字元的 glob 模式和規則運算式。 | | **` sort`** | 以遞增 (`asc`) 或遞減 (`desc`) 方式顯示傳回的日誌事件。 | | **` SOURCE`** | 在查詢`SOURCE`中包含 是根據要在查詢中包含的日誌群組名稱字首、帳戶識別符和日誌群組類別來指定大量日誌群組的有用方法。只有在您在 中 AWS CLI 或以程式設計方式建立查詢時，才支援此命令，而不是在 CloudWatch 主控台中。 | | **` stats`** | 使用日誌欄位值計算彙總統計數字。 | | **` limit`** | 指定您希望查詢傳回的日誌事件數目上限。使用 **`sort`** 可傳回「前 20 個」或「最近 20 個」結果。 | | **` dedup`** | 根據您指定之欄位中的特定值移除重複的結果。 | | **` unmask`** | 顯示因為資料保護政策而遮罩某些內容的某個日誌事件的全部內容。如需有關日誌群組中資料保護的詳細資訊，請參閱 [使用遮罩功能協助保護敏感日誌資料](mask-sensitive-log-data.md)。 | | **`[unnest](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-Unnest.html)`** | 扁平化做為輸入的清單，以針對清單中的每個元素產生具有單一記錄的多個記錄。 | | **` lookup`** | 透過比對欄位值，使用查詢資料表中的資料來豐富日誌事件。使用查詢資料表將參考資料，例如使用者詳細資訊、應用程式名稱或產品資訊新增至查詢結果。 | | ** [其他操作和函數](CWL_QuerySyntax-operations-functions.md)** | CloudWatch Logs Insights 也支援許多比較、算術、日期時間、數值、字串、IP 地址以及一般函數和操作。 | 以下各節提供有關 CloudWatch Logs Insights 查詢命令的詳細資訊。 **Topics** + [日誌類別中支援的 Logs Insights QL 命令](CWL_AnalyzeLogData_Classes.md) + [異常](CWL_QuerySyntax-Anomaly.md) + [**display**](CWL_QuerySyntax-Display.md) + [fields](CWL_QuerySyntax-Fields.md) + [篩選條件](CWL_QuerySyntax-Filter.md) + [filterIndex](CWL_QuerySyntax-FilterIndex.md) + [SOURCE](CWL_QuerySyntax-Source.md) + [pattern](CWL_QuerySyntax-Pattern.md) + [差異](CWL_QuerySyntax-Diff.md) + [parse](CWL_QuerySyntax-Parse.md) + [sort](CWL_QuerySyntax-Sort.md) + [統計資料](CWL_QuerySyntax-Stats.md) + [limit](CWL_QuerySyntax-Limit.md) + [dedup](CWL_QuerySyntax-Dedup.md) + [unmask](CWL_QuerySyntax-Unmask.md) + [解巢狀](CWL_QuerySyntax-Unnest.md) + [查詢](CWL_QuerySyntax-Lookup.md) + [布林值、比較、數值、日期時間和其他函數](CWL_QuerySyntax-operations-functions.md) + [包含特殊字元的欄位](CWL_QuerySyntax-Guidelines.md) + [在查詢中使用別名和註解](CWL_QuerySyntax-alias.md) # 日誌類別中支援的 Logs Insights QL 命令 標準日誌類別中的日誌群組支援所有 Logs Insights QL 查詢命令。不常存取日誌類別中的日誌群組支援 `pattern`、`filterIndex`、 `diff`和 以外的所有查詢命令`unmask`。 # 異常 使用 `anomaly`以機器學習自動識別日誌資料中的異常模式和潛在問題。 `anomaly` 命令會擴展現有`pattern`功能，並利用進階分析來協助識別日誌資料中的潛在異常。您可以使用 `anomaly`來減少在日誌中自動浮現異常模式或行為來識別和解決操作問題所需的時間。 `anomaly` 命令會搭配 ` pattern`命令使用，先識別日誌模式，然後偵測這些模式中的異常。您也可以`anomaly`結合 ` filter`或 ` sort`命令，將異常偵測聚焦於資料的特定子集。 **異常命令輸入** `anomaly` 命令通常會在` pattern`命令之後使用，以分析日誌資料中識別的模式。命令不需要其他參數，並分析查詢中先前命令的輸出。 **已識別的異常類型** `anomaly` 命令會識別五種不同的異常類型： + *模式頻率異常*：特定日誌模式的異常頻率，例如應用程式開始產生比平常更多的錯誤訊息時。 + *新模式異常*：先前看不到的日誌模式可能表示日誌中出現新類型的錯誤或訊息。 + *字符變化異常*：日誌訊息內容的非預期變更，可能表示預期日誌格式的異常變化。 + *數值符記異常*：日誌中數值的異常變更，可協助偵測潛在的效能問題或非預期的指標變化。 + *HTTP 錯誤碼異常*：與 HTTP 錯誤回應相關的模式，在監控 Web 應用程式和 APIs時特別有用。 **異常命令輸出** `anomaly` 命令會保留輸入資料中的所有欄位，並新增異常偵測結果，以協助識別日誌資料中的異常模式。 **範例** 下列命令會識別日誌資料中的模式，然後偵測這些模式中的異常： ``` fields @timestamp, @message | pattern @message | anomaly ``` `anomaly` 命令可與篩選搭配使用，以專注於特定日誌類型： ``` fields @timestamp, @message | filter @type = "REPORT" | pattern @message | anomaly ``` `anomaly` 命令可與排序結合，以組織結果： ``` fields @timestamp, @message | filter @type = "ERROR" | pattern @message | anomaly | sort @timestamp desc ``` # **display** 使用 `display` 在查詢結果中顯示一個或多個特定欄位。 `display` 命令僅顯示您指定的欄位。如果您的查詢包含多個 `display` 命令，查詢結果僅會顯示您在最終 `display` 命令中指定的欄位。 **範例：顯示一個欄位** 程式碼片段會顯示一個查詢範例，其使用剖析命令從 `@message` 中擷取資料，建立擷取欄位 `loggingType` 和 `loggingMessage`。查詢會傳回 `loggingType` 的值為 **ERROR** 的所有日誌事件。`display` 僅在查詢結果中顯示 `loggingMessage` 的值。 ``` fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage ``` **提示** 在查詢中僅使用一次 `display`。如果您在查詢中多次使用 `display`，則查詢結果只會顯示您最後一次使用 `display` 命令時指定的欄位。 # fields 使用 `fields` 在查詢結果中顯示特定欄位。 如果您的查詢包含多個 `fields` 命令且未包含 `display` 命令，則結果會顯示在 `fields` 命令中指定的所有欄位。 **範例：顯示特定欄位** 下列範例顯示一個查詢，它傳回 20 個日誌事件並按降序顯示它們。會在查詢結果中顯示 `@timestamp` 和 `@message` 的值。 ``` fields @timestamp, @message | sort @timestamp desc | limit 20 ``` 當您想要使用 支援的不同函數和操作`fields`來修改欄位值，並建立新的欄位以用於查詢`display`時，請使用 `fields`而非 。 您可以搭配使用 `fields` 命令和關鍵字 *as*，在日誌事件中建立使用欄位和函數的擷取欄位。例如：`fields ispresent as isRes` 會建立一個名為 `isRes` 的擷取欄位，而擷取欄位可在其餘查詢中使用。 # 篩選條件 使用 `filter` 來取得與一個或多個條件相符的日誌事件。 **範例：使用一個條件篩選日誌事件** 程式碼片段會顯示一個查詢範例，其會傳回 `range` 的值大於 ***3000*** 的所有日誌事件。該查詢將結果限制為 20 筆日誌事件，並按照 `@timestamp` 依遞減順序對日誌事件進行排序。 ``` fields @timestamp, @message | filter (range>3000) | sort @timestamp desc | limit 20 ``` **範例：使用多個條件篩選日誌事件** 您可以使用關鍵字 `and` 和 `or` 以結合多個條件。 程式碼片段會顯示一個查詢範例，其會傳回 `range` 的值大於 ***3000*** 且 `accountId` 的值等於 ***123456789012*** 的日誌事件。該查詢將結果限制為 20 筆日誌事件，並按照 `@timestamp` 依遞減順序對日誌事件進行排序。 ``` fields @timestamp, @message | filter (range>3000 and accountId=123456789012) | sort @timestamp desc | limit 20 ``` ## 索引欄位和 filter 命令 如果您已為日誌群組建立欄位索引，您可以利用這些欄位索引，讓您的`filter`查詢更有效率並減少掃描的磁碟區。例如，假設您已建立 的欄位索引`requestId`。然後，該日誌群組上包含`filter requestId = value`或`filter requestId IN [value, value, ...]`將嘗試略過處理已知不包含索引欄位的日誌事件的任何 CloudWatch Logs Insights 查詢。透過嘗試僅掃描已知包含該索引欄位的日誌事件，可以減少掃描磁碟區，並且查詢更快。 如需欄位索引以及如何建立它們的詳細資訊，請參閱 [建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。 **重要** 只有具有 `filter fieldName =...`和 的查詢`filter fieldName IN...`將受益於欄位索引改進。使用 的查詢`filter fieldName like`不使用索引，並一律掃描所選日誌群組中的所有日誌事件。 ** 範例：使用索引尋找與特定請求 ID 相關的日誌事件 ** 此範例假設您已在 上建立欄位索引`requestId`。對於使用此欄位索引的日誌群組，查詢會利用欄位索引嘗試掃描最少數量的日誌事件，以尋找值`requestId`為 的事件 `123456` ``` fields @timestamp, @message | filter requestId = "1234656" | limit 20 ``` ## filter 命令中的比對和規則表達式 篩選命令支援使用規則表達式。您可以使用下列比較運算子 (`=`、`!=`、`<`、`<=`、`>`、`>=`) 和布林值運算子 (`and`、`or` 以及 `not`)。 您可以使用關鍵字 `in` 來測試設定的成員資格並檢查陣列中的元素。若要檢查陣列中的元素，將陣列放在 `in` 之後。您可以搭配 `in` 使用布林運算子 `not`。您可以建立查詢来使用 `in` 傳回欄位為字串相符的日誌事件。欄位必須是完整的字串。例如，下列程式碼片段會顯示查詢使用 `in` 来傳回欄位 `logGroup` 是完整的字串 `example_group` 的日誌事件。 ``` fields @timestamp, @message | filter logGroup in ["example_group"] ``` 您可以使用關鍵字詞 `like` 和 `not like` 來比對子字串。您可以使用規則表達式運算子 `=~` 來比對子字串。若要比對帶有 `like` 和 `not like` 的子字串，請將要比對的子字串放在單引號或雙引號中。您可以搭配 `like` 和 `not like` 使用規則表達式模式。若要使用規則表達式運算子來比對子字串，請以斜線括住想要比對的子字串。下列範例包含程式碼片段，示範如何使用 `filter` 命令來比對子字串。 **範例：比對子字串** 以下範例會傳回 `f1` 含有單字 ***Exception*** 的日誌事件。所有三個範例都會區分大小寫。 第一個範例比對帶有 `like` 的子字符。 ``` fields f1, f2, f3 | filter f1 like "Exception" ``` 第二個範例比對帶有 `like` 和規則表達式模式的子字串。 ``` fields f1, f2, f3 | filter f1 like /Exception/ ``` 第三個範例會比對子字串與規則表達式。 ``` fields f1, f2, f3 | filter f1 =~ /Exception/ ``` **範例：比對子字串與萬用字元** 您可以使用句點符號 (`.`) 作為規則表達式中的萬用字元來比對子字串。在下列範例中，查詢會傳回與以字串 `ServiceLog` 開始的 `f1` 的值相符項目。 ``` fields f1, f2, f3 | filter f1 like /ServiceLog./ ``` 您可以在句點符號 (`.*`) 後面放置一個星號符號，來建立窮盡數量詞，窮盡數量詞會傳回儘可能多的相符項目。例如，以下查詢會傳回與以字串 `ServiceLog` 開始而且還包含字串 `ServiceLog` 的 `f1` 的值相符項目。 ``` fields f1, f2, f3 | filter f1 like /ServiceLog.*/ ``` 可能的相符項目格式如下所示： + `ServiceLogSampleApiLogGroup` + `SampleApiLogGroupServiceLog` **範例：從相符項目中排除子字串** 以下範例會顯示會傳回日誌事件的查詢，傳回的日誌事件中 `f1` 不會含有單字 ***Exception***。這個範例區分大小寫。 ``` fields f1, f2, f3 | filter f1 not like "Exception" ``` **範例：比對區分大小寫的子字串** 您可以比對帶有 `like` 和規則表達式且區分大小寫的子字串。請將下列參數 (**?i**) 放置在想要比對的子字串之前。下列範例會顯示會傳回日誌事件的查詢，傳回的日誌事件中 `f1` 會含有單字 ***Exception*** 或 ***exception***。 ``` fields f1, f2, f3 | filter f1 like /(?i)Exception/ ``` # filterIndex `filterIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。對於在此欄位上編製索引的這些日誌群組，它會略過沒有包含索引欄位查詢中指定欄位的任何日誌事件的日誌群組，以進一步最佳化查詢。它透過嘗試僅掃描這些日誌群組中符合此欄位索引查詢中指定值的日誌事件，進一步減少掃描的磁碟區。如需欄位索引以及如何建立它們的詳細資訊，請參閱 [建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。 透過將實際搜尋空間限制為具有欄位索引的日誌群組和日誌事件，使用 `filterIndex`搭配索引欄位可協助您有效率地查詢包含 PB 日誌資料的日誌群組。 例如，假設您已在帳戶中的某些日誌群組`IPaddress`中為 建立欄位索引。然後，您可以建立下列查詢，並選擇查詢帳戶中的所有日誌群組，以尋找包含 `198.51.100.0` `IPaddress` 欄位中值的日誌事件。 ``` fields @timestamp, @message | filterIndex IPaddress = "198.51.100.0" | limit 20 ``` `filterIndex` 命令會導致此查詢嘗試略過未為 編製索引的所有日誌群組`IPaddress`。此外，在編製索引的日誌群組中，查詢會略過具有 `IPaddress` 欄位，但未觀察`198.51.100.0`為該欄位值的日誌事件。 使用 `IN`運算子將結果擴展到索引欄位的多個值中的任何一個。下列範例會尋找 `198.51.100.1`欄位中包含 值`198.51.100.0`或 的日誌事件`IPaddress`。 ``` fields @timestamp, @message | filterIndex IPaddress in ["198.51.100.0", "198.51.100.1"] | limit 20 ``` CloudWatch Logs 為標準日誌類別中的所有日誌群組提供預設欄位索引。預設欄位索引會自動用於下列欄位： + `@logStream` + `@aws.region` + `@aws.account` + `@source.log` + `@data_source_name` + `@data_source_type` + `@data_format` + `traceId` + `severityText` + `attributes.session.id` CloudWatch Logs 也提供特定資料來源名稱和類型組合的預設欄位索引。預設欄位索引會自動用於下列資料來源名稱和類型組合： | 資料來源名稱和類型 | 預設欄位索引 | | --- | --- | | `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` | | `amazon_route53.resolver_query` | `query_type` `transport` `rcode` | | `aws_waf.access` | `action` `httpRequest.country` | | `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` | 預設欄位索引是附加於您在政策中定義的任何自訂欄位索引。預設欄位索引不會計入您的[欄位索引配額](CloudWatchLogs-Field-Indexing-Syntax.md)。 ## filterIndex 與篩選條件的比較 若要說明 `filterIndex`和 之間的差異`filter`，請考慮下列範例查詢。假設您已為四個日誌群組建立 的欄位索引`IPaddress`，但不是為第五個日誌群組建立。下列使用 的查詢`filterIndex`會略過掃描沒有欄位索引的日誌群組。對於每個索引日誌群組，它會嘗試僅掃描具有索引欄位的日誌事件，而且也會在建立欄位索引之後僅傳回 的結果。 ``` fields @timestamp, @message | filterIndex IPaddress = "198.51.100.0" | limit 20 ``` 相反地，如果您使用 `filter`而不是 `filterIndex` 來查詢相同的五個日誌群組，查詢不僅會嘗試掃描索引日誌群組中包含 值的日誌事件，還會掃描未編製索引的第五個日誌群組，而且會掃描該第五個日誌群組中的每個日誌事件。 ``` fields @timestamp, @message | filter IPaddress = "198.51.100.0" | limit 20 ``` # SOURCE 當您使用 或 API 建立查詢時，在查詢`SOURCE`中包含 是指定要包含在查詢中的日誌群組和/ AWS CLI 或資料來源的實用方式。`SOURCE` 命令僅在 AWS CLI 和 API 中受支援，在 CloudWatch 主控台中不受支援。當您使用 CloudWatch 主控台啟動查詢時，您可以使用主控台界面來指定日誌群組。 查詢日誌群組 若要使用 `SOURCE` 指定要查詢的日誌群組，您可以使用下列關鍵字： + `namePrefix` 針對名稱開頭為您所指定字串的日誌群組執行查詢。如果您省略此選項，則會查詢所有日誌群組。 您可以在清單中包含最多五個字首。 + `accountIdentifier` 針對指定 AWS 帳戶中的日誌群組執行查詢。這只有在您在監控帳戶中執行查詢時才有效。如果您省略此選項，預設為查詢所有連結的來源帳戶和目前的監控帳戶。如需跨帳戶可觀測性的詳細資訊，請參閱 [CloudWatch 跨帳戶可觀測性](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)。 您可以在清單中包含多達 20 個帳戶識別符。 + `logGroupClass` 針對指定日誌類別中的日誌群組執行查詢，可以是標準存取或不常存取。如果您省略此選項，則會使用標準日誌類別的預設值。如需日誌類別的詳細資訊，請參閱 [日誌類別](CloudWatch_Logs_Log_Classes.md)。 由於您可以指定大量日誌群組以這種方式查詢，因此建議您`SOURCE`僅在利用您已建立之欄位索引的查詢中使用 。如需在日誌群組中為欄位編製索引的詳細資訊，請參閱 [建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md) 下列範例會選取帳戶中的所有日誌群組。如果這是監控帳戶，則會選取監控和所有來源帳戶的日誌群組。如果日誌群組總數超過 10，000，則您會看到錯誤，提示您使用不同的日誌群組選取方法來減少日誌群組數量。 ``` SOURCE logGroups() ``` 下列範例會選取`111122223333`來源帳戶中的日誌群組。如果您在 CloudWatch 跨帳戶可觀測性的監控帳戶中啟動查詢，預設會選取所有來源帳戶和監控帳戶中的日誌群組。 ``` SOURCE logGroups(accountIdentifiers:['111122223333']) ``` 下一個範例會根據名稱字首選取日誌群組。 ``` SOURCE logGroups(namePrefix: ['namePrefix1', 'namePrefix2']) ``` 下列範例會選取不常存取日誌類別中的所有日誌群組。如果您未包含識別`class`符，查詢只會套用至標準日誌類別中的日誌群組，這是預設值。 ``` SOURCE logGroups(class: ['INFREQUENT_ACCESS']) ``` 下一個範例會選取 111122223333 帳戶中以特定名稱字首開頭且位於標準日誌類別的日誌群組。命令中未提及 類別，因為 Standard 是預設的日誌類別值。 ``` SOURCE logGroups(accountIdentifiers:['111122223333'], namePrefix: ['namePrefix1', 'namePrefix2'] ``` 最後一個範例顯示如何搭配 `SOURCE`命令使用 `start-query` AWS CLI 命令。 ``` aws logs start-query --region us-east-1 --start-time 1729728200 --end-time 1729728215 --query-string "SOURCE logGroups(namePrefix: ['Query']) | fields @message | limit 5" ``` 查詢資料來源 若要使用 `SOURCE` 指定要查詢的資料來源，您可以使用 `dataSource`關鍵字。您可以在清單中包含多達十個資料來源。 下列範例會選取`amazon_vpc.flow`資料來源。 ``` SOURCE dataSource(['amazon_vpc.flow']) ``` 下列範例會選取`amazon_vpc.flow`資料來源，並根據日誌群組名稱字首來限制日誌群組。 ``` SOURCE dataSource(['amazon_vpc.flow']) logGroups(namePrefix: ['namePrefix1']) ``` # pattern 使用 `pattern` 自動將您的日誌資料叢集化，以形成模式。 模式是指日誌欄位之間反覆出現的共同文字結構。您可以使用 `pattern` 來顯示新興趨勢、監控已知錯誤，以及識別經常發生或高成本的日誌行。CloudWatch Logs Insights 也提供主控台體驗，您可以用來尋找並進一步分析日誌事件中的模式。如需詳細資訊，請參閱[模式分析](CWL_AnalyzeLogData_Patterns.md)。 由於 `pattern`命令會自動識別常見模式，因此您可以使用它做為搜尋和分析日誌的起點。您也可以將 `pattern` 與 ` filter`、` parse` 或 ` sort` 命令搭配使用，在更多經過微調的查詢中識別模式。 **模式命令輸入** `pattern` 命令需有以下任何一項輸入：`@message` 欄位、以 ` parse` 命令建立的擷取欄位，或使用一或多個[字串函數](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html#CWL_QuerySyntax-string-functions)操控的字串。 如果 CloudWatch Logs 無法推斷動態權杖所代表的資料類型， 會顯示為 ，而*數字*指出此權杖相較於其他動態權杖，出現在模式中的位置。 動態字符的常見範例包括錯誤代碼、IP 地址、時間戳記和請求 IDs。 **模式命令輸出** `pattern` 命令會產生以下輸出： + `@pattern`：日誌事件欄位之間反覆出現的共同文字結構。模式內不同的欄位，例如請求 ID 或時間戳記，會以*字符*表示。如果 CloudWatch Logs 可以判斷動態字符代表的資料類型，則會將字符顯示為 ``。*字串*是字符所代表資料類型的描述。相較於其他動態字符，*數字*會顯示此字符在模式中的顯示位置。 CloudWatch Logs 會根據分析包含該名稱的日誌事件內容來指派名稱的字串部分。 如果 CloudWatch Logs 無法推斷動態權杖所代表的資料類型， 會顯示為 ，而*數字*指出此權杖相較於其他動態權杖，在模式中顯示的位置。 例如，`[INFO] Request time: ms` 是日誌訊息 `[INFO] Request time: 327 ms` 可能的輸出。 + `@ratio`：所選期間和指定日誌群組中，符合已識別模式的日誌事件比例。例如，如果選取的日誌群組和期間中有一半的日誌事件符合模式，`@ratio` 就會傳回 `0.50` + `@sampleCount`：所選期間和指定日誌群組中，符合已識別模式的日誌事件數量。 + `@severityLabel`：日誌嚴重性或層級，指明日誌中的資訊類型，例如 `Error`、`Warning`、`Info` 或 `Debug`。 **範例** 以下命令會識別所選時間範圍內指定日誌群組中具有類似結構的日誌，並依模式和數量將其分組 ``` pattern @message ``` `pattern` 命令可以與 ` filter` 命令搭配使用 ``` filter @message like /ERROR/ | pattern @message ``` `pattern` 命令可與 ` parse` 和 ` sort` 命令搭配使用 ``` filter @message like /ERROR/ | parse @message 'Failed to do: *' as cause | pattern cause | sort @sampleCount asc ``` # 差異 將請求時段中找到的日誌事件與先前相同長度時段的日誌事件進行比較。如此一來，您可以尋找趨勢，並找出特定日誌事件是否為新的。 將修飾詞新增至`diff`命令，以指定您要與之比較的時段： + `diff` 會將目前選取時間範圍中的日誌事件與前一個時間範圍的日誌事件進行比較。 + `diff previousDay` 會將目前選取時間範圍中的日誌事件與前一天同一時間的日誌事件進行比較。 + `diff previousWeek` 會將目前選取時間範圍中的日誌事件與上週同一時間的日誌事件進行比較。 + `diff previousMonth` 會將目前選取時間範圍中的日誌事件與上個月相同時間的日誌事件進行比較。 如需詳細資訊，請參閱[比較 （差異） 與先前的時間範圍](CWL_AnalyzeLogData_Compare.md)。 # parse 使用 `parse` 從日誌欄位擷取資料，並建立一個您可在查詢中處理的擷取欄位。**`parse`** 支援使用萬用字元的 glob 模式和規則運算式。如需規則表達式語法的資訊，請參閱 [支援的規則運算式 (regex) 語法](FilterAndPatternSyntax.md#regex-expressions)。 您可以使用規則表達式剖析巢狀 JSON 欄位。 **範例：剖析巢狀 JSON 欄位** 程式碼片段會示範如何剖析在擷取期間已扁平化的 JSON 日誌事件。 ``` {'fieldsA': 'logs', 'fieldsB': [{'fA': 'a1'}, {'fA': 'a2'}]} ``` 程式碼片段會顯示一個具有規則運算式的查詢，其會擷取 `fieldsA` 和 `fieldsB` 的值，以建立擷取欄位 `fld` 和 `array`。 ``` parse @message "'fieldsA': '*', 'fieldsB': ['*']" as fld, array ``` **具名擷取群組** 當您將 **`parse`** 與正規表達式搭配使用時，您可以使用具名擷取群組將模式擷取到欄位中。語法是 `parse @message (?pattern)`。 以下範例在 VPC 流量日誌上使用擷取群組，將 ENI 擷取到名為 `NetworkInterface` 的欄位中。 ``` parse @message /(?eni-.*?) / | display NetworkInterface, @message ``` **注意** JSON 日誌事件會在擷取期間扁平化。目前不支援剖析具有 glob 表達式的巢狀 JSON 欄位。您只能剖析包含不超過 200 個日誌事件欄位的 JSON 日誌事件。剖析巢狀 JSON 欄位時，您必須格式化查詢中的規則表達式，以符合 JSON 日誌事件的格式。 ## 剖析命令的範例 **使用 glob 運算式，從日誌欄位 `@message` 中擷取欄位 `@user`、`@method` 和 `@latency`，並傳回 `@method` 和 `@user` 各種不重複組合的平均延遲。** ``` parse @message "user=*, method:*, latency := *" as @user, @method, @latency | stats avg(@latency) by @method, @user ``` **使用規則運算式，從日誌欄位 `@message` 中擷取欄位 `@user2`、`@method2` 和 `@latency2`，並傳回 `@method2` 和 `@user2` 各種不重複組合的平均延遲。** ``` parse @message /user=(?.*?), method:(?.*?), latency := (?.*?)/ | stats avg(latency2) by @method2, @user2 ``` **擷取欄位 `loggingTime`、`loggingType` 和 `loggingMessage`，並篩選包含 `ERROR` 或 `INFO` 字串的日誌事件，然後針對包含 `ERROR` 字串的事件，僅顯示 `loggingMessage` 和 `loggingType` 欄位。** ``` FIELDS @message | PARSE @message "* [*] *" as loggingTime, loggingType, loggingMessage | FILTER loggingType IN ["ERROR", "INFO"] | DISPLAY loggingMessage, loggingType = "ERROR" as isError ``` # sort 使用 `sort` 按指定欄位以遞增 (`asc`) 或遞減 (`desc`) 順序顯示日誌事件。您可以搭配使用 `limit` 命令來建立「前 N 個」或「底部 N 個」查詢。 排序演算法是自然排序的更新版本。如果您以遞增順序排序，則會使用下列邏輯。 + 所有非數值都先於所有數值。*數值*是僅包含數字的值，而不是數字和其他字元的組合。 + 對於非數值，演算法會將連續的數值字元和連續的字母字元分組為不同的區塊以供比較。它會依其 Unicode 值排序非數值部分，然後依其長度排序數值部分，再依其數值排序。 如需 Unicode 順序的詳細資訊，請參閱 [Unicode 字元清單](https://en.wikipedia.org/wiki/List_of_Unicode_characters)。 例如，以下是依遞增順序排序的結果。 ``` !: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> sorted by unicode order # *%04 0# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Alphanumeric starting with numbers 5A 111A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Starts with more digits than 5A, so it sorted to be later than 5A 2345_ @ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2345 is compared with @ in the unicode order, @_ A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Values starting with letters A9876fghj a12345hfh 0 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Number values 01 1 2 3 ``` 如果您以遞減順序排序，排序結果會相反。 例如，下列 Amazon VPC 流程日誌的查詢會找出跨主機的前 15 個封包傳輸。 ``` stats sum(packets) as packetsTransferred by srcAddr, dstAddr | sort packetsTransferred desc | limit 15 ``` # 統計資料 使用 `stats` 建立日誌資料的視覺化效果，例如長條圖、折線圖和堆疊區域圖。這可協助您更有效地識別日誌資料中的模式。CloudWatch Logs Insights 可以為使用 `stats` 函數和一或多個彙總函數的查詢產生視覺效果。 例如，Route 53 日誌群組中的下列查詢會傳回視覺化效果，依查詢類型顯示每小時 Route 53 記錄的分佈情況。 ``` stats count(*) by queryType, bin(1h) ``` 所有這些查詢都可以產生長條圖。如果您的查詢使用 `bin()` 函式將資料以一個欄位與一段時間進行群組，那麼您也可以看到折線圖和堆疊區域圖。 `bin` 函數支援以下時間單位和縮寫。對於包含多個字元的所有單位和縮寫，支援加上 s 來表示複數。所以 `hr` 和 `hrs` 皆可用來指定時數。 + `millisecond` `ms` `msec` + `second` `s` `sec` + `minute` `m` `min` + `hour` `h` `hr` + `day` `d` + `week` `w` + `month` `mo` `mon` + `quarter` `q` `qtr` + `year` `y` `yr` **Topics** + [視覺化呈現時間序列資料](#CWL_Insights-Visualizing-TimeSeries) + [視覺化呈現依欄位分組的日誌資料](#CWL_Insights-Visualizing-ByFields) + [在單一查詢中使用多個統計資訊命令](#CWL_QuerySyntax-stats-multi) + [與統計資料搭配使用的函數](#CWL_QuerySyntax-stats-functions) ## 視覺化呈現時間序列資料 時間序列視覺化適用於具有下列特性的查詢： + 查詢包含一或多個彙總函數。如需詳細資訊，請參閱[Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions)。 + 查詢使用 `bin()` 函數依一個欄位來分組資料。 這些查詢可以產生折線圖、堆疊區域圖、長條圖和圓餅圖。 **範例** 如需完整的教學，請參閱[教學課程：執行查詢來產生時間序列視覺化](CWL_AnalyzeLogData_VisualizationQuery.md)。 以下是更多適用於時間序列視覺化的查詢範例。 以下查詢為 `myfield1` 欄位的平均值產生視覺效果，其中每 5 分鐘建立一個資料點。每個資料點是日誌中前五分鐘的 `myfield1` 值的平均值彙總。 ``` stats avg(myfield1) by bin(5m) ``` 以下查詢根據不同欄位建立三個值的視覺效果，其中每 5 分鐘建立一個資料點。產生此覺化是因為查詢包含彙總函數，且使用 `bin()` 做為分組欄位。 ``` stats avg(myfield1), min(myfield2), max(myfield3) by bin(5m) ``` **折線圖和堆疊區域圖限制** 彙總記錄項目資訊但不使用 `bin()` 函數的查詢可產生長條圖。不過，該查詢無法產生折線圖或堆疊區域圖。如需這些查詢類型的詳細資訊，請參閱 [視覺化呈現依欄位分組的日誌資料](#CWL_Insights-Visualizing-ByFields)。 ## 視覺化呈現依欄位分組的日誌資料 您可以為使用 `stats` 函數和一或多個彙總函數的查詢產生長條圖。如需詳細資訊，請參閱[Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions)。 若要查看視覺化，請執行查詢。查詢 **Visualization (視覺化)** 標籤，選取 **Line (線條)** 旁邊的箭頭，然後選擇 **Bar (長條)**。長條圖中的視覺化限制為最多 100 個長條。 **範例** 如需完整的教學，請參閱[教學課程：執行查詢以產生依日誌欄位分組的視覺效果](CWL_AnalyzeLogData_VisualizationFieldQuery.md)。以下段落包含更多可依據欄位進行視覺化的查詢範例。 下列 VPC 流程日誌查詢會尋找每個目的地位址、每個工作階段傳輸的平均位元組數。 ``` stats avg(bytes) by dstAddr ``` 您也可以產生一個圖表，其中包含每個結果值的多個長條。例如，下列 VPC 流程日誌查詢會尋找每個目的地位址、每個工作階段傳輸的平均和最大位元組數。 ``` stats avg(bytes), max(bytes) by dstAddr ``` 下列查詢會尋找每個查詢類型的 Amazon Route 53 查詢日誌數量。 ``` stats count(*) by queryType ``` ## 在單一查詢中使用多個統計資訊命令 您可以在單一查詢中使用多達兩個 `stats` 命令。這讓能您在第一個彙總的輸出上執行額外的彙總。 **範例：使用兩個 `stats` 命令進行查詢** 例如，以下查詢會先找出 5 分鐘區間的總流量，然後計算這些 5 分鐘區間的最高、最低和平均流量。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length)/1024/1024 as logs_mb BY bin(5m) | STATS max(logs_mb) AS peak_ingest_mb, min(logs_mb) AS min_ingest_mb, avg(logs_mb) AS avg_ingest_mb ``` **範例：將多個統計資料命令與其他函數 (例如 `filter`、`fields`、`bin`) 相結合** 您可以在單一命令中，將兩個 `stats` 命令與其他命令（例如 `filter` 和 `fields`) 相結合。例如，以下查詢會尋找工作階段中不同 IP 地址的數目，並依用戶端平台尋找工作階段數目，篩選這些 IP 地址，最後再找出每個用戶端平台的工作階段請求的平均數。 ``` STATS count_distinct(client_ip) AS session_ips, count(*) AS requests BY session_id, client_platform | FILTER session_ips > 1 | STATS count(*) AS multiple_ip_sessions, sum(requests) / count(*) AS avg_session_requests BY client_platform ``` 您可以在具有多個 `stats` 命令的查詢中使用 `bin` 和 `dateceil` 函數。例如，以下查詢會先將訊息合併成 5 分鐘的區塊，然後將這些 5 分鐘的區塊彙總為 10 分鐘的區塊，並計算每個 10 分鐘區塊內的最高、最低和平均流量。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) / 1024 / 1024 AS logs_mb BY BIN(5m) as @t | STATS max(logs_mb) AS peak_ingest_mb, min(logs_mb) AS min_ingest_mb, avg(logs_mb) AS avg_ingest_mb BY dateceil(@t, 10m) ``` **備註與限制** 查詢最多可以有兩個 `stats` 命令。此配額無法變更。 如果您使用一個 `sort` 或 `limit` 命令，則其必須出現在第二個 `stats` 命令之後。如果在第二個 `stats` 命令之前，查詢無效。 當查詢有兩個 `stats` 命令時，在第一個 `stats` 彙總完成之前，不會開始顯示查詢的部分結果。 在單一查詢的第二個 `stats` 命令中，您只能參照第一個 `stats` 命令中定義的欄位。例如，以下查詢無效，因為 `@message` 欄位要在第一次 `stats` 彙總之後才可以使用。 ``` FIELDS @message | STATS SUM(Fault) by Operation # You can only reference `SUM(Fault)` or Operation at this point | STATS MAX(strlen(@message)) AS MaxMessageSize # Invalid reference to @message ``` 您在第一個 `stats` 命令之後參照的任何欄位，都必須在該第一個 `stats` 命令中定義。 ``` STATS sum(x) as sum_x by y, z | STATS max(sum_x) as max_x by z # You can only reference `max(sum_x)`, max_x or z at this point ``` **重要** `bin` 函數始終以隱含的方式使用 `@timestamp` 欄位。這表示如果不使用第一個 `stats` 命令傳播 `timestamp` 欄位，就無法在第二個 `stats` 命令中使用 `bin`。例如，以下查詢無效。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) AS ingested_bytes BY @logStream | STATS avg(ingested_bytes) BY bin(5m) # Invalid reference to @timestamp field ``` 因此，應在第一個 `stats` 命令中定義 `@timestamp` 欄位，然後就可以在第二個 `stats` 命令中用來與 `dateceil` 搭配使用，如以下範例所示。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) AS ingested_bytes, max(@timestamp) as @t BY @logStream | STATS avg(ingested_bytes) BY dateceil(@t, 5m) ``` ## 與統計資料搭配使用的函數 CloudWatch Logs Insights 支援統計資料彙總函數和統計資料非彙總函數。 在 `stats` 命令中使用統計資料彙總函數，並用作其他函數的引數。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `avg(fieldName: NumericLogField)` | number | 所指定欄位中的值的平均數。 | | `count()` `count(fieldName: LogField)` | number | 計算日誌事件數。`count()` (或 `count(*)`) 計算查詢傳回的所有事件數，`count(fieldName)` 計算包含指定欄位名稱的所有記錄數。 | | `count_distinct(fieldName: LogField)` | number | 傳回欄位的唯一值數目。如果欄位有極高的基數 (包含許多唯一值)，則 `count_distinct` 傳回的值只是近似值。 | | `max(fieldName: LogField)` | LogFieldValue | 在所查詢的日誌中此日誌欄位的值上限。 | | `min(fieldName: LogField)` | LogFieldValue | 在所查詢的日誌中此日誌欄位的值下限。 | | `pct(fieldName: LogFieldValue, percent: number)` | LogFieldValue | 百分位數會指出資料集中相關準備好的值。例如，`pct(@duration, 95)` 傳回 `@duration` 值，其中 `@duration` 的值有 95% 低於這個值，有 5% 高於這個值。 | | `stddev(fieldName: NumericLogField)` | number | 所指定欄位中的值的標準差。 | | `sum(fieldName: NumericLogField)` | number | 所指定欄位中的值的總和。 | **Stats 非彙總函數** 非彙總函數可用於 `stats` 命令，也可以作為其他函數的引數使用。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `earliest(fieldName: LogField)` | LogField | 從在查詢日誌中具有最早時間戳記的日誌事件中傳回 `fieldName` 的值。 | | `latest(fieldName: LogField)` | LogField | 從在查詢日誌中具有最晚時間戳記的日誌事件中傳回 `fieldName` 的值。 | | `sortsFirst(fieldName: LogField)` | LogField | 傳回在查詢日誌中最先排序的 `fieldName` 值。 | | `sortsLast(fieldName: LogField)` | LogField | 傳回在查詢日誌中最後排序的 `fieldName` 值。 | # limit 使用 `limit` 指定您希望查詢傳回的日誌事件數目。如果您省略 `limit`，查詢會在結果中傳回多達 10，000 個日誌事件。 例如，下列範例僅傳回 25 個最新的日誌事件。 ``` fields @timestamp, @message | sort @timestamp desc | limit 25 ``` # dedup 使用 `dedup` 根據指定欄位中的特定值移除重複的結果。可以將 `dedup` 與一個或多個欄位搭配使用。如果對 `dedup` 指定一個欄位，則只會針對該欄位的每個唯一值傳回一個日誌事件。如果指定多個欄位，則會針對這些欄位的每個唯一值組合傳回一個日誌事件。 系統會根據排序順序捨棄重複項目，只會保留排序順序中的第一個結果。建議您先對結果進行排序，然後再透過 `dedup` 命令進行排序。如果在透過 `dedup` 執行之前未對結果進行排序，則會採用使用 `@timestamp` 的預設遞減排序順序。 Null 值不會被視為評估的重複項目。系統會保留任何指定欄位之具有 Null 值的日誌事件。要消除具有 null 值的字段，請採用使用 `isPresent(field)` 函數的 **`filter`**。 可以在 `dedup` 命令之後的查詢中使用的唯一查詢命令為 `limit`。 當您在查詢`dedup`中使用 時，主控台會顯示訊息，例如**顯示 Y 記錄的 X**，其中 X 是重複資料刪除的結果數目，Y 是重複資料刪除之前符合的記錄總數。這表示重複的記錄已移除，並不表示資料遺失。 **範例：僅查看名為 `server` 之欄位的每個唯一值的最近日誌事件** 下列範例顯示 `server` 的每個唯一值的最近事件的 `timestamp`、`server`、`severity` 和 `message` 欄位。 ``` fields @timestamp, server, severity, message | sort @timestamp desc | dedup server ``` 如需 CloudWatch Logs Insights 查詢的更多範例，請參閱 [一般查詢](CWL_QuerySyntax-examples.md#CWL_QuerySyntax-examples-general)。 # unmask 使用 `unmask` 可以顯示因為資料保護政策而遮罩某些內容的某個日誌事件的全部內容。若要使用此命令，您必須擁有 `logs:Unmask` 許可。 如需有關日誌群組中資料保護的詳細資訊，請參閱 [使用遮罩功能協助保護敏感日誌資料](mask-sensitive-log-data.md)。 # 解巢狀 使用 `unnest`將做為輸入的清單扁平化，為清單中的每個元素產生具有單一記錄的多個記錄。根據欄位包含的項目數量，此命令會捨棄目前的記錄並產生新的記錄。每個記錄都包含 `unnested_field`，代表一個項目。所有其他欄位都來自原始記錄。 的輸入`unnest`是 `LIST`，其來自 `jsonParse`函數。如需詳細資訊，請參閱[結構類型](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html#CWL_QuerySyntax-structure-types)。任何其他類型，例如 `MAP``String`和 `numbers`，都會被視為清單中有一個項目`unnest`。 **命令結構** 下列範例說明此命令的格式。 ``` unnest field into unnested_field ``` **查詢範例** 下列範例剖析 JSON 物件字串並展開欄位事件清單。 ``` fields jsonParse(@message) as json_message | unnest json_message.events into event | display event.name ``` 此範例查詢的日誌事件可以是 JSON 字串，如下所示： ``` { "events": [ { "name": "exception" }, { "name": "user action" } ] } ``` 在此情況下，範例查詢會在查詢結果中產生兩個記錄，一個為 `event.name`，`exception`另一個為 `event.name`作為**使用者動作** **查詢範例** 下列範例會扁平化清單，然後篩選出項目。 ``` fields jsonParse(@message) as js | unnest js.accounts into account | filter account.type = "internal" ``` **查詢範例** 下列範例會扁平化要彙總的清單。 ``` fields jsonParse(trimmedData) as accounts | unnest accounts into account | stats sum(account.droppedSpans) as n by account.accountId | sort n desc | limit 10 ``` # 查詢 使用 `lookup` 以查詢資料表中的參考資料豐富查詢結果。查詢資料表包含您上傳至 Amazon CloudWatch Logs 的 CSV 資料。查詢執行時，`lookup`命令會將日誌事件中的欄位與查詢資料表中的欄位相符，並將指定的輸出欄位附加至結果。 針對資料擴充案例使用查詢表，例如將使用者 IDs映射至使用者詳細資訊、將產品代碼映射至產品資訊，或將錯誤代碼映射至錯誤描述。 ## 建立和管理查詢資料表 您必須先建立查詢資料表，才能在查詢中使用 `lookup`命令。您可以從 CloudWatch 主控台或使用 Amazon CloudWatch Logs API 建立和管理查詢資料表。 **建立查詢資料表 （主控台）** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**設定**，然後選擇**日誌**索引標籤。 1. 捲動至**查詢資料表**，然後選擇**管理**。 1. 選擇**建立查詢資料表**。 1. 輸入查詢資料表的名稱。名稱只能包含英數字元、連字號和底線。 1. (選用) 輸入描述。 1. 上傳 CSV 檔案。檔案必須包含具有資料欄名稱的標頭列、使用 UTF-8 編碼，且不得超過 10 MB。 1. （選用） 指定要加密資料表資料的 AWS KMS 金鑰。 1. 選擇**建立**。 建立查詢資料表後，您可以在 CloudWatch Logs Insights 查詢編輯器中檢視它。選擇**查詢資料表**索引標籤來瀏覽可用的資料表及其欄位。 若要更新查詢資料表，請選取資料表，然後選擇**動作**、**更新**。上傳新的 CSV 檔案以取代所有現有的內容。若要刪除查詢資料表，請選擇**動作**、**刪除**。 **注意** 每個 每個帳戶最多可以建立 100 個查詢資料表 AWS 區域。CSV 檔案最多可達 10 MB。您也可以使用 Amazon CloudWatch Logs API 管理查詢資料表。如需詳細資訊，請參閱《*Amazon CloudWatch Logs API 參考*》中的 [CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)。 **注意** 如果查詢表使用 KMS 金鑰加密，呼叫者必須擁有金鑰 （用於加密查詢表的 KMS 金鑰） 的`kms:Decrypt`許可，才能搭配參考該查詢表的查詢使用 `StartQuery` API。如需詳細資訊，請參閱[使用 加密 CloudWatch Logs 中的查詢資料表 AWS Key Management Service](encrypt-lookup-tables-kms.md)。 ## 查詢查詢語法 **命令結構** 以下顯示此命令的格式。 ``` lookup table lookup-field as log-field [,...] output-mode output-field[,...] ``` 命令使用下列引數： + `table` – 要使用的查詢資料表名稱。 + `lookup-field` – 查詢資料表中要比對的欄位。 + `log-field` – 日誌事件中要比對的欄位。相符項目完全且區分大小寫。 + `output-mode` – 指定 `OUTPUT`將輸出欄位新增至結果。如果日誌事件中已存在同名的欄位，則會予以覆寫。 + `output-field` – 要新增至結果的查詢資料表中的一個或多個欄位。 **範例：使用使用者詳細資訊來豐富日誌事件** 假設您有一個包含 `id` 欄位的事件日誌群組，以及名為 的查詢資料表`user_data`，其中包含欄 `id`、`name`、 `email`和 `department`。下列查詢會使用查詢表中的使用者名稱、電子郵件和部門來豐富每個日誌事件。 ``` fields action, status, name, email, department | lookup user_data id OUTPUT name, email, department ``` **範例：搭配彙總使用查詢** 您可以搭配彙總函數使用查詢輸出欄位。下列查詢會使用使用者詳細資訊豐富日誌事件，然後計算依電子郵件地址分組的事件。 ``` fields user_id, action, username, email, department | lookup user_data user_id OUTPUT username, email, department | stats count(*) by email ``` **範例：搭配篩選條件使用查詢** 您可以根據查詢傳回的欄位來篩選結果。下列查詢會擴充日誌事件，然後篩選以僅顯示特定部門的事件。 ``` fields user_id, action | lookup user_data user_id OUTPUT username, email, department | filter department = "Engineering" ``` # 布林值、比較、數值、日期時間和其他函數 CloudWatch Logs Insights 支援查詢中的許多其他操作和函數，如以下各節所述。 **Topics** + [算術運算子](#CWL_QuerySyntax-operations-arithmetic) + [布林值運算子](#CWL_QuerySyntax-operations-Boolean) + [比較運算子](#CWL_QuerySyntax-operations-comparison) + [數值運算子](#CWL_QuerySyntax-operations-numeric) + [結構類型](#CWL_QuerySyntax-structure-types) + [日期時間函數](#CWL_QuerySyntax-datetime) + [一般函數](#CWL_QuerySyntax-general-functions) + [JSON 函數](#CWL_QuerySyntax-json-functions) + [IP 地址字串函數](#CWL_QuerySyntax-IPaddress-functions) + [字串函數](#CWL_QuerySyntax-string-functions) ## 算術運算子 算術運算子可接受以數值資料類型作為引數，而且會傳回數值結果。算術運算子可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。 | 作業 | Description | | --- | --- | | `a + b` | 加法 | | `a - b` | 減法 | | `a * b` | 乘法 | | `a / b` | 除法 | | `a ^ b` | 指數 (`2 ^ 3` 傳回 `8`) | | `a % b` | 餘數或模數 (`10 % 3` 傳回 `1`) | ## 布林值運算子 使用布林值運算子 `and`、`or` 和 `not`。 **注意** 布林值運算子僅限用於會傳回 **TRUE** 或 **FALSE** 的函數。 ## 比較運算子 比較運算子可接受以所有資料類型作為引數，而且會傳回布林值結果。比較運算子可用於 `filter` 命令，也可以作為其他函數的引數使用。 | 運算子 | Description | | --- | --- | | `=` | 等於 | | `!=` | 不等於 | | `<` | Less than | | `>` | Greater than | | `<=` | 小於或等於 | | `>=` | 大於或等於 | ## 數值運算子 數值運算接受數值資料類型作為引數，並傳回數值結果。數值運算可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。 | 作業 | 結果類型 | Description | | --- | --- | --- | | `abs(a: number)` | number | 絕對值 | | `ceil(a: number)` | number | 無條件進位到上限 (大於 `a` 值的最小整數) | | `floor(a: number)` | number | 無條件捨去到下限 (小於 `a` 值的最大整數) | | `greatest(a: number, ...numbers: number[])` | number | 傳回最大值 | | `least(a: number, ...numbers: number[])` | number | 傳回最小值 | | `log(a: number)` | number | 自然對數 | | `sqrt(a: number)` | number | 平方根 | ## 結構類型 地圖或清單是 CloudWatch Logs Insights 中的結構類型，可讓您存取和使用查詢的屬性。 **範例：取得地圖或清單** 使用 `jsonParse`將 json 字串的欄位剖析為映射或清單。 ``` fields jsonParse(@message) as json_message ``` **範例：存取屬性** 使用點存取運算子 (map.attribute) 來存取映射中的項目。如果地圖中的屬性包含特殊字元，請使用反引號括住屬性名稱 (map.attributes.`special.char`)。 ``` fields jsonParse(@message) as json_message | stats count() by json_message.status_code ``` 使用括號存取運算子 (list【index】) 擷取清單中特定位置的項目。 ``` fields jsonParse(@message) as json_message | filter json_message.users[1].action = "PutData" ``` 當金鑰名稱中存在特殊字元時，以反引號 (``) 包裝特殊字元。 ``` fields jsonParse(@message) as json_message | filter json_message.`user.id` = "123" ``` **範例：空的結果** 地圖和清單會被視為字串、數字和日期時間函數的 null。 ``` fields jsonParse(@message) as json_message | display toupper(json_message) ``` 比較映射和清單到任何其他欄位會導致 `false`。 **注意** `stats` 不支援在 `dedup`、`sort`、 和 `pattern`中使用地圖和清單。 ## 日期時間函數 **日期時間函數** 日期時間函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。如果查詢中使用了彙總函數，您可以使用這些函數來建立時段。使用由數字和下列其中一項組成的時段： + `ms` 毫秒 + `s` 持續 秒 + `m` 持續 分鐘 + `h` 小時 例如，`10m` 是 10 分鐘，`1h` 是 1 小時。 **注意** 為您的日期時間函數使用最適當的時間單位。CloudWatch Logs 會根據您選擇的時間單位來限制您的請求。例如，它以 60 為上限，作為使用 的任何請求的最大值`s`。因此，如果您指定 `bin(300s)`，CloudWatch Logs 實際上會將其實作為 60 秒，因為 60 是一分鐘的秒數，因此 CloudWatch Logs 不會搭配 使用高於 60 的數字`s`。若要建立 5 分鐘的儲存貯體，請`bin(5m)`改用 。 的上限為 `ms` 1000、 `s`和 的上限為 `m` 60，而 的上限為 `h` 24。 下表列出您可以在查詢命令中使用的不同日期時間函數。該表列出了每個函式的結果類型，並包含對每個函式的說明。 **提示** 建立查詢命令時，您可以使用時間間隔選擇器，來選取您要查詢的時間段。例如：您可以設定 5 分鐘到 30 分鐘的間隔；1 小時、3 小時和 12 小時的間隔；或是自訂的時間範圍。您也可以在特定日期之間設定時間段。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `bin(period: Period)` | 時間戳記 | 將 `@timestamp` 的值四捨五入到指定時間段，然後截斷。例如，`bin(5m)` 將 `@timestamp` 的值四捨五入至最接近的 5 分鐘。 您可以使用此操作在查詢中將多筆日誌條目分組在一起。以下範例傳回每小時的例外情況計數。 
filter @message like /Exception/ 
    | stats count(*) as exceptionCount by bin(1h)
    | sort exceptionCount desc
`bin` 函數支援以下時間單位和縮寫。對於包含多個字元的所有單位和縮寫，支援加上 s 來表示複數。所以 `hr` 和 `hrs` 皆可用來指定時數。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html) | | `datefloor(timestamp: Timestamp, period: Period)` | 時間戳記 | 將時間戳記截斷為指定的期間。例如，`datefloor(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為半點小時。 | | `dateceil(timestamp: Timestamp, period: Period)` | 時間戳記 | 將時間戳記無條件進位到指定期間，然後截斷。例如，`dateceil(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為整點小時。 | | `fromMillis(fieldName: number)` | 時間戳記 | 解譯輸入欄位為自 Unix epoch 以來的毫秒數，並將其轉換為時間戳記。 | | `toMillis(fieldName: Timestamp)` | number | 將指定欄位中找到的時間戳記轉換為數字，代表自 Unix epoch 以來的毫秒數。例如：`toMillis(@timestamp)` 會將時間戳記 `2022-01-14T13:18:031.000-08:00` 轉換為 `1642195111000`。 | | `now()` | number | 以 epoch 秒為單位，傳回查詢處理開始的時間。此函數不採用引數。 您可以使用此值，根據目前時間篩選查詢結果。 例如，下列查詢會傳回過去兩個小時內所有 4xx 個錯誤： 
parse @message "Status Code: *;" as statusCode\n 
| filter statusCode >= 400 and statusCode <= 499  \n 
| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)
下列範例會傳回過去五小時內包含單字 `error`或 的所有日誌項目 `failure` 
fields @timestamp, @message 
| filter @message like /(?i)(error|failure)/ 
| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)
| **注意** 目前 CloudWatch Logs Insights 不支援使用人類可讀時間戳記篩選日誌。 ## 一般函數 **一般函數** 一般函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `ispresent(fieldName: LogField)` | Boolean | 如果欄位存在，傳回 `true` | | `coalesce(fieldName: LogField, ...fieldNames: LogField[])` | LogField | 傳回清單中的第一個非空值 | ## JSON 函數 **JSON 函數** 在 `fields`和 `filter`命令中使用 JSON 函數，並做為其他函數的引數。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `jsonParse(fieldName: string)` | 映射 \$1 清單 \$1 空白 | 當輸入是 JSON 物件或 JSON 陣列的字串表示法時，傳回映射或清單。如果輸入不是其中一個表示法，則傳回空值。 | | `jsonStringify(fieldName: Map \| List)` | String | 從映射或清單資料傳回 JSON 字串。 | ## IP 地址字串函數 **IP 地址字串函數** IP 地址字串函數可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `isValidIp(fieldName: string)` | boolean | 如果欄位是有效的 IPv4 或 IPv6 地址，則會傳回 `true`。 | | `isValidIpV4(fieldName: string)` | boolean | 如果欄位是有效的 IPv4 地址，則傳回 `true`。 | | `isValidIpV6(fieldName: string)` | boolean | 如果欄位是有效的 IPv6 地址，則傳回 `true`。 | | `isIpInSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v4 或 v6 子網路內的有效 IPv4 或 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24` 或 `2001:db8::/32`，其中 `192.0.2.0` 或 `2001:db8::` 是 CIDR 區塊的起始位置。 | | `isIpv4InSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v4 子網路內的有效 IPv4 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24`，其中 `192.0.2.0` 是 CIDR 區塊的起始位置。 | | `isIpv6InSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v6 子網路內的有效 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `2001:db8::/32`，其中 `2001:db8::` 是 CIDR 區塊的起始位置。 | ## 字串函數 **字串函數** 字串函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。 | 函式 | 結果類型 | Description | | --- | --- | --- | | `isempty(fieldName: string)` | Number | 如果欄位遺失或是空白字串，傳回 `1`。 | | `isblank(fieldName: string)` | Number | 如果欄位遺失、是空白字串或只包含空格，傳回 `1`。 | | `concat(str: string, ...strings: string[])` | string | 串連字串。 | | `ltrim(str: string)` `ltrim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串左側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 左側移除 `trimChars` 中的字元。例如，`ltrim("xyZxyfooxyZ","xyZ")` 傳回 `"fooxyZ"`。 | | `rtrim(str: string)` `rtrim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串右側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 右側移除 `trimChars` 的字元。例如，`rtrim("xyZfooxyxyZ","xyZ")` 傳回 `"xyZfoo"`。 | | `trim(str: string)` `trim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串兩側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 兩側移除 `trimChars` 的字元。例如，`trim("xyZxyfooxyxyZ","xyZ")` 傳回 `"foo"`。 | | `strlen(str: string)` | number | 以 Unicode 字碼指標傳回字串的長度。 | | `toupper(str: string)` | string | 將字串轉換成大寫。 | | `tolower(str: string)` | string | 將字串轉換成小寫。 | | `substr(str: string, startIndex: number)` `substr(str: string, startIndex: number, length: number)` | string | 傳回從數字引數指定的索引到字串結尾的子字串。如果函數有第二個數字引數，則是包含要擷取的子字串長度。例如，`substr("xyZfooxyZ",3, 3)` 傳回 `"foo"`。 | | `replace(fieldName: string, searchValue: string, replaceValue: string)` | string | 以 `replaceValue` 取代 `fieldName: string` 中出現的所有 `searchValue`。 例如：函式 `replace(logGroup,"smoke_test","Smoke")` 搜尋欄位 `logGroup` 中包含字串值 `smoke_test` 的日誌事件，並將值替換為字串 `Smoke`。 | | `strcontains(str: string, searchValue: string)` | number | 如果 `str` 包含 `searchValue`，則傳回 1，否則傳回 0。 | # 包含特殊字元的欄位 如果欄位包含`@`符號或句點 (`.`) 以外的非英數字元，您必須以反引號字元 () 括住欄位```。例如：日誌欄位 `foo-bar` 含有非英數字元，亦即連字號 (`-`)，因此必須置於反引號 (``foo-bar``) 之間。 # 在查詢中使用別名和註解 建立含有別名的查詢。將日誌欄位重新命名，或在擷取值並填入欄位時，都可使用別名。使用關鍵字 `as` 為日誌欄位或結果賦予別名。您可以在查詢中使用多個別名。您可以在下列任一命令中使用別名： + `fields` + `parse` + `sort` + ` stats ` 以下範例會示範如何建立含有別名的查詢。 **範例** 查詢的 `fields` 命令中含有別名。 ``` fields @timestamp, @message, accountId as ID | sort @timestamp desc | limit 20 ``` 查詢會傳回欄位 `@timestamp`、`@message` 和 `accountId` 的值。結果以遞減方式排序，且限制為 20。`accountId` 的值會顯示於別名 `ID` 底下。 **範例** 查詢的 `sort` 和 `stats` 命令中含有別名。 ``` stats count(*) by duration as time | sort time desc ``` 查詢會計算欄位 `duration` 出現於日誌群組中的次數，並以遞減方式將結果排序。`duration` 的值會顯示於別名 `time` 底下。 ## 使用註解 CloudWatch Logs Insights 支援在查詢中使用註解。使用雜湊字元 (**\$1**) 作為註解的開頭。您可以使用註解，忽略查詢或文件查詢中的行。 **範例：查詢** 以下查詢運行時，系統會忽略第二行。 ``` fields @timestamp, @message, accountId # | filter accountId not like "7983124201998" | sort @timestamp desc | limit 20 ``` # Logs Insights QL 入門：查詢教學課程 下列各節包含範例查詢教學課程，協助您開始使用 Logs Insights QL。 **Topics** + [教學課程：執行和修改範例查詢](CWL_AnalyzeLogData_RunSampleQuery.md) + [教學課程：使用彙總函數執行查詢](CWL_AnalyzeLogData_AggregationQuery.md) + [教學課程：執行查詢以產生依日誌欄位分組的視覺效果](CWL_AnalyzeLogData_VisualizationFieldQuery.md) + [教學課程：執行查詢來產生時間序列視覺化](CWL_AnalyzeLogData_VisualizationQuery.md) # 教學課程：執行和修改範例查詢 下列教學課程協助您開始使用 CloudWatch Logs Insights。您可以在 Logs Insights QL 中執行範例查詢，然後查看如何修改並重新執行。 若要執行查詢，您必須已經有日誌存放在 CloudWatch Logs。如果您已經在使用 CloudWatch Logs，且已設定日誌群組和日誌串流，那就可以開始。如果您使用 AWS CloudTrail、Amazon Route 53 或 Amazon VPC 等服務，而且已設定將來自這些服務的日誌傳到 CloudWatch Logs，則您也可能已經有日誌。如需有關將日誌傳送至 CloudWatch Logs 的詳細資訊，請參閱[開始使用 CloudWatch Logs](CWL_GettingStarted.md)。 CloudWatch Logs Insights 中的查詢會從日誌事件傳回一組欄位，或在日誌事件上執行的數學加總或其他運算的結果。本教學課程示範的查詢會傳回日誌事件清單。 ## 執行範例查詢 **執行 CloudWatch Logs Insights 範例查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 在 **Logs Insights** 頁面上，查詢編輯器包含 Logs Insights QL 中的預設查詢，該查詢會傳回 20 個最新的日誌事件。 1. 在 **Select log group(s)** (選取日誌群組) 下拉式選單中，選擇一個或多個要查詢的日誌群組。 如果這是 CloudWatch 跨帳戶觀察功能中的監控帳戶，您可以在來源帳戶和監控帳戶中選取日誌群組。單一查詢可以一次查詢來自不同帳戶的日誌。 您可以依日誌群組名稱、帳戶 ID 或帳戶標籤來篩選日誌群組。 當您在標準日誌類別中選取日誌群組時，CloudWatch Logs Insights 會自動偵測群組中的資料欄位。若要查看探索的欄位，請選取頁面右上方附近的 **Fields** (欄位) 選單。 **注意** 僅標準日誌類別中的日誌群組支援探索的欄位。如需日誌類別的詳細資訊，請參閱 [日誌類別](CloudWatch_Logs_Log_Classes.md)。 1. (選用) 使用時間間隔選擇器，選取您要查詢的時間段。 您可以選擇 5 分鐘到 30 分鐘的間隔；1 小時、3 小時和 12 小時的間隔；或是自訂的時間範圍。 1. 選擇 **Run** (執行) 以檢視結果。 在本教學中，結果包括 20 筆最近新增的日誌事件。 CloudWatch Logs 會顯示日誌群組中一段時間內的日誌事件長條圖。長條圖不僅會顯示表格中的事件，還會顯示日誌群組中符合您的查詢和時間範圍的事件分佈。 1. 若要查看傳回日誌事件的所有欄位，請選擇編號事件左側的三角形下拉圖示。 ## 修改範例查詢 在此教學課程中，您將修改範例查詢來顯示 50 個最新的日誌事件。 如果您尚未執行上一個教學課程，請現在這樣做。此教學課程會從上一個教學課程的結尾處開始。 **注意** CloudWatch Logs Insights 隨附的一些範例查詢使用 `head` 或 `tail` 命令，而不是 `limit`。這些命令已被取代，並換成 `limit`。在您編寫的所有查詢中使用 `limit`，而不是 `head` 或 `tail`。 **修改 CloudWatch Logs Insights 範例查詢** 1. 在查詢編輯器中，將 **20** 變更為 **50**，然後選擇 **Run (執行)**。 新查詢的結果隨即出現。假設日誌群組中有足夠的資料在預設時間範圍內，則現在會列出 50 個日誌事件。 1. (選用) 您可以儲存已建立的查詢。若要儲存此查詢，請選擇 **Save** (儲存)。如需詳細資訊，請參閱[儲存並重新執行 CloudWatch Logs Insights 查詢](CWL_Insights-Saving-Queries.md)。 ## 將篩選條件命令新增到範例查詢 本教學課程說明如何在查詢編輯器對查詢進行更強大的變更。在此教學課程中，您將根據已擷取的日誌事件中的欄位，以篩選前一個查詢的結果。 如果您尚未執行先前的教學課程，請現在這樣做。此教學課程會從上一個教學課程的結尾處開始。 **將篩選條件命令新增到前一個查詢** 1. 決定要篩選的欄位。若要查看 CloudWatch Logs 過去 15 分鐘內在選定日誌群組包含的日誌事件中最常偵測到的欄位，以及每個欄位出現在這些日誌事件中的百分比，請在頁面右側選取 **Fields** (欄位)。 若要查看特定日誌事件中包含的欄位，請選擇該列左側的圖示。 **awsRegion** 欄位可能出現在您的日誌事件中，這取決於日誌中有哪些事件。在本教學剩下的部分，我們將使用 **awsRegion** 作為篩選條件欄位，但如果沒有該欄位，您可以使用不同的欄位。 1. 在查詢編輯器方塊中，將游標移到 **50** 後面，然後按 Enter。 1. 在新的一行上，首先輸入 \$1 (垂直線字元) 和空格。CloudWatch Logs Insights 查詢中的命令必須以垂直線字元隔開。 1. 輸入 **filter awsRegion="us-east-1"**。 1. 選擇**執行**。 查詢會再次執行，現在會顯示符合新篩選條件的 50 個最新結果。 如果您篩選不同的欄位，且得到錯誤結果，則可能需要逸出欄位名稱。如果欄位名稱包含非英數字元，您必須在欄位名稱前後加上反引號字元 (`) (例如，**`error-code`="102"**)。 您必須將反引號字元用於包含非英數字元的欄位名稱 ，而不是用於值。值一律包含在引號 (") 中。 Logs Insights QL 包含強大的查詢功能，包括對規則表達式、數學和統計操作的數個命令和支援。如需詳細資訊，請參閱[CloudWatch Logs Insights 語言查詢語法](CWL_QuerySyntax.md)。 # 教學課程：使用彙總函數執行查詢 您可以在 `stats` 命令中使用彙總函式，也可以作為其他函式的引數。在本教學中，您會了解如何執行查詢命令，以計算包含指定欄位的日誌事件數量。查詢命令會回傳按照指定欄位的一個或多個值分組的總數。如需有關彙總函式的詳細資訊，請參閱《*Amazon CloudWatch Logs 使用者指南*》中的[支援的運算和函式](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html#CWL_QuerySyntax-operations-functions)。 **使用彙總函式執行查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 確認已選取 **Logs Insights QL** 標籤。 1. 在 **Select log group(s)** (選取日誌群組) 下拉式選單中，選擇一個或多個要查詢的日誌群組。 如果這是 CloudWatch 跨帳戶觀察功能中的監控帳戶，您可以在來源帳戶和監控帳戶中選取日誌群組。單一查詢可以一次查詢來自不同帳戶的日誌。 您可以依日誌群組名稱、帳戶 ID 或帳戶標籤來篩選日誌群組。 當您選取日誌群組時，如果日誌群組是標準類別日誌群組，CloudWatch Logs Insights 會自動偵測日誌群組中的資料欄位。若要查看探索的欄位，請選取頁面右上方附近的 **Fields** (欄位) 選單。 1. 刪除查詢編輯器中的預設查詢，然後輸入下列命令： ``` stats count(*) by fieldName ``` 1. 將 *fieldName* 替換為 **Fields** (欄位) 選單中探索到的選單欄位。 **Fields** (欄位) 選單位於頁面右上角，會顯示 CloudWatch Logs Insights 在日誌群組中探索到的所有欄位。 1. 選擇 **Run** (執行) 以檢視查詢結果。 查詢結果會顯示日誌群組中與查詢命令相符的記錄筆數，以及按照指定欄位的一個或多個值分組的總數。 # 教學課程：執行查詢以產生依日誌欄位分組的視覺效果 當您執行的查詢使用 `stats` 函數，依日誌項目中一或多個欄位的值來分組傳回的結果時，您可以透過長條圖、圓餅圖、折線圖或堆疊區域圖來檢視結果。這可協助您更有效率地將日誌中的趨勢視覺化。 **執行查詢來產生視覺效果** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 在 **Select log group(s)** (選取日誌群組) 下拉式選單中，選擇一個或多個要查詢的日誌群組。 如果這是 CloudWatch 跨帳戶觀察功能中的監控帳戶，您可以在來源帳戶和監控帳戶中選取日誌群組。單一查詢可以一次查詢來自不同帳戶的日誌。 您可以依日誌群組名稱、帳戶 ID 或帳戶標籤來篩選日誌群組。 1. 在查詢編輯器中，刪除目前的內容，然後輸入以下 `stats` 函式，並選擇 **Run query (執行查詢)**。 ``` stats count(*) by @logStream | limit 100 ``` 結果會顯示每個記錄串流的日誌群組中的日誌事件數量。結果限制為 100 個資料列。 1. 選擇 **Visualization (視覺化)** 標籤。 1. 選取 **Line (行)** 旁邊的箭頭，然後選擇 **Bar (列)**。 此時將會顯示長條圖，顯示日誌群組中每個日誌串流的長條圖。 # 教學課程：執行查詢來產生時間序列視覺化 當您執行的查詢使用 `bin()` 函數，依時段來分組傳回的結果時，您可以透過折線圖、堆疊區域圖、圓餅圖或長條圖來檢視結果。這可協助您更有效率地視覺化日誌事件在一段時間內的趨勢。 **執行查詢來產生視覺效果** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 確認已選取 **Logs Insights QL** 標籤。 1. 在 **Select log group(s)** (選取日誌群組) 下拉式選單中，選擇一個或多個要查詢的日誌群組。 如果這是 CloudWatch 跨帳戶觀察功能中的監控帳戶，您可以在來源帳戶和監控帳戶中選取日誌群組。單一查詢可以一次查詢來自不同帳戶的日誌。 您可以依日誌群組名稱、帳戶 ID 或帳戶標籤來篩選日誌群組。 1. 在查詢編輯器中，刪除目前的內容，然後輸入以下 `stats` 函式，並選擇 **Run query (執行查詢)**。 ``` stats count(*) by bin(30s) ``` 結果會顯示 CloudWatch Logs 在每個 30 秒週期內在日誌群組中收到的日誌事件數。 1. 選擇 **Visualization (視覺化)** 標籤。 結果會顯示為折線圖。若要切換至長條圖、圓餅圖或堆疊區域圖，請選擇圖表左上角 **Line** (線條) 旁邊的箭頭。 # 範例查詢 本節列出您可以在[CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)執行的通用且有效的查詢命令。如需如何執行查詢命令的資訊，請參閱*《Amazon CloudWatch Logs 使用者指南》*中的[教學：執行和修改範例查詢](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_RunSampleQuery.html)。 如需查詢語法的詳細資訊，請參閱 [CloudWatch Logs Insights 語言查詢語法](CWL_QuerySyntax.md)。 **Topics** + [一般查詢](#CWL_QuerySyntax-examples-general) + [Lambda 日誌的查詢](#CWL_QuerySyntax-examples-Lambda) + [Amazon VPC 流程日誌的查詢](#CWL_QuerySyntax-examples-VPC) + [Route 53 日誌的查詢](#CWL_QuerySyntax-examples-Route53) + [CloudTrail 日誌的查詢](#CWL_QuerySyntax-examples-CloudTrail) + [的查詢 Amazon API Gateway](#CWL_QuerySyntax-examples-APIGateway) + [NAT 閘道的查詢](#CWL_QuerySyntax-examples-NATGateway) + [Apache 伺服器日誌的查詢](#CWL_QuerySyntax-examples-Apache) + [Amazon EventBridge 的查詢](#CWL_QuerySyntax-examples-EventBridge) + [剖析命令的範例](#CWL_QuerySyntax-examples-parse) ## 一般查詢 **尋找最近新增的 25 個日誌事件。** ``` fields @timestamp, @message | sort @timestamp desc | limit 25 ``` **取得每小時的例外狀況數清單。** ``` filter @message like /Exception/ | stats count(*) as exceptionCount by bin(1h) | sort exceptionCount desc ``` **取得非例外狀況的日誌事件清單。** ``` fields @message | filter @message not like /Exception/ ``` **取得 `server` 欄位的每個唯一值的最近日誌事件。** ``` fields @timestamp, server, severity, message | sort @timestamp asc | dedup server ``` **取得每個 `severity` 類型的 `server` 欄位的每個唯一值的最近日誌事件。** ``` fields @timestamp, server, severity, message | sort @timestamp desc | dedup server, severity ``` ## Lambda 日誌的查詢 **查明過度佈建的記憶體數量。** ``` filter @type = "REPORT" | stats max(@memorySize / 1000 / 1000) as provisonedMemoryMB, min(@maxMemoryUsed / 1000 / 1000) as smallestMemoryRequestMB, avg(@maxMemoryUsed / 1000 / 1000) as avgMemoryUsedMB, max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB, provisonedMemoryMB - maxMemoryUsedMB as overProvisionedMB ``` **建立延遲報告。** ``` filter @type = "REPORT" | stats avg(@duration), max(@duration), min(@duration) by bin(5m) ``` **搜尋緩慢的函數調用，並消除重試或用戶端程式碼可能產生的重複請求。在此查詢中，`@duration` 以毫秒為單位。** ``` fields @timestamp, @requestId, @message, @logStream | filter @type = "REPORT" and @duration > 1000 | sort @timestamp desc | dedup @requestId | limit 20 ``` ## Amazon VPC 流程日誌的查詢 **尋找主機之間的前 15 個封包傳輸：** ``` stats sum(packets) as packetsTransferred by srcAddr, dstAddr | sort packetsTransferred desc | limit 15 ``` **尋找特定子網路上主機的前 15 個位元組傳輸。** ``` filter isIpv4InSubnet(srcAddr, "192.0.2.0/24") | stats sum(bytes) as bytesTransferred by dstAddr | sort bytesTransferred desc | limit 15 ``` **尋找使用 UDP 做為資料傳輸協定的 IP 地址。** ``` filter protocol=17 | stats count(*) by srcAddr ``` **尋找在擷取時段略過流程記錄的 IP 地址。** ``` filter logStatus="SKIPDATA" | stats count(*) by bin(1h) as t | sort t ``` **尋找每個連線的單一記錄，以協助疑難排解網路連線問題。** ``` fields @timestamp, srcAddr, dstAddr, srcPort, dstPort, protocol, bytes | filter logStream = 'vpc-flow-logs' and interfaceId = 'eni-0123456789abcdef0' | sort @timestamp desc | dedup srcAddr, dstAddr, srcPort, dstPort, protocol | limit 20 ``` ## Route 53 日誌的查詢 **依查詢類型尋找每小時的記錄分佈。** ``` stats count(*) by queryType, bin(1h) ``` **尋找請求數最高的前 10 個 DNS 解析程式。** ``` stats count(*) as numRequests by resolverIp | sort numRequests desc | limit 10 ``` **依網域和子網域尋找伺服器無法完成 DNS 請求的記錄數。** ``` filter responseCode="SERVFAIL" | stats count(*) by queryName ``` ## CloudTrail 日誌的查詢 **尋找每個服務、事件類型和 AWS 區域的日誌項目數量。** ``` stats count(*) by eventSource, eventName, awsRegion ``` **尋找在指定 AWS 區域中啟動或停止的 Amazon EC2 主機。** ``` filter (eventName="StartInstances" or eventName="StopInstances") and awsRegion="us-east-2" ``` **尋找新建立的 IAM 使用者 AWS 的區域、使用者名稱和 ARNs。** ``` filter eventName="CreateUser" | fields awsRegion, requestParameters.userName, responseElements.user.arn ``` **尋找叫用 API `UpdateTrail` 時發生例外狀況的記錄數。** ``` filter eventName="UpdateTrail" and ispresent(errorCode) | stats count(*) by errorCode, errorMessage ``` **尋找使用 TLS 1.0 或 1.1 的日誌條目** ``` filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ] | stats count(*) as numOutdatedTlsCalls by userIdentity.accountId, recipientAccountId, eventSource, eventName, awsRegion, tlsDetails.tlsVersion, tlsDetails.cipherSuite, userAgent | sort eventSource, eventName, awsRegion, tlsDetails.tlsVersion ``` **尋找使用 TLS 1.0 或 1.1 版本之每項服務的呼叫次數** ``` filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ] | stats count(*) as numOutdatedTlsCalls by eventSource | sort numOutdatedTlsCalls desc ``` ## 的查詢 Amazon API Gateway 找出最後 10 個 4XX 錯誤 ``` fields @timestamp, status, ip, path, httpMethod | filter status>=400 and status<=499 | sort @timestamp desc | limit 10 ``` 識別 Amazon API Gateway 存取日誌群組中執行時間最長的 10 個 Amazon API Gateway 請求 ``` fields @timestamp, status, ip, path, httpMethod, responseLatency | sort responseLatency desc | limit 10 ``` 傳回 Amazon API Gateway 存取日誌群組中最常用的 API 路徑清單 ``` stats count(*) as requestCount by path | sort requestCount desc | limit 10 ``` 為您的 Amazon API Gateway 存取日誌群組建立整合延遲報告 ``` filter status=200 | stats avg(integrationLatency), max(integrationLatency), min(integrationLatency) by bin(1m) ``` ## NAT 閘道的查詢 如果您在 AWS 帳單中發現高於正常成本，您可以使用 CloudWatch Logs Insights 來尋找主要參與者。如需下列查詢命令的詳細資訊，請參閱 AWS 進階支援頁面中的[如何透過 VPC 中的 NAT 閘道尋找流量的主要參與者？](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-find-traffic-sources-nat-gateway/)。 **注意** 在以下查詢命令中，將 "x.x.x.x" 取代為 NAT 閘道的私有 IP，並將 "y.y" 替換為 VPC CIDR 範圍的前兩個八位元組。 **查看透過 NAT 閘道傳送最多流量的執行個體。** ``` filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` **確定進出 NAT 閘道中執行個體的流量。** ``` filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.') or (srcAddr like 'xxx.xx.xx.xx' and dstAddr like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` **確定 VPC 中的執行個體在上傳和下載時，最經常與之通訊的網際網路目的地。** *****對於上傳***** ``` filter (srcAddr like 'x.x.x.x' and dstAddr not like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` *****對於下載***** ``` filter (dstAddr like 'x.x.x.x' and srcAddr not like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` ## Apache 伺服器日誌的查詢 您可以使用 CloudWatch Logs Insights 來查詢 Apache 伺服器日誌。如需下列查詢的詳細資訊，請參閱 AWS Cloud Operations & Migrations 部落格中的[使用 CloudWatch Logs Insights 簡化 Apache 伺服器日誌](https://aws.amazon.com/blogs/mt/simplifying-apache-server-logs-with-amazon-cloudwatch-logs-insights/)。 **查看最相關的欄位，以在應用程式的 */admin* 路徑中檢閱存取日誌並檢查流量。** ``` fields @timestamp, remoteIP, request, status, filename| sort @timestamp desc | filter filename="/var/www/html/admin" | limit 20 ``` **查找以狀態碼 "200" (成功) 存取主頁面的不重複 GET 請求次數。** ``` fields @timestamp, remoteIP, method, status | filter status="200" and referrer= http://34.250.27.141/ and method= "GET" | stats count_distinct(remoteIP) as UniqueVisits | limit 10 ``` **查找 Apache 服務重新啟動的次數。** ``` fields @timestamp, function, process, message | filter message like "resuming normal operations" | sort @timestamp desc | limit 20 ``` ## Amazon EventBridge 的查詢 取得按事件詳細資訊類型分組的 EventBridge 事件數 ``` fields @timestamp, @message | stats count(*) as numberOfEvents by `detail-type` | sort numberOfEvents desc ``` ## 剖析命令的範例 **使用 glob 運算式，從日誌欄位 `@message` 中擷取欄位 `@user`、`@method` 和 `@latency`，並傳回 `@method` 和 `@user` 各種不重複組合的平均延遲。** ``` parse @message "user=*, method:*, latency := *" as @user, @method, @latency | stats avg(@latency) by @method, @user ``` **使用規則運算式，從日誌欄位 `@message` 中擷取欄位 `@user2`、`@method2` 和 `@latency2`，並傳回 `@method2` 和 `@user2` 各種不重複組合的平均延遲。** ``` parse @message /user=(?.*?), method:(?.*?), latency := (?.*?)/ | stats avg(latency2) by @method2, @user2 ``` **擷取欄位 `loggingTime`、`loggingType` 和 `loggingMessage`，並篩選包含 `ERROR` 或 `INFO` 字串的日誌事件，然後針對包含 `ERROR` 字串的事件，僅顯示 `loggingMessage` 和 `loggingType` 欄位。** ``` FIELDS @message | PARSE @message "* [*] *" as loggingTime, loggingType, loggingMessage | FILTER loggingType IN ["ERROR", "INFO"] | DISPLAY loggingMessage, loggingType = "ERROR" as isError ``` # 比較 （差異） 與先前的時間範圍 您可以使用 CloudWatch Logs Insights 搭配 Logs Insights QL 來比較日誌事件中隨時間的變化。您可以將最近時間範圍擷取的日誌事件與上一個時段的日誌進行比較。或者，您可以與類似的過去時段進行比較。這可協助您找出日誌中的錯誤是最近推出的還是已經發生，並可協助您尋找其他趨勢。 比較查詢只會傳回結果中的模式，不會傳回原始日誌事件。傳回的模式可協助您快速查看日誌事件隨時間變化的趨勢和變化。執行比較查詢並取得模式結果後，您可以查看感興趣的模式的範例原始日誌事件。如需日誌模式的詳細資訊，請參閱 [模式分析](CWL_AnalyzeLogData_Patterns.md)。 當您執行比較查詢時，會根據兩個不同的時段來分析查詢：您選取的原始查詢期間，以及比較期間。比較期間的長度一律與原始查詢期間相同。比較的預設時間間隔如下。 + **上一個期間** — 與查詢期間之前的期間進行比較。 + **前一天** — 與查詢期間前一天的期間進行比較。 + **上週** — 與查詢期間前一週的期間進行比較。 + **上個月** — 與查詢期間之前的一個月期間進行比較。 **注意** 使用比較的查詢會產生類似於在合併時間範圍內執行單一 CloudWatch Logs Insights 查詢的費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。 **執行比較查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**日誌**，然後選擇 **Logs Insights**。 預設查詢會出現在查詢方塊中。 1. 確認已選取 **Logs Insights QL** 標籤。 1. 保留預設查詢或輸入不同的查詢。 1. 在**選取日誌群組 （選取日誌群組） **下拉式清單中，選擇要查詢的一或多個日誌群組。 1. (選用) 使用時間間隔選擇器，選取您要查詢的時間段。預設查詢適用於前一小時的日誌資料。 1. 根據時間範圍選擇器，選擇**比較**。然後選擇您要與之比較原始日誌的先前時段，然後選擇**套用**。 1. 選擇 **Run query** (執行查詢)。 為了讓查詢從比較期間擷取資料， `diff`命令會附加到您的查詢。 1. 選擇**模式**索引標籤以查看結果。 資料表會顯示下列資訊： + 每個**模式**，模式的可變部分以動態字符符號 取代``。*字串*是字符所代表資料類型的描述。此*數字*顯示與其他動態字符相比，此字符在模式中的顯示位置。如需詳細資訊，請參閱[模式分析](CWL_AnalyzeLogData_Patterns.md)。 + **事件計數**是具有該模式的日誌事件數量，在原始、較目前的時段內。 + **差異事件計數**是目前期間內相符日誌事件的數量與比較期間之間的差異。正數不同表示目前期間內有更多這類事件。 + **差異描述**簡短總結了目前期間和比較期間之間該模式的變更。 + **嚴重性類型**是根據日誌事件中找到的字詞，例如 `FATAL`、 `ERROR`和 ，以此模式記錄事件的可能嚴重性`WARN`。 1. 若要進一步檢查清單中的其中一個模式，請選擇**檢查**欄中其中一個模式的圖示。 **模式檢查**窗格隨即出現，並顯示下列項目： + **模式**。在模式中選取權杖，以分析該權杖的值。 + 顯示查詢時間範圍內模式出現次數的長條圖。這可協助您識別有趣的趨勢，例如模式的出現突然增加。 + **日誌範例**索引標籤會顯示一些符合所選模式的日誌事件。 + 如果您已選取動態權杖，**權杖值**索引標籤會顯示所選動態權杖的值。 **注意** 每個字符最多擷取 10 個字符值。字符計數可能不精確。CloudWatch Logs 使用機率計數器來產生字符計數，而不是絕對值。 + **相關模式**索引標籤會顯示與您檢查的模式幾乎同時經常發生的其他模式。例如，如果`ERROR`訊息的模式通常伴隨另一個標記為 的日誌事件`INFO`和其他詳細資訊，則此模式會顯示在此處。 # 在圖表中視覺化日誌資料 您可以使用長條圖、折線圖和堆疊區域圖等視覺效果，更有效率地識別日誌資料中的模式。CloudWatch Logs Insights 可以為使用 `stats` 函數和一或多個彙總函數的查詢產生視覺效果。如需詳細資訊，請參閱 [stats](CWL_QuerySyntax-Stats.md)。 # OpenSearch 管道處理語言 (PPL) 本節包含使用 OpenSearch PPL 查詢 CloudWatch Logs 的基本簡介。您可以使用 PPL 擷取、查詢和分析資料，以便更輕鬆地了解和編寫複雜的查詢。其語法是以 Unix 管道為基礎，並啟用命令鏈結來轉換和處理資料。透過 PPL，您可以篩選和彙總資料，並使用一組豐富的數學、字串、日期、條件式和其他函數進行分析。 在 PPL 查詢`SOURCE`中包含 是指定日誌群組欄位索引的實用方式，以及當您使用 AWS CLI 或 API 建立查詢時要包含在查詢中的資料來源。`SOURCE` 命令僅在 AWS CLI 和 API 中受支援，在 CloudWatch 主控台中不受支援。當您使用 CloudWatch 主控台啟動查詢時，您可以使用主控台界面來指定日誌群組和資料來源名稱和類型。 `aws:fieldIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。系統會根據 `filterIndex`命令中指定的欄位，自動選取相關的日誌群組。這可藉由略過沒有任何包含查詢中指定欄位之日誌事件的日誌群組，以及僅掃描符合此欄位索引查詢中指定值的日誌群組，來減少掃描的磁碟區。使用 `aws:fieldIndex`指定欄位名稱，以及來源命令中的欄位名稱和值，以僅查詢包含指定欄位和值的索引資料。如需詳細資訊，請參閱[建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md) 您可以使用 OpenSearch PPL 來查詢標準日誌類別中的日誌群組。 **注意** 如需 CloudWatch Logs 中支援的所有 OpenSearch PPL 查詢命令的相關資訊，以及語法和限制的詳細資訊，請參閱OpenSearch Service 開發人員指南》中的[支援的 PPL 命令](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html)。 如需有關您可以使用之其他查詢語言的資訊，請參閱 [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) 和 [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html) | 命令或函數 | 查詢範例 | Description | | --- | --- | --- | | fields | `fields field1, field2` | 顯示一組需要投影的欄位。 | | join | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | 將兩個資料集聯結在一起。 | | where | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | 根據您指定的條件篩選資料。 | | aws：fieldIndex | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10` | 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。 | | 統計資料 | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | 執行彙總和計算 | | parse | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | 從字串擷取規則表達式 (regex) 模式，並顯示擷取的模式。擷取的模式可以進一步用來建立新的欄位或篩選資料。 | | sort | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | 依欄位名稱排序顯示的結果。使用 sort -FieldName 以遞減順序排序。 | | 評估 | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | 修改或處理欄位的值，並將其存放在不同的欄位中。這有助於以數學方式修改資料欄、將字串函數套用至資料欄，或將日期函數套用至資料欄。 | | 重新命名 | `rename field2 as field1 \| fields field1;` | 重新命名搜尋結果中的一個或多個欄位。 | | head | `fields `@message` \| head 20` | 將顯示的查詢結果限制為前 N 列。 | | top | `top 2 field1 by field2` | 尋找欄位最常見的值。 | | dedup | `dedup field1 \| fields field1, field2, field3` | 根據您指定的欄位移除重複的項目。 | | 很少見 | `rare field1 by field2` | 尋找欄位清單中所有欄位頻率最低的值。 | | subquery | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | 在您的 PPL 陳述式中執行複雜的巢狀查詢。 | | 趨勢線 | `trendline sma(2, field1) as field1Alias` | 計算欄位的移動平均值。 | | eventStats | `eventstats sum(field1) by field2` | 使用計算的摘要統計資料來豐富您的事件資料。它會分析事件中的指定欄位、運算各種統計指標，然後將這些結果做為新欄位附加到每個原始事件。 | | expand | `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags` | 將包含多個值的欄位細分為不同的資料列，為指定欄位中的每個值建立新的資料列。 | | fillnull | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | 使用您提供的值填入 null 欄位。它可用於一個或多個欄位。 | | flatten | `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) ` | 扁平化欄位。欄位必須屬於此類型： `struct`或 `array>`。 | | cidrmatch | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | 檢查指定的 IP 地址是否在指定的 CIDR 範圍內。 | | 欄位摘要 | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | 計算每個欄位的基本統計資料 （計數、相異計數、最小值、最大值、平均值、標準差和平均值）。 | | grok | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | 剖析具有 grok 模式的文字欄位，並將結果附加到搜尋結果。 | | 字串函數 | `eval field1Len = LENGTH(field1) \| fields field1Len` | PPL 中的內建函數，可以操作和轉換 PPL 查詢中的字串和文字資料。例如，轉換案例、合併字串、擷取部分和清理文字。 | | 日期時間函數 | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | 用於處理和轉換 PPL 查詢中日期和時間戳記資料的內建函數。例如，date\$1add、date\$1format、datediff、date-sub、timestampadd、timestampdiff、current\$1timezone、utc\$1timestamp 和 current\$1date。 | | 條件函數 | `eval field2 = isnull(field1) \| fields field2, field1, field3` | 檢查特定欄位條件，並依條件評估表達式的內建函數。例如，如果 field1 為 null，則傳回 field2。 | | 數學函數 | `eval field2 = ACOS(field1) \| fields field1` | 用於在 PPL 查詢中執行數學計算和轉換的內建函數。例如，abs （絕對值）、圓 （圓數）、sqrt （平方根）、pow （功率計算） 和 ceil （四捨五入至最接近的整數）。 | | CryptoGraphic 函數 | `eval crypto = MD5(field)\| head 1000` | 計算指定欄位的雜湊 | | JSON 函數 | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | 用於處理 JSON 的內建函數，包括陣列、擷取和驗證。例如，json\$1object、json\$1array、to\$1json\$1string、json\$1array\$1length、json\$1extract、json\$1keys 和 json\$1valid。 | ## 查詢範圍 當您使用 AWS CLI 或 API 建立查詢時，在查詢中包含 SOURCE 是指定要包含在查詢中的日誌群組的實用方式。SOURCE 命令僅支援 AWS CLI 和 API，不支援 CloudWatch 主控台。當您使用 CloudWatch 主控台啟動查詢時，您可以使用主控台界面來指定日誌群組和資料來源名稱和類型。 PPL 的來源命令現在支援多種指定方式： 1. 日誌群組 1. 欄位索引 - 新 1. 資料來源和類型 - 新 ### 日誌群組 當客戶知道需要搜尋哪個確切的日誌群組 （日誌群組） 時，可以使用日誌群組來源選擇 ``` source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10 ``` ### 欄位索引 當篩選條件鎖定已編製索引的欄位時，將結果限制為僅編製索引的資料，以欄位索引為基礎的來源選擇可減少查詢的資料量。系統會根據 `filterIndex`命令中指定的欄位，自動選取相關的日誌群組。如需欄位索引及其建立方式的詳細資訊，請參閱[建立欄位索引以改善查詢效能並降低掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。 `aws:fieldIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。對於在此欄位上編製索引的這些日誌群組，它會略過沒有包含索引欄位查詢中指定欄位的任何日誌事件的日誌群組，以進一步最佳化查詢。它透過嘗試僅掃描這些日誌群組中符合此欄位索引查詢中指定值的日誌事件，進一步減少掃描的磁碟區。如需欄位索引及其建立方式的詳細資訊，請參閱建立欄位索引以改善查詢效能並降低掃描磁碟區。 在 PPL 中， `aws:fieldIndex` 用於指定哪些索引鍵值對應被視為索引。語法如下 ``` source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10 ``` 其中， 1. ``aws:fieldIndex`="region"` 將區域識別為欄位索引。 1. 注意：而不是 = 客戶可以使用 IN 來指定多個索引 （範例如下） 1. ``region`="us-west-2"` 識別要套用的篩選條件 1. 注意：而不是 = 客戶可以使用 IN 來指定多個值 （範例如下） 客戶可以指定多個 fieldIndexes，如下所示 ``` source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10 ``` ### 資料來源和類型 當客戶知道需要查詢哪些確切資料來源時，可以使用資料來源和類型型來源選擇。此查詢會透過一或多個包含指定資料來源和類型的日誌群組執行。 ``` source = [ds:`data_source.type`] | where status = 200 | head 10 ``` #### 資料來源查詢支援的 PPL 若要支援在 PPL 中查詢資料來源的使用案例，您可以使用動態來源選取器子句。使用此語法，您可以在搜尋命令中指定資料來源，以查詢資料來源。您最多可以指定 10 個資料來源。 **語法** ``` source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`] ``` **查詢範例** ``` search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2 ``` ### 合併的範例 客戶可以按任何順序指定所有來源選取運算子，結果會是所有套用條件的交集。 例如，/aws/lambda/my-function-1 可能包含多個資料來源和類型，包括各種索引，當執行下列查詢時，傳回的結果只會有來源和類型 DataSource1.Type1 的事件，並符合 'status' = 200 的條件。 ``` search source=[ ds:`DataSource1.Type1`, lg:`/aws/lambda/my-function-1`, `aws:fieldIndex` IN ("status"), `status` = 200 ] ``` ## 限制 當您使用 OpenSearch PPL 在 CloudWatch Logs Insights 中查詢時，適用下列限制。 + 您無法搭配資料來源查詢使用聯結或子查詢命令。 # OpenSearch 結構化查詢語言 (SQL) 本節包含使用 OpenSearch SQL 查詢 CloudWatch Logs 的基本簡介。如果您習慣使用關聯式資料庫，它會提供熟悉的選項。OpenSearch SQL 提供 SQL 功能的子集，使其成為執行臨機操作查詢和資料分析任務的理想選擇。透過 OpenSearch SQL，您可以使用 SELECT、 FROM、WHERE、GROUP BY、HAVING 等命令，以及各種其他 SQL 命令和函數。您可以跨日誌群組執行 JOINs、使用子查詢跨日誌群組關聯資料，並使用一組豐富的 JSON、數學、字串、條件式和其他 SQL 函數，對日誌和安全資料執行強大的分析。 `filterIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。略過沒有任何包含查詢中指定欄位之日誌事件的日誌群組，並僅掃描符合此欄位索引查詢中指定值的日誌群組，以減少掃描的磁碟區。使用 `filterIndex`指定欄位名稱，以及欄位名稱和值，以僅查詢包含指定欄位和值的索引資料。 您可以使用 OpenSearch SQL 來查詢標準日誌類別中的日誌群組。SQL 也支援使用資料來源名稱和資料來源類型進行查詢。 **注意** 下表列出 CloudWatch Logs 中支援的 SQL 命令和函數 如需所有 OpenSearch SQL 命令的資訊，包括語法，請參閱 OpenSearch Service 開發人員指南中的[支援的 SQL 命令](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-directquery-sql.html)。 如需有關您可以使用的其他查詢語言的資訊，請參閱[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html) 和 [CloudWatch。 Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html) ## 支援的 SQL 命令 **注意** 在範例查詢欄中，根據您查詢的資料來源``，視需要取代 。 | 命令或函數 | 查詢範例 | Description | | --- | --- | --- | | SELECT | `SELECT `@message`, Operation FROM `LogGroupA`` | 顯示投影值。 | | FROM | `SELECT `@message`, Operation FROM `LogGroupA`` | 內建子句 （指定要從中擷取資料的來源資料表或檢視），支援各種類型的聯結和子查詢。 | | WHERE | `SELECT * FROM `LogGroupA` WHERE Operation = 'x'` | 根據提供的欄位條件篩選日誌事件。 | | filterIndex | `SELECT * FROM `filterIndex('region' = 'us-east-1')` WHERE status = 200 LIMIT 10;` | 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。 | | GROUP BY | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream`` | 根據類別對日誌事件進行分組，並根據統計資料尋找平均值。 | | HAVING | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream` HAVING log_count > 100` | 根據分組條件篩選結果。 | | ORDER BY | `SELECT * FROM `LogGroupA` ORDER BY `@timestamp` DESC` | 根據 ORDER BY 子句中的欄位排序結果。您可以依遞減或遞增順序排序。 | | JOIN | `SELECT A.`@message`, B.`@timestamp`FROM `LogGroupA` as A INNER JOIN `LogGroupB` as B ON A.`requestId` = B.`requestId`` | 根據常見欄位聯結兩個資料表的結果。必須指定內部 JOIN 或左側外部聯結 | | LIMIT | `Select * from `LogGroupA` limit 10` | 將顯示的查詢結果限制為前 N 列。 | | 字串函數 | `SELECT upper(Operation) , lower(Operation), Operation FROM `LogGroupA`` | SQL 中的內建函數，可以操作和轉換 SQL 查詢中的字串和文字資料。例如，轉換案例、合併字串、擷取部分和清理文字。 | | 日期函數 | `SELECT current_date() as today, date_add(current_date(), 30) as thirty_days_later, last_day(current_date()) as month_end FROM `LogGroupA`` | 用於處理和轉換 SQL 查詢中日期和時間戳記資料的內建函數。例如，date\$1add、date\$1format、datediff 和 current\$1date。 | | 條件函數 | `SELECT Operation, IF(Error > 0, 'High', 'Low') as error_category FROM `LogGroupA`;` | 內建函數，可根據指定的條件執行動作，或以條件方式評估表達式。例如，CASE 和 IF。 | | 彙總函數 | `SELECT AVG(bytes) as bytesWritten FROM `LogGroupA`` | 對多個資料列執行計算以產生單一摘要值的內建函數。例如，SUM、COUNT、AVG、MAX 和 MIN。 | | JSON 函數 | `SELECT get_json_object(json_column, '$.name') as name FROM `LogGroupA`` | 用於在 SQL 查詢中剖析、擷取、修改和查詢 JSON 格式資料的內建函數 （例如，from\$1json、to\$1json、get\$1json\$1object、json\$1tuple)，允許在資料集中操作 JSON 結構。 | | 陣列函數 | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | 用於在 SQL 查詢中使用陣列類型資料欄的內建函數，允許存取、修改和分析陣列資料 （例如，大小、爆炸、Array\$1contains) 等操作。 | | 範圍函數 | `SELECT field1, field2, RANK() OVER (ORDER BY field2 DESC) as field2Rank FROM `LogGroupA`;` | 內建函數，可在與目前資料列 （視窗） 相關的指定資料列中執行計算，啟用排名、執行總計和移動平均值等操作。例如，ROW\$1NUMBER、RANK、LAG 和 LEAD | | 轉換函數 | `SELECT CAST('123' AS INT) as converted_number, CAST(123 AS STRING) as converted_string FROM `LogGroupA`` | 用於在 SQL 查詢中將資料從一種類型轉換為另一種類型的內建函數，啟用資料類型轉換和格式轉換。例如，CAST、TO\$1DATE、TO\$1TIMESTAMP 和 BINARY。 | | 述詞函數 | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | 根據指定的條件或模式，評估條件並傳回布林值 (true/false) 的內建函數。例如，IN、LIKE、BETWEEN、IS NULL 和 EXISTS。 | | 選取多個日誌群組 | `SELECT lg1.field1, lg1.field2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'])` as lg1 where lg1.field3= "Success"` | 可讓您在 SELECT 陳述式中指定多個日誌群組 | | 選取多個資料來源 | `SELECT ds1.field1, ds1.field2 from `dataSource(['DataSource1', 'DataSource2'])` as ds1 where ds1.field3= "Success"` | 可讓您在 SELECT 陳述式中指定多個資料來源 | ## multi-log-group查詢支援的 SQL 若要支援在 SQL 中查詢多個日誌群組的使用案例，您可以使用 `logGroups`命令。使用此語法，您可以在 FROM 命令中指定多個日誌群組來查詢它們。 語法： ``` `logGroups( logGroupIdentifier: ['LogGroup1','LogGroup2', ...'LogGroupn'] ) ``` 在此語法中，您可以在 `logGroupIdentifier` 參數中指定最多 50 個日誌群組。若要參考監控帳戶中的日誌群組，請使用 ARNs 而非`LogGroup`名稱。 查詢範例： ``` SELECT LG1.Column1, LG1.Column2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'] )` as LG1 WHERE LG1.Column1 = 'ABC' ``` 查詢 CloudWatch Logs 時，不支援在`FROM`陳述式之後涉及多個日誌群組的下列語法。 ``` SELECT Column1, Column2 FROM 'LogGroup1', 'LogGroup2', ...'LogGroupn' WHERE Column1 = 'ABC' ``` ## 資料來源查詢支援的 SQL 若要支援在 SQL 中查詢資料來源的使用案例，您可以使用 dataSource 命令。使用此語法，您可以在 `FROM`命令中指定資料來源，以查詢資料來源。您最多可以指定 10 個資料來源。 **語法** ``` `dataSource( ['DataSource1', 'DataSource2', ...'DataSourcen'] )` ``` **查詢範例 ** ``` SELECT DS1.Column1, DS1.Column2 from `dataSource( ['DataSource1', 'DataSource2'] )` as DS1 WHERE DS1.Column1 = 'ABC' ``` ## 查詢範圍 在 AWS CLI 和 API 中，您可以使用日誌群組、資料來源和類型，以及欄位索引來指定要查詢的日誌。 ### 日誌群組 當客戶知道需要搜尋哪個確切日誌群組 （日誌群組） 時，可以使用日誌群組來源選擇 ``` SELECT * FROM `logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])`; ``` ### 資料來源和類型 客戶可以使用資料來源名稱和資料來源類型來查詢其日誌。 當客戶知道需要查詢哪些確切資料來源時，可以使用資料來源和類型型來源選擇。此查詢會透過一或多個包含指定資料來源和類型的日誌群組執行。 若要支援在 SQL 中查詢資料來源的使用案例，您可以使用 dataSource 命令。使用此語法，您可以在 FROM 命令中指定資料來源，以查詢資料來源。您最多可以指定 10 個資料來源。 語法： ``` `dataSource( ['DataSource1.Type1', 'DataSource2.Type2', ...'DataSourcen.Typen'] )` ``` 查詢範例： ``` SELECT DS1.Column1, DS1.Column2 from `dataSource( ['DataSource1.Type1', 'DataSource2.Type2'] )` as DS1 WHERE DS1.Column1 = 'ABC' ``` 如需依資料來源查詢的詳細資訊，請參閱 [使用面向來分組和探索日誌](CloudWatchLogs-Facets.md)。 ### 合併的範例 客戶可以在反引號內以任何順序指定所有來源選取運算子，結果會根據所有套用條件的交集。 例如，/aws/lambda/my-function-1 可能包含多個資料來源和類型，包括各種索引，當執行下列查詢時，傳回的結果只會有來源和類型 DataSource1.Type1 的事件，並符合 'status' = 200 的條件。 ``` SELECT * FROM ` logGroups(logGroupIdentifier: ['/aws/lambda/my-function']) filterIndex('status' = 200) dataSource(['DataSource1.Type1']) `; ``` ### 欄位索引 當您篩選目標索引欄位時，欄位索引型來源選擇會自動識別相關日誌群組，以減少掃描磁碟區和查詢執行時間。 `filterIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。對於在此欄位上編製索引的這些日誌群組，它會略過沒有包含索引欄位查詢中指定欄位之任何日誌事件的日誌群組，以進一步最佳化查詢。它透過嘗試僅掃描這些日誌群組中符合此欄位索引查詢中指定值的日誌事件，進一步減少掃描的磁碟區。如需欄位索引以及如何建立它們的詳細資訊，請參閱[建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。 在 SQL 中，filterIndex 用於指定哪些索引鍵值對應被視為索引。語法如下 ``` SELECT * FROM `filterIndex('region' = 'us-east-1')`; ``` 其中， 1. filterIndex(...) 指定將其中的索引鍵值視為欄位索引。每個索引鍵值對以逗號分隔 （範例如下） 1. 'region' = 'us-east-1' 指定要套用的實際條件 1. 注意：而不是 = 客戶可以使用 IN 來指定多個值 （範例如下） 使用多個 filterIndex 會使用 "AND" 結合條件。在此範例中，會查詢 us-east-1 或 us-west-2 中的日誌比對狀態=200 和區域。 ``` SELECT * FROM `filterIndex('status' = 200, 'region' IN ['us-east-1', 'us-west-2'])`; ``` ## 限制 當您使用 OpenSearch SQL 在 CloudWatch Logs Insights 中查詢時，適用下列限制。 + 您只能在 SELECT 陳述式中包含一個 JOIN。 + 您無法搭配資料來源查詢使用 JOIN 或子查詢。 + 僅支援一個層級的巢狀子查詢。 + 不支援以分號 (；) 分隔的多個陳述式查詢。 + 不支援包含相同但僅在 欄位 （例如 field1 和 FIELD1) 時才不同的欄位名稱的查詢。 例如，不支援下列查詢： ``` Select AWSAccountId, AwsAccountId from LogGroup ``` 不過，由於兩個日誌群組中的欄位名稱 (`@logStream`) 相同，因此支援下列查詢： ``` Select a.`@logStream`, b.`@logStream` from Table A INNER Join Table B on a.id = b.id ``` + 函數和表達式必須在欄位名稱上操作，並成為 SELECT 陳述式的一部分，其中包含 FROM 子句中指定的日誌群組。 例如，不支援此查詢： ``` SELECT cos(10) FROM LogGroup ``` 支援此查詢： ``` SELECT cos(field1) FROM LogGroup ``` + 使用 SQL 或 PPL 命令時，請將特定欄位括在反引號中，以成功查詢它們。具有特殊字元 （非字母和非數字） 的欄位需要反引號。例如，將 `@message`、 `Operation.Export`和 括在反引號`Test::Field`中。您不需要在反引號中以純字母名稱括住欄位。 具有簡單欄位的範例查詢： ``` SELECT SessionToken, Operation, StartTime FROM `LogGroup-A` LIMIT 1000; ``` 附加反引號的類似查詢： ``` SELECT `@SessionToken`, `@Operation`, `@StartTime` FROM `LogGroup-A` LIMIT 1000; ``` # 使用自然語言來產生和更新 CloudWatch Logs Insights 查詢 CloudWatch Logs 支援自然語言查詢功能，可協助您產生和更新 [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html)、[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) 和 [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)的查詢。 使用此功能，您可以詢問或描述以純英文尋找的 CloudWatch Logs 資料。自然語言功能會根據您輸入的提示產生查詢，並逐行說明查詢的運作方式。也可以更新查詢以進一步調查您的資料。 根據您的環境，您可以輸入提示，例如「傳輸位元組的前 100 個來源 IP 地址是什麼？」 和「尋找 10 個最慢的 Lambda 函數請求。」 **注意** 自然語言查詢功能是區域性服務。對於某些區域，此功能會對美國區域進行跨區域呼叫，以處理查詢提示。如需詳細資訊，請參閱 [Amazon CloudWatch 擴展區域對自然語言查詢結果摘要和查詢產生 的支援](https://aws.amazon.com/about-aws/whats-new/2025/08/amazon-cloudwatch-region-support-query-result-summarization-query-generation/)。 若要使用此功能產生 CloudWatch Logs Insights 查詢，請開啟 CloudWatch Logs Insights 查詢編輯器，選取您要查詢的日誌群組，然後選擇**產生查詢**。 **重要** 若要使用自然語言查詢功能，您必須使用 [CloudWatchLogsFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsFullAccess.html)、[CloudWatchLogsReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html)、 [AdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) 或 [ReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html) IAM 政策登入，或具有 `cloudwatch:GenerateQuery`許可。 ## 查詢範例 本節中的範例說明如何使用自然語言功能產生及更新查詢。 **注意** 如需 CloudWatch Logs Insights 查詢編輯器和語法的詳細資訊，請參閱 [CloudWatch Logs Insights 查詢語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)。 ### 範例：產生自然語言查詢 若要使用自然語言產生查詢，請輸入提示並選擇**產生新查詢**。這些範例顯示執行基本搜尋的查詢。 **提示詞** 以下是提示範例，指示 搜尋 10 個最慢 Lambda 函數叫用的功能。 ``` Find the 10 slowest requests ``` **Query** 以下是使用 CloudWatch Logs Insights 查詢語言的查詢，自然語言功能會根據提示產生。請注意提示在查詢前出現在註解中的方式。查詢之後，您可以閱讀描述查詢運作方式的說明。 ``` # Find the 10 slowest requests fields @timestamp, @message, @duration | sort @duration desc | limit 10 # This query retrieves the timestamp, message and duration fields from the logs and sorts them in descending order by duration to find the 10 slowest requests. ``` **注意** 若要關閉提示的外觀以及查詢運作方式的說明，請使用編輯器中的齒輪圖示。 **提示詞** 若要產生 OpenSearch SQL 查詢，請選取 OpenSearch SQL 索引標籤，然後開啟查詢產生器提示方塊以輸入您的自然語言提示。以下是使用自然語言功能產生 OpenSearch SQL 查詢的提示範例。 ``` Give me the number of errors and exceptions per hour ``` **Query** 以下是該提示產生的 SQL 查詢，您可以使用它來尋找每小時彙總的錯誤和例外狀況數量： ``` SELECT DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') AS hour, COUNT(*) AS error_count FROM `/aws/lambda/CloudWatchOdysseyQueryGen` WHERE `@message` LIKE '%error%' OR `@message` LIKE '%exception%' GROUP BY DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') ORDER BY hour ``` **提示詞** 若要產生 OpenSearch PPL 查詢，請選取 OpenSearch PPL 標籤，然後開啟查詢產生器提示方塊以輸入您的自然語言提示。以下是使用自然語言功能來產生 OpenSearch PPL 查詢的提示範例。 ``` Give me all unique exception messages ``` **Query** 以下是該提示產生的 PPL 查詢，您可以使用它在日誌中尋找唯一的例外狀況訊息： ``` dedup @message | fields @message ``` ### 範例：更新自然語言查詢 可以透過編輯初始提示，然後選擇**更新查詢**來更新查詢。 **更新提示** 下列範例顯示先前提示的更新版本。而不是搜尋 10 個最慢 Lambda 函數調用的提示，此提示現在會指示 搜尋 20 個最慢 Lambda 函數調用的功能，並包含其他日誌事件的另一個資料欄。 ``` Show top 20 slowest requests instead and display requestId as a column ``` **更新查詢** 以下是使用 CloudWatch Logs Insights 查詢語言更新查詢的範例。請注意更新後的提示在更新後的查詢前出現在註解中的方式。查詢之後，您可以閱讀描述原始查詢更新方式的說明。 ``` # Show top 20 slowest requests instead and display requestId as a column fields @timestamp, @message, @requestId, @duration | sort @duration desc | limit 20 # This query modifies the original query by replacing the @message field with the @requestId field and changing the limit from 10 to 20 to return the top 20 log events by duration instead of the top 10. ``` ## 選擇不使用您的資料以改善服務 您提供用於訓練 AI 模型並產生相關查詢的自然語言提示資料僅用於提供和維護您的服務。此資料可能用於改善 CloudWatch Logs Insights 的品質。我們將您的信任和隱私以及內容安全性放在首位。如需詳細資訊，請參閱 [AWS 服務條款](https://aws.amazon.com/service-terms/)和 [AWS 負責任的 AI 政策](https://aws.amazon.com/machine-learning/responsible-ai/policy/)。 透過建立 AI 服務退出政策，可選擇不將您的內容用於開發或改進自然語言查詢的品質。若要選擇退出所有 CloudWatch Logs AI 功能的資料收集，包括查詢產生功能，您必須為 CloudWatch Logs 建立選擇退出政策。如需詳細資訊，請參閱《AWS Organizations 使用者指南》**中的 [AI 服務退出政策](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)。 # 支援的日誌和探索的欄位 CloudWatch Logs Insights 支援各種類型的日誌。對於傳送至 Amazon CloudWatch Logs 中標準類別日誌群組的每個日誌，CloudWatch Logs Insights 會自動產生五個系統欄位： + `@message` 包含原始未分析的日誌事件。這相當於 [InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html) 中的 `message` 欄位。 + `@timestamp` 含有日誌事件 `timestamp` 欄位中的事件時間戳記。這相當於 [InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html) 中的 `timestamp` 欄位。 + `@ingestionTime` 含有 CloudWatch Logs 收到日誌事件的時間。 + `@logStream` 包含日誌事件新增到其中的日誌串流名稱。日誌串流透過產生日誌串流的相同程序對日誌進行分組。 + `@log` 是 `account-id:log-group-name` 形式的日誌群組識別碼。在查詢多個日誌群組時，這有助於識別特定事件所屬的日誌群組。 + `@entity` 包含與[探索相關遙測](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ExploreRelated.html)功能的實體相關的平面化 JSON。 例如，此 JSON 可以代表實體。 ``` { "Entity": { "KeyAttributes": { "Type": "Service", "Name": "PetClinic" }, "Attributes": { "PlatformType": "AWS::EC2", "EC2.InstanceId": "i-1234567890123" } } } ``` 對於此實體，擷取的系統欄位如下： ``` @entity.KeyAttributes.Type = Service @entity.KeyAttributes.Name = PetClinic @entity.Attributes.PlatformType = AWS::EC2 @entity.Attributes.EC2.InstanceId = i-1234567890123 ``` **注意** 欄位探索僅支援標準日誌類別中的日誌群組。如需日誌類別的詳細資訊，請參閱 [日誌類別](CloudWatch_Logs_Log_Classes.md)。 CloudWatch Logs Insights 會在其產生的欄位開頭插入 **@** 符號。 對於許多日誌類型，CloudWatch Logs 也會自動探索日誌包含的日誌欄位。下表顯示這些自動探索的欄位。 如果是 CloudWatch Logs Insights 不會自動探索欄位的其他日誌類型，您可以使用 `parse` 命令來擷取和建立擷取欄位，以用於該查詢中。如需詳細資訊，請參閱[CloudWatch Logs Insights 語言查詢語法](CWL_QuerySyntax.md)。 如果找到的日誌欄位以 `@` 為名稱開頭，CloudWatch Logs Insights 顯示該欄位時會在開頭多加一個 `@`。例如，如果日誌欄位名稱是 `@example.com`，這個欄位名稱會顯示為 `@@example.com`。 **注意** 除了 `@message`、 `@timestamp`或 之外`@log`，您可以為探索到的欄位建立欄位索引。如需欄位索引的詳細資訊，請參閱 [建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。 | 日誌類型 | 探索的日誌欄位 | | --- | --- | | Amazon VPC 流程日誌 | `@timestamp`, `@logStream`, `@message`, `accountId`, `endTime`, `interfaceId`, `logStatus`, `startTime`, `version`, `action`, `bytes`, `dstAddr`, `dstPort`, `packets`, `protocol`, `srcAddr`, `srcPort` | | Route 53 日誌 | `@timestamp`, `@logStream`, `@message`, `edgeLocation`, `ednsClientSubnet`, `hostZoneId`, `protocol`, `queryName`, `queryTimestamp`, `queryType`, `resolverIp`, `responseCode`, `version` | | Lambda 日誌 | `@timestamp`, `@logStream`, `@message`, `@requestId`, `@duration, ``@billedDuration`, `@type`, `@maxMemoryUsed`, `@memorySize` 如果 Lambda 日誌行包含 X-Ray 追蹤 ID，則也會包含以下欄位：`@xrayTraceId` 和 `@xraySegmentId`。 CloudWatch Logs Insights 會自動探索 Lambda 日誌中的日誌欄位，但僅限於每個日誌事件中的第一個內嵌 JSON 片段。如果 Lambda 日誌事件包含多個 JSON 片段，您可以使用 `parse` 命令來剖析和擷取日誌欄位。如需詳細資訊，請參閱[JSON 日誌中的欄位](#CWL_AnalyzeLogData-discoverable-JSON-logs)。 | | CloudTrail 日誌 JSON 格式的日誌 | 如需詳細資訊，請參閱[JSON 日誌中的欄位](#CWL_AnalyzeLogData-discoverable-JSON-logs)。 | | 其他日誌類型 | `@timestamp`, `@ingestionTime`, `@logStream`, `@message`, `@log`. | ## JSON 日誌中的欄位 藉由 CloudWatch Logs Insights，您可以使用點符號來表示 JSON 欄位。本節包含 JSON 事件範例和程式碼片段，示範如何使用點符號存取 JSON 欄位。 **範例：JSON 事件** ``` { "eventVersion": "1.0", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn: aws: iam: : 123456789012: user/Alice", "accessKeyId": "EXAMPLE_KEY_ID", "accountId": "123456789012", "userName": "Alice" }, "eventTime": "2014-03-06T21: 22: 54Z", "eventSource": "ec2.amazonaws.com", "eventName": "StartInstances", "awsRegion": "us-east-2", "sourceIPAddress": "192.0.2.255", "userAgent": "ec2-api-tools1.6.12.2", "requestParameters": { "instancesSet": { "items": [ { "instanceId": "i-abcde123" } ] } }, "responseElements": { "instancesSet": { "items": [ { "instanceId": "i-abcde123", "currentState": { "code": 0, "name": "pending" }, "previousState": { "code": 80, "name": "stopped" } } ] } } } ``` 範例 JSON 事件包含一個名為 `userIdentity` 的物件。`userIdentity` 包含名為 `type` 的欄位。若要使用點符號表示 `type` 的值，您可以使用 `userIdentity.type`。 範例 JSON 事件包含展平為巢狀欄位名稱和值清單的陣列。若要表示 `requestParameters.instancesSet` 中第一個項目 `instanceId` 的值，您可以使用 `requestParameters.instancesSet.items.0.instanceId`。放置在欄位 `instanceID` 前的數字 `0` 指的是欄位 `items` 的值的位置。下列範例包含一個程式碼片段，顯示如何存取 JSON 日誌事件中的巢狀 JSON 欄位。 **範例：查詢** ``` fields @timestamp, @message | filter requestParameters.instancesSet.items.0.instanceId="i-abcde123" | sort @timestamp desc ``` 該程式碼片段顯示了一個查詢，該查詢使用帶有 `filter` 命令的點符號來存取巢狀 JSON 欄位 `instanceId` 的值。查詢會篩選出 `instanceId` 值等於 `"i-abcde123"` 的消息，並傳回包含指定值的所有日誌事件。 **注意** CloudWatch Logs Insights 最多可從 JSON 日誌中擷取 200 個日誌事件欄位。針對未擷取的額外欄位，可以使用 `parse` 命令來擷取訊息欄位中原始未剖析日誌事件的欄位。如需有關 `parse` 命令的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的[查詢語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)。 # 建立欄位索引以改善查詢效能並減少掃描磁碟區 您可以在日誌事件中建立欄位*的欄位索引*，以進行以等式為基礎的高效率搜尋。當您接著在 CloudWatch Logs Insights 查詢中使用欄位索引時，查詢會嘗試略過處理已知不包含索引欄位的日誌事件。這可減少使用欄位索引的查詢掃描量，因此可以更快地傳回結果。這可協助您在數千個日誌群組中快速搜尋總日誌數 PB，並更快速地在相關日誌上進行搜尋。要編製索引的良好欄位是您通常需要查詢的欄位。具有高基數值的欄位也是欄位索引的良好候選項目，因為使用這些欄位索引的查詢會更快完成，因為它會限制與目標值相符的日誌事件。 例如，假設您已建立 的欄位索引`requestId`。然後，該日誌群組 CloudWatch Logs 上包含`requestId = value`或`requestId IN [value, value, ...]`將嘗試僅處理已知包含該索引欄位和查詢值的日誌事件，且該 CloudWatch Logs 在過去已偵測到該欄位的值。 您也可以利用欄位索引來建立更多日誌群組的有效查詢。當您在查詢中使用 `filterIndex`命令而非 `filter`命令時，查詢會在具有欄位索引的日誌事件上針對選取的日誌群組執行。這些查詢最多可以掃描 10，000 個您選擇的日誌群組，方法是指定最多五個日誌群組名稱字首。如果這是 CloudWatch 跨帳戶可觀測性的監控帳戶，您可以選擇所有來源帳戶或指定個別來源帳戶來選取日誌群組。 索引欄位區分大小寫。例如， 的欄位索引與包含 的日誌事件`RequestId`不相符`requestId`。 欄位索引僅支援 JSON 和服務日誌的結構化日誌格式。 CloudWatch Logs 為標準日誌類別中的所有日誌群組提供預設欄位索引。預設欄位索引會自動用於下列欄位： + `@logStream` + `@aws.region` + `@aws.account` + `@source.log` + `@data_source_name` + `@data_source_type` + `@data_format` + `traceId` + `severityText` + `attributes.session.id` CloudWatch Logs 也為特定資料來源名稱和類型組合提供預設欄位索引。預設欄位索引會自動用於下列資料來源名稱和類型組合： | 資料來源名稱和類型 | 預設欄位索引 | | --- | --- | | `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` | | `amazon_route53.resolver_query` | `query_type` `transport` `rcode` | | `aws_waf.access` | `action` `httpRequest.country` | | `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` | 預設欄位索引是附加於您在政策中定義的任何自訂欄位索引。預設欄位索引不會計入您的[欄位索引配額](CloudWatchLogs-Field-Indexing-Syntax.md)。 CloudWatch Logs 只會將建立索引政策後擷取的日誌事件編製索引。它不會為建立政策之前擷取的日誌事件編製索引。建立欄位索引之後，每個相符的日誌事件都會從日誌事件的擷取時間開始保持索引 30 天。 **注意** 如果您在監控帳戶中建立欄位索引政策，該政策不會用於連結來源帳戶中的日誌群組。欄位索引政策僅適用於建立該政策的帳戶。 本節中的其餘主題說明如何建立欄位索引。如需有關在查詢中參考欄位索引的資訊，請參閱 [filterIndex](CWL_QuerySyntax-FilterIndex.md)和 [篩選條件](CWL_QuerySyntax-Filter.md)。 **Topics** + [欄位索引語法和配額](CloudWatchLogs-Field-Indexing-Syntax.md) + [建立帳戶層級欄位索引政策](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md) + [建立日誌群組層級欄位索引政策](CloudWatchLogs-Field-Indexing-CreateLogGroupLevel.md) + [建立查詢時的日誌群組選取選項](Field-Indexing-Selection.md) + [刪除欄位索引政策的效果](CloudWatchLogs-Field-Indexing-Deletion.md) # 欄位索引語法和配額 您可以透過建立欄位索引*政策來建立欄位索引*。您可以建立套用至整個帳戶的帳戶層級索引政策，也可以建立僅適用於單一日誌群組的政策。對於整個帳戶的索引政策，您可以有一個適用於帳戶中所有日誌群組的索引政策。您也可以建立套用到帳戶中日誌群組子集的帳戶層級索引政策，由其日誌群組名稱的字首選取。如果您在同一個帳戶中有多個帳戶層級政策，則這些政策的日誌群組名稱字首無法重疊。同樣地，您可以建立套用至特定資料來源名稱和類型組合的帳戶層級索引政策。每個資料來源名稱和類型組合只能建立一個帳戶政策。 日誌群組層級欄位索引政策會覆寫帳戶層級欄位索引政策：整體套用至日誌群組 （例如，沒有選取條件或日誌群組名稱字首型選取條件的帳戶層級政策）。除了符合整體日誌群組的政策之外，還會套用符合日誌事件層級的帳戶層級政策 （例如，指定資料來源名稱和類型組合）。如果您建立日誌群組層級索引政策，則該日誌群組不會使用與日誌群組層級相符的帳戶層級政策。 日誌事件與欄位索引名稱的比對會區分大小寫。例如， 的欄位索引與包含 的日誌事件`RequestId`不相符`requestId`。 您最多可以有 40 個帳戶層級索引政策，其中 20 個政策可以使用日誌群組名稱字首選擇條件，而 20 個政策可以使用資料來源型選擇條件。如果您有多個帳戶層級索引政策篩選為日誌群組名稱字首，則其中沒有任何兩個政策可以使用相同或重疊的日誌群組名稱字首。例如，如果您有一個政策篩選為以 開頭的日誌群組`my-log`，則您無法將另一個欄位索引政策篩選為 `my-logpprod`或 `my-logging`。同樣地，如果您有多個帳戶層級索引政策篩選為資料來源名稱和類型組合，則其中沒有任何兩個政策可以使用相同的資料來源名稱和類型。例如，如果您有一個政策篩選為資料來源名稱`amazon_vpc`和資料來源類型`flow`，則無法使用此組合建立另一個政策。 如果您的帳戶層級索引政策沒有名稱字首且適用於所有日誌群組，則無法建立具有日誌群組名稱字首篩選條件的其他帳戶層級索引政策；您可以建立使用資料來源名稱和類型篩選條件的帳戶層級索引政策。 每個索引政策都有下列配額和限制： + 政策最多可包含 20 個欄位。 + 每個欄位名稱最多可包含 100 個字元。 + 若要在以 開頭的日誌群組中建立自訂欄位的索引`@`，您必須在欄位名稱的`@`開頭指定具有額外 的欄位。例如，如果您的日誌事件包含名為 的欄位`@userId`，您必須指定 `@@userId` 為此欄位建立索引。 對於具有資料來源名稱和類型型選取條件的帳戶層級索引政策，會套用額外的限制：所有欄位都必須是基本資料類型，結構僅支援巢狀基本。 **產生的欄位和預留欄位** CloudWatch Logs Insights 會在每個日誌事件中自動產生系統欄位。這些產生的欄位字首為 `@`，如需所產生欄位的詳細資訊，請參閱 [支援的日誌和探索的欄位](CWL_AnalyzeLogData-discoverable-fields.md)。 在這些產生的欄位中，支援使用下列項目做為欄位索引： + `@logStream` + `@ingestionTime` + `@requestId` + `@type` + `@initDuration` + `@duration` + `@billedDuration` + `@memorySize` + `@maxMemoryUsed` + `@xrayTraceId` + `@xraySegmentId` 若要為這些產生的欄位編製索引，您不需要在指定`@`時新增額外的 ，因為您必須對開頭為 的自訂欄位執行此操作`@`。例如，若要建立 的欄位索引`@logStream`，只要指定 `@logStream`做為欄位索引即可。 CloudWatch Logs 為標準日誌類別中的所有日誌群組提供預設欄位索引。預設欄位索引會自動用於下列欄位： + `@logStream` + `@aws.region` + `@aws.account` + `@source.log` + `@data_source_name` + `@data_source_type` + `@data_format` + `traceId` + `severityText` + `attributes.session.id` CloudWatch Logs 也為特定資料來源名稱和類型組合提供預設欄位索引。預設欄位索引會自動用於下列資料來源名稱和類型組合： | 資料來源名稱和類型 | 預設欄位索引 | | --- | --- | | `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` | | `amazon_route53.resolver_query` | `query_type` `transport` `rcode` | | `aws_waf.access` | `action` `httpRequest.country` | | `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` | 預設欄位索引是附加於您在政策中定義的任何自訂欄位索引。預設欄位索引不會計入您的[欄位索引配額](#CloudWatchLogs-Field-Indexing-Syntax)。 **JSON 日誌中的子欄位和陣列欄位** 您可以在 JSON 日誌中為巢狀子欄位或陣列欄位的欄位編製索引。 例如，您可以在此日誌的 欄位內建立`accessKeyId`子`userIdentity`欄位的索引： ``` { "eventVersion": "1.0", "userIdentity": { "type": "IAMUser", "principalId": "EXAMPLE_PRINCIPAL_ID", "arn": "arn: aws: iam: : 123456789012: user/Alice", "accessKeyId": "11112222", "accountId": "123456789012", "userName": "Alice" }, "eventTime": "2014-03-06T21: 22: 54Z", "eventSource": "ec2.amazonaws.com", "eventName": "StartInstances", "awsRegion": "us-east-2", "sourceIPAddress": "192.0.2.255", "userAgent": "ec2-api-tools1.6.12.2", "requestParameters": { "instancesSet": { "items": [{ "instanceId": "i-abcde123", "currentState": { "code": 0, "name": "pending" }, "previousState": { "code": 80, "name": "stopped" } }] } } } ``` 若要建立此欄位，您可以在建立欄位索引和在查詢中指定欄位索引時，使用點符號 (`userIdentity.accessKeyId`) 來參考它。查詢可能如下所示： ``` fields @timestamp, @message | filterIndex userIdentity.accessKeyId = "11112222" ``` 在先前的範例事件中， `instanceId` 欄位位於 陣列中 `requestParameters.instancesSet.items` 若要在建立欄位索引時和查詢時都代表此欄位，請將其稱為 `requestParameters.instancesSet.items.0.instanceId` 0，表示該欄位在陣列中的位置。 然後，此欄位的查詢可以是下列項目： ``` fields @timestamp, @message | filterIndex requestParameters.instancesSet.items.0.instanceId="i-abcde123" ``` # 建立帳戶層級欄位索引政策 使用本節中的步驟來建立欄位索引政策，該政策會套用至帳戶中的所有日誌群組，或套用至具有以相同字串開頭之日誌群組名稱的多個日誌群組。 **建立帳戶層級欄位索引政策** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在左側導覽窗格中，選擇**設定**，然後選擇**日誌**索引標籤。 1. 在**帳戶層級索引政策**區段中，選擇**管理**。 1. 選擇**建立索引政策**。 1. 在**政策名稱**中，輸入新政策的名稱。 1. 對於**選取政策範圍**，請執行下列其中一項操作： + 選擇**所有標準日誌群組**，讓索引政策套用至帳戶中的所有標準類別日誌群組。 + **依字首比對選擇日誌群組**，將政策套用至名稱以相同字串開頭的日誌群組子集。然後，在輸入字首**名稱中輸入這些日誌群組的字首**。 輸入字首後，您可以選擇**預覽字首相符的日誌群組**，以確認字首符合您預期的日誌群組。 選擇**依資料來源記錄資料**，將政策套用至特定資料來源名稱和類型組合。然後，您可以從下拉式選單中選取**資料來源**和**資料類型**。 選取資料來源名稱和類型後，您可以選取**取得欄位**，將可用欄位、包含的日誌群組，以及預設和自訂欄位索引等相關資訊填入**設定欄位索引和面向**區段。 1. 針對**自訂索引欄位組態**，選擇**新增欄位路徑**以輸入要索引的第一個欄位。 然後輸入要用作欄位名稱值的字串，或從下拉式功能表中選取欄位。這必須與日誌事件中顯示的內容完全相符。例如，如果您的日誌事件包含 `requestId`，則必須`requestId`在此處輸入 。`RequestId`、 `requestID`和 `request Id`不相符。 如果您想要為以 `@` 字元開頭的自訂日誌欄位編製索引，您必須在輸入索引字串時包含額外的`@`字元。例如，如果您有自訂日誌欄位 `@emailname`，`@@emailname`請在**新增欄位路徑**方塊中輸入 。 您也可以為 CloudWatch Logs 自動產生的 `@ingestionTime`和 `@logStream` 欄位建立索引。如果您這麼做，則不需要在指定`@`時新增額外的 。 1. （選用） 除了指定欄位路徑之外，您還可以選取**設定為面向**，以將欄位建立為面向。 1. 重複上一個步驟，新增多達 20 個欄位索引。 1. 當您完成時，請選擇 **Create (建立)**。 # 建立日誌群組層級欄位索引政策 使用本節中的步驟來建立套用至單一日誌群組的欄位索引政策。 **建立日誌群組層級欄位索引政策** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在左側導覽窗格中依序選擇 **Logs (日誌)** > **Log groups (日誌群組)**。 1. 選擇日誌群組的名稱。 1. 選擇**欄位索引**索引標籤。 1. 選擇**管理此日誌群組的欄位索引** 1. 針對**管理日誌群組層級欄位索引**，選擇**新增欄位路徑**以輸入要編製索引的第一個欄位。 然後輸入要用作欄位名稱值的字串。這必須與日誌事件中顯示的內容完全相符。例如，如果您的日誌事件包含 `requestId`，則必須`requestId`在此處輸入 。`RequestId`、 `requestID`和 `request Id`不相符。 如果您想要為以 `@` 字元開頭的自訂日誌欄位編製索引，您必須在輸入索引字串時包含額外的`@`字元。例如，如果您有自訂日誌欄位 `@emailname`，`@@emailname`請在**新增欄位路徑**方塊中輸入 。 您也可以為 CloudWatch Logs 自動產生的 `@ingestionTime`和 `@logStream` 欄位建立索引。如果您這麼做，則不需要在指定`@`時新增額外的 。 1. （選用） 除了指定欄位路徑之外，您還可以選取**設定為面向**，將欄位建立為面向。 1. 重複上一個步驟，新增多達 20 個欄位索引。 1. 完成後，請選擇 **Save (儲存)**。 # 建立查詢時的日誌群組選取選項 本節說明您可以選取要包含在查詢中的日誌群組的各種方式。 **在主控台中選取查詢的日誌群組** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**日誌**，然後選擇 **Logs Insights**。 1. 選取您要用於此查詢的查詢語言。您可以選擇：**Logs Insights QL**、**OpenSearch PPL** 或 **OpenSearch SQL**。 1. 有三種方式可以選取查詢的日誌群組： + 使用**日誌群組名稱**方塊。這是預設選擇方法。您可以使用此方法輸入最多 50 個日誌群組名稱。如果這是 CloudWatch 跨帳戶觀察功能中的監控帳戶，您可以在來源帳戶和監控帳戶中選取日誌群組。單一查詢可以一次查詢來自不同帳戶的日誌。 + 使用**日誌群組條件**區段。在本節中，您可以根據日誌群組名稱的字首選擇日誌群組。您可以在一個查詢中包含最多五個字首。將會選取名稱中具有這些字首的日誌群組。或者，**所有日誌群組**選項會從帳戶選取所有日誌群組。 + 如果這是 CloudWatch 跨帳戶可觀測性的監控帳戶，您可以在帳戶下拉式功能表中選取**所有**帳戶，從所有連結帳戶中選取日誌群組。或者，您可以個別選取此查詢應包含哪些帳戶。 如果您的選擇符合超過 10，000 個日誌群組，您會看到錯誤，提示您縮小選擇範圍。 1. 查詢的預設日誌類別為**標準**。您可以使用**日誌類別**將其變更為**不常存取**。 **使用 AWS CLI** 若要在從命令列啟動查詢時進行這些類型的選擇，您可以在查詢中使用 `source`命令。如需詳細資訊和範例，請參閱 [SOURCE](CWL_QuerySyntax-Source.md)。 # 刪除欄位索引政策的效果 如果您刪除已生效一段時間的欄位索引政策，會發生下列情況： + 在刪除政策後最多 30 天內，查詢仍然可以從索引日誌事件中受益。 + 如果您刪除日誌群組層級索引政策，且已有適用於該日誌群組的帳戶層級政策，則帳戶層級政策最終會套用至該日誌群組。 # 使用面向來分組和探索日誌 面向有助於分析日誌，因為它們可讓您以互動方式篩選和分組資料，而無需執行查詢。面向是日誌中的欄位 （例如 `ServiceName`或 `StatusCode`)，可啟用跨日誌群組的篩選、彙總和分析。您可以在 CloudWatch Logs Insights 主控台中檢視面向欄位的清單，以及根據您選取的時間範圍，每個面向值的日誌事件計數。當您選取不同的面向和值時，面向值和計數會即時更新，讓您以互動方式探索日誌。 每個面向都會根據選取的時間範圍和查詢範圍，顯示日誌中欄位自動擷取的可用值和計數，並保留 30 天。顯示的面向計數為近似值。您可以使用資料來源名稱或資料來源類型等預設面向來探索日誌，或在日誌中的任何欄位上建立自訂面向。資料來源名稱是產生日誌的 AWS 服務或應用程式 （例如 Route 53、Amazon VPC 或 CloudTrail)，而資料來源類型是該服務產生的特定日誌類型。預設面向由 CloudWatch 建立，並包含 `@aws.region`、`@data_source_type`、 `@data_source_name`和 `@data_format`。如需詳細資訊，請參閱[日誌管理](LogManagement.md)。面向僅適用於帳戶中導入的日誌。如果您已設定跨帳戶可觀測性，監控帳戶將無法根據來源帳戶的日誌檢視面向。 若要建立其他面向，請選取日誌中與您的故障診斷相關的欄位，並使用索引政策進行設定。對於自訂面向，我們建議在低基數欄位上建立它們 （每天小於 100 個唯一值的欄位，例如狀態和 ApplicationName)。每天有超過 100 個唯一值的構面會分類為高基數，且不會顯示這些構面的值。選取一或多個面向，然後按一下以跨日誌執行查詢。 若要開始使用 CloudWatch Logs Insights 中的面向： 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**日誌**，然後選擇 **Logs Insights**。 1. （選用） 使用時間範圍選擇器來選取您要分析的時段。對於選取的時間範圍，可用的面向和值會顯示在面板中。 1. 選取構面以探索您的資料，並查看各個構面中值分佈的即時更新。 不會顯示具有超過 100 個唯一值的面向。若要查詢特定值，請改為在查詢中使用篩選條件。 ## 執行面向型查詢 1. 跨面向選取一或多個值。 1. 事件計數會根據選取的面向和值更新。 1. 選取面向值時，查詢範圍會更新以反映選擇。 1. 選取面向值後，按一下執行以執行查詢。 1. 每個面向支援的唯一值數目上限為 100。例如，如果面向有 100 個以上的值，則所有計數會顯示為 "-"，表示值未知。 ## 儲存面向型查詢 1. 使用一或多個面向值建立查詢。 1. 其餘步驟與儲存 Logs Insights 查詢相同。請參閱[儲存 CloudWatch Logs Insights 查詢](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.html)。 1. 您儲存的查詢可在儲存的查詢區段中取得。當您擷取已儲存的查詢時，它會自動包含用於查詢的面向和值，讓您輕鬆分析日誌。 ## 建立帳戶層級面向 1. 若要建立面向，您必須先建立 欄位做為索引，並將其設定為面向。在導覽窗格中，選擇**設定**、**日誌**、**帳戶層級索引政策**。或者，您可以在**面向面板上選取管理**面向。 1. 選擇**建立新的索引政策**。如需建立索引政策的詳細資訊，請參閱 [建立帳戶層級欄位索引政策](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md)。 1. 若要建立面向，請在索引政策建立頁面中勾選將選定欄位**設為面向**。 ## 使用 APIs面向管理 您可以使用欄位索引政策來完成面向管理。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html) API。 APIs **欄位索引 APIs** | 否。 | 名稱 | 描述 | | --- | --- | --- | | 1 | PutIndexPolicy | 建立或更新特定日誌群組的欄位索引政策 | | 2 | PutAccountPolicy | 建立帳戶層級資料保護政策、訂閱篩選條件政策、欄位索引政策、轉換器政策或指標擷取政策，適用於帳戶中的所有日誌群組或日誌群組子集 | | 3 | DeleteIndexPolicy | 刪除套用至單一日誌群組的日誌群組層級欄位索引政策 | | 4 | DeleteAccountPolicy | 刪除 CloudWatch Logs 帳戶政策 | # 模式分析 CloudWatch Logs Insights 會使用機器學習演算法來尋找*模式*。模式是在您的日誌欄位之間重複出現的共用文字結構。當您檢視查詢的結果時，您可以選擇**模式**索引標籤，以查看 CloudWatch Logs 根據結果範例找到的模式。或者，您可以將 `pattern`命令附加至查詢，以分析整組相符日誌事件中的模式。 模式有助於分析大型日誌集，因為大量日誌事件通常可以壓縮為幾個模式。 請考慮以下三個日誌事件的範例。 ``` 2023-01-01 19:00:01 [INFO] Calling DynamoDB to store for resource id 12342342k124-12345 2023-01-01 19:00:02 [INFO] Calling DynamoDB to store for resource id 324892398123-12345 2023-01-01 19:00:03 [INFO] Calling DynamoDB to store for resource id 3ff231242342-12345 ``` 在先前的範例中，這三個日誌事件都遵循一個模式： ``` [INFO] Calling DynamoDB to store for resource id ``` 模式內的欄位稱為*字符*。模式內不同的欄位，例如請求 ID 或時間戳記，都是*動態字符*。每個動態字符都由 表示``。*字串*是字符所代表資料類型的描述。此*數字*顯示與其他動態字符相比，此字符在模式中的顯示位置。 動態字符的常見範例包括錯誤代碼、時間戳記和請求 IDs。*權杖值*代表動態權杖的特定值。例如，如果動態字符代表 HTTP 錯誤代碼，則字符值可以是 `501`。 模式偵測也用於 CloudWatch Logs 異常偵測器並比較功能。如需詳細資訊，請參閱[日誌異常偵測](LogsAnomalyDetection.md)及[比較 （差異） 與先前的時間範圍](CWL_AnalyzeLogData_Compare.md)。 ## 模式分析入門 模式偵測會在任何 CloudWatch Logs Insights 查詢中自動執行。不包含 `pattern`命令的查詢會在結果中同時取得日誌事件和模式。 如果您在查詢中包含 `pattern`命令，則會對整組相符的日誌事件執行模式分析。這可提供更準確的模式結果，但當您使用 `pattern`命令時，不會傳回原始日誌事件。當查詢不包含 時`pattern`，模式結果會根據前 1000 個傳回的日誌事件，或是您在查詢中使用的限制值。如果您在查詢`pattern`中包含 ，則**模式**索引標籤中顯示的結果會衍生自查詢相符的所有日誌事件。 **在 CloudWatch Logs Insights 中開始使用模式分析** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**日誌**，然後選擇 **Logs Insights**。 在 **Logs Insights** (日誌洞察) 頁面上，查詢編輯器包含會傳回 20 筆最新日誌事件的預設查詢。 1. 移除查詢方塊中的`| limit 20`行，讓查詢如下所示： ``` fields @timestamp, @message, @logStream, @log | sort @timestamp desc ``` 1. 在**選取日誌群組 (Select log group) **下拉式清單中，選擇要查詢的一或多個日誌群組。 1. (選用) 使用時間間隔選擇器，選取您要查詢的時間段。 您可以選擇 5 分鐘和 30 分鐘間隔；1 小時、3 小時和 12 小時間隔；或自訂時間範圍。 1. 選擇**執行查詢**以開始查詢。 當查詢完成執行時，**日誌**索引標籤會顯示查詢傳回的日誌事件資料表。表格上方是有關有多少筆記錄符合查詢的訊息，類似於**顯示 71，101 筆記錄中有 10，000 筆符合**。 1. 選擇**模式**索引標籤。 1. 資料表現在會顯示查詢中找到的模式。由於查詢不包含 `pattern`命令，此標籤只會顯示 10，000 個日誌事件中探索到的模式，這些事件會顯示在**日誌**標籤的表格中。 對於每個模式，會顯示下列資訊： + **模式**，每個動態字符都顯示為 ``。*字串*是字符所代表資料類型的描述。此*數字*顯示與其他動態字符相比，此字符在模式中的顯示位置。 + **事件計數**，這是模式出現在查詢日誌事件中的次數。選擇**事件計數**欄標題，依頻率排序模式。 + **事件比率**，即包含此模式的查詢日誌事件百分比。 + **嚴重性類型**，將是下列其中一項： + 如果模式包含**錯誤**一詞，則為**錯誤**。 + 如果模式包含**警告**一詞，但不包含**錯誤**，請**警告** 。 + 如果模式不包含**警告**或**錯誤**，**則為 INFO**。 選擇**嚴重性資訊**欄標題，依嚴重性排序模式。 1. 現在變更查詢。將查詢中的 `| sort @timestamp desc`行取代為 `| pattern @message`，讓完整的查詢如下所示： ``` fields @timestamp, @message, @logStream, @log | pattern @message ``` 1. 選擇 **Run query** (執行查詢)。 查詢完成時，**日誌**索引標籤中沒有結果。不過，根據查詢的日誌事件總數，**模式**索引標籤可能列出更多模式。 1. 無論您是否包含在查詢`pattern`中，都可以進一步檢查查詢傳回的模式。若要這樣做，請在**檢查**欄中選擇其中一個模式的圖示。 **模式檢查**窗格隨即出現，並顯示下列項目： + **模式**。在模式中選取權杖，以分析該權杖的值。 + 顯示查詢時間範圍內模式出現次數的長條圖。這可協助您識別有趣的趨勢，例如模式的出現突然增加。 + **日誌範例**索引標籤會顯示一些符合所選模式的日誌事件。 + 如果您已選取動態**權杖，權杖值**索引標籤會顯示所選動態權杖的值。 **注意** 每個字符最多擷取 10 個字符值。字符計數可能不精確。CloudWatch Logs 使用機率計數器來產生字符計數，而不是絕對值。 + **相關模式**索引標籤會顯示與您檢查的模式幾乎同時經常發生的其他模式。例如，如果`ERROR`訊息的模式通常伴隨另一個標記為 的日誌事件`INFO`和其他詳細資訊，則此模式會顯示在此處。 ## 模式命令的詳細資訊 本節包含有關 `pattern`命令及其用途的更多詳細資訊。 + 在先前的教學課程中，我們在新增 時移除 `sort`命令，`pattern`因為如果查詢在`sort`命令之後包含`pattern`命令，則查詢無效。在 `pattern`之前擁有 是有效的`sort`。 如需`pattern`語法的詳細資訊，請參閱 [pattern](CWL_QuerySyntax-Pattern.md)。 + 當您`pattern`在查詢中使用 時， `@message` 必須是在 `pattern`命令中選取的其中一個欄位。 + 您可以在`filter`命令之前包含 `pattern`命令，只讓篩選過的日誌事件集做為模式分析的輸入。 + 若要查看特定欄位的模式結果，例如衍生自`parse`命令的欄位，請使用 `pattern @fieldname`。 + 使用非日誌輸出的查詢，例如使用 `stats`命令的查詢，不會傳回模式結果。 # 儲存並重新執行 CloudWatch Logs Insights 查詢 建立查詢之後，可以儲存該查詢，以便之後再次執行。查詢會儲存在資料夾結構中，因此您可以組織它們。每個區域和每個帳戶最多可儲存 1000 個查詢。 查詢會儲存在區域特定層級，而非使用者特定層級。如果您建立並儲存查詢，在同一區域中具有 CloudWatch Logs 存取權的其他使用者可以查看該區域中所有已儲存的查詢及其資料夾結構。 若要儲存查詢，您必須登入具有許可 `logs:PutQueryDefinition` 的角色。若要查看已儲存查詢的清單，您必須登入具有許可 `logs:DescribeQueryDefinitions` 的角色。 **注意** 您可以使用 參數建立和儲存查詢 — 具有具名預留位置的可重複使用範本。與其使用不同的值儲存相同查詢的多個變化，請建立一個範本，並在執行時提供不同的參數值。此功能目前僅支援使用 Logs Insights 查詢語言的查詢。如需詳細資訊，請參閱[搭配參數使用已儲存的查詢](#CWL_Insights-Parameterized-Queries)。 ------ #### [ Console ] **儲存查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 在查詢編輯器中，建立查詢。 1. 選擇**儲存**。 1. 輸入查詢的名稱。 1. (選用) 選擇您要儲存查詢的資料夾。選取 **Create new (新建)** 以建立資料夾。如果您建立新資料夾，您可以在資料夾名稱中使用斜線 (/) 字元，以定義資料夾結構。例如，命名新資料夾 **folder-level-1/folder-level-2** 會建立名為 **folder-level-1** 的頂層資料夾，該資料夾中會有另一個資料夾名為 **folder-level-2**。查詢會儲存在 **folder-level-2** 中。 1. (選用) 變更查詢的日誌群組或查詢文字。 1. （選用） 若要在查詢中使用參數，請遵循下列其他步驟： 1. **將參數新增至查詢。**使用`{{parameter}}`語法 （參數名稱前後的雙括號） 將靜態值取代為預留位置。 範例：具有靜態值的原始查詢： ``` fields @timestamp, @message | filter level = "Error" | filter applicationName = "OrderService" ``` 使用參數更新查詢： ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 1. **定義查詢中使用的參數。**針對每個預留位置參數，指定： + **名稱**：必須與預留位置名稱完全相符 （例如，`logLevel`、`applicationName`)。 + **預設值** （選用）：如果未提供參數值，要使用的值。 + **描述** （選用）：說明 參數的用途。 1. 您可以使用具有 `$`字首的查詢名稱，並將參數名稱做為索引鍵/值對傳遞，來執行具有參數的查詢。如需詳細資訊**，請參閱執行已儲存的查詢**。 1. 選擇**儲存**。 ------ #### [ AWS CLI ] **若要儲存查詢**，請使用 `put-query-definition`： ``` aws logs put-query-definition \ --name "ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` （選用） 若要使用參數儲存查詢，請新增 `--parameters`選項，並在查詢字串中使用`{{parameterName}}`預留位置： ``` aws logs put-query-definition \ --name "ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \ --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` 若要將查詢儲存在資料夾中，請在查詢名稱前面加上資料夾路徑： ``` aws logs put-query-definition \ --name "my-folder/ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \ --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` ------ #### [ API ] **若要儲存查詢**，請呼叫 [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)： ``` { "name": "ErrorsByLevel", "queryString": "fields @timestamp, @message | filter level = \"ERROR\"", "logGroupNames": ["/aws/lambda/my-function"] } ``` （選用） 若要使用參數儲存查詢，請在查詢字串中包含 `parameters` 欄位並使用`{{parameterName}}`預留位置： ``` { "name": "ErrorsByLevel", "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}", "logGroupNames": ["/aws/lambda/my-function"], "parameters": [ { "name": "logLevel", "defaultValue": "ERROR", "description": "Log level to filter" }, { "name": "applicationName", "defaultValue": "OrderService", "description": "Application name to filter" } ] } ``` ------ **提示** 您可以使用 `PutQueryDefinition` 建立已儲存查詢的資料夾。若要為儲存的查詢建立資料夾，請使用正斜線 (/) ，在所需查詢名稱前加上想要的資料夾名稱：`/`。如需有關此動作的詳細資訊，請參閱 [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)。 ------ #### [ Console ] **執行已儲存的查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 選擇右側的 **Queries (查詢)**。 1. 從**已儲存的查詢清單中選取您的查詢**。查詢文字會出現在查詢編輯器中。 1. （選用） 若要搭配參數使用查詢： 1. 在**已儲存查詢**側邊面板中選擇查詢名稱旁的 **\$1** 圖示。 1. 具有參數的查詢會出現在查詢編輯器中。例如，如果您選擇 旁的 **\$1** 圖示`ErrorsByLevel`，查詢編輯器會填入： `$ErrorsByLevel(level=, applicationName=)` 1. 提供參數 (level、applicationName) 的值並執行查詢。例如：`$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. 選擇**執行**。 ------ #### [ AWS CLI ] **使用參數執行已儲存的查詢** `start-query` 搭配 `$QueryName()` 語法使用： ``` aws logs start-query \ --log-group-names "/aws/lambda/my-function" \ --start-time 1707566400 --end-time 1707570000 \ --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \ --region us-east-1 ``` ------ #### [ API ] **使用參數執行已儲存的查詢** 使用 `queryString` 欄位中的`$QueryName()`語法呼叫 [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)： ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **儲存新版本的已儲存查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 選擇右側的 **Queries (查詢)**。 1. 從 **Saved queries (已儲存的查詢)** 清單中選取查詢。它會出現在查詢編輯器中。 1. 修改查詢。如果您需要執行該功能以檢查您的工作，請選擇 **Run query (執行查詢)**。 1. 當您準備好儲存新版本，請選擇 **Actions (動作)**、**Save as (另存新檔)**。 1. 輸入查詢的名稱。 1. (選用) 選擇您要儲存查詢的資料夾。選取 **Create new (新建)** 以建立資料夾。如果您建立新資料夾，您可以在資料夾名稱中使用斜線 (/) 字元，以定義資料夾結構。例如，命名新資料夾 **folder-level-1/folder-level-2** 會建立名為 **folder-level-1** 的頂層資料夾，該資料夾中會有另一個資料夾名為 **folder-level-2**。查詢會儲存在 **folder-level-2** 中。 1. (選用) 變更查詢的日誌群組或查詢文字。 1. 選擇**儲存**。 若要刪除查詢，您必須登入具備 `logs:DeleteQueryDefinition` 許可的角色。 **編輯或刪除已儲存的查詢** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 選擇右側的 **Queries (查詢)**。 1. 從 **Saved queries (已儲存的查詢)** 清單中選取查詢。它會出現在查詢編輯器中。 1. 選擇 **Actions (動作)**、**Edit (編輯)** 或 **Actions (動作)**、**Delete (刪除)**。 ## 搭配參數使用已儲存的查詢 具有參數的已儲存查詢是具有具名預留位置的可重複使用查詢範本。您可以儲存範本並在執行查詢時提供不同的參數值，而不是維護幾乎相同的查詢的多個副本。只有 CloudWatch Logs Insights 查詢語言才支援參數。 **運作方式** 儲存查詢時，預留位置會識別您可以在查詢執行時間提供的值。預留位置使用 `{{parameterName}}` 語法。以下是名為 且`ErrorsByLevel`具有兩個參數 `logLevel`和 的已儲存查詢範例`applicationName`。 ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 若要執行儲存的查詢，您可以使用字首為 的查詢名稱來叫用它，`$`並傳遞參數值。CloudWatch Logs Insights 查詢引擎會取代每個預留位置。如果參數包含預設值，則如果未提供其他值，則會使用這些值。 ``` # Run query by using query name and passing parameter values explicitly $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") # Run query without specifying parameter values - default values are used in this case. $ErrorsByLevel() ``` 包含空格或特殊字元的已儲存查詢名稱需要用反引號括住： ``` $`Errors By Level`(logLevel = "WARN") ``` ### 具有參數的已儲存查詢範例 **新增結果限制做為參數** 查詢名稱：`ErrorsByLevel`含參數 `logLevel`（預設值：`"ERROR"`)、 `applicationName` （預設值：`"OrderService"`) 和 `maxResults`（預設值：`50`) ``` fields @timestamp, @message, @logStream | filter level = {{logLevel}} | filter applicationName = {{applicationName}} | sort @timestamp desc | limit {{maxResults}} ``` ``` # Run the query using the query name and passing parameter values $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100) ``` **搭配參數使用多個已儲存的查詢** 以下範例使用 `ErrorsByLevel`和第二個儲存的查詢`RecentN`，其定義為 `sort @timestamp desc | limit {{count}}`（使用參數 `count`，預設 `20`)。CloudWatch Logs Insights 查詢引擎會在執行前展開每個查詢。 ``` # Using multiple queries with parameters in sequence $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") | $RecentN(count = 10) # Each of the queries is expanded, resulting in the following query when it is run. fields @timestamp, @message | filter level = "WARN" | filter applicationName = "OrderService" | sort @timestamp desc | limit 10 ``` ### 配額和錯誤處理 **注意** 每個儲存的查詢最多可有 20 個參數。 展開的查詢字串不能超過 10，000 個字元。參數名稱必須以字母或底線開頭。儲存的查詢無法參考另一個儲存的查詢 （不支援巢狀調用）。 **常見錯誤** | 錯誤 | 原因 | | --- | --- | | 只有 CWLI 查詢語言才支援參數 | 只有 CloudWatch Logs Insights 查詢語言才支援參數。 | | queryString 中找不到必要的參數 | 中的參數名稱在查詢字串`{{placeholder}}`中`--parameters`沒有相符項目。 | | 參數計數超過上限 20 | 儲存的查詢目前僅支援 20 個參數。 | | 重複的參數名稱 | 查詢定義在 中有重複的參數`parameters`。 | **注意** 若要使用參數建立或更新已儲存的查詢，您需要 `logs:PutQueryDefinition`許可。若要執行一個，您需要 `logs:StartQuery`和 `logs:DescribeQueryDefinitions`。 # 將查詢新增到儀表板或匯出查詢結果 執行查詢之後，您可以將查詢新增至 CloudWatch 儀表板，或將結果複製到剪貼簿。 每次載入儀表板和每次儀表板重新整理時，會執行新增到儀表板的查詢。這些查詢會計入 100 個並行 CloudWatch Logs Insights 查詢的限制。 **將查詢結果新增到儀表板** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 選擇一或多個日誌群組並執行查詢。 1. 選擇 **Add to dashboard (新增至儀表板)**。 1. 選取儀表板，或選擇 **Create new (新建)**，為查詢結果建立儀表板。 1. 選取用於查詢結果的 Widget 類型。 1. 輸入 Widget 的名稱。 1. 選擇 **Add to dashboard (新增至儀表板)**。 **將查詢結果複製到剪貼簿或下載查詢結果** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 選擇一或多個日誌群組並執行查詢。 1. 選擇 **Export results (匯出結果)**，然後選擇您需要的選項。 # 檢視執行中的查詢或查詢歷史記錄 您可以檢視目前進行中的查詢，以及您的最新查詢歷史記錄。 目前執行中的查詢包括您已新增到儀表板的查詢。每個帳戶僅限 100 個並行 CloudWatch Logs Insights 查詢，包括新增至儀表板的查詢。此外，您可以為 OpenSearch Service PPL 或 OpenSearch Service SQL 執行 15 個並行查詢。 **檢視您的最新查詢歷史記錄** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。 1. 如果您使用新設計的 CloudWatch Logs 主控台，請選擇 **History** (歷史記錄)。如果您是使用舊設計，請選擇 **Actions (動作)**、**View query history for this account (檢視此帳戶的查詢歷程記錄)**。 隨即顯示您的最新查詢清單。您可以選取查詢，並選擇 **Run (執行)**，以再次執行任一查詢。 在 **Status** (狀態) 下，CloudWatch Logs 會將目前執行中的任何查詢顯示為 **In progress** (進行中)。 # 使用 加密查詢結果 AWS Key Management Service 根據預設，CloudWatch Logs 會使用 CloudWatch Logs 伺服器端預設的加密方法，加密您 CloudWatch Logs Insights 查詢所儲存的結果。您可以選擇改用 AWS KMS 金鑰來加密這些結果。如果您將 AWS KMS 金鑰與加密結果建立關聯，則 CloudWatch Logs 會使用該金鑰來加密帳戶中所有查詢的儲存結果。 如果您之後取消金鑰與查詢結果的關聯，CloudWatch Logs 會在日後的查詢中重新使用預設的加密方法。不過，在金鑰仍有關聯時所執行的查詢，依然會使用該金鑰來加密。由於 CloudWatch Logs 仍可繼續參照該金鑰，因此依然可在 KMS 金鑰解除關聯後傳回那些結果。然而，若之後將金鑰停用，CloudWatch Logs 就無法讀取使用該金鑰加密的日誌。 **重要** CloudWatch Logs 僅支援對稱 KMS 金鑰。切勿使用非對稱金鑰加密查詢結果。如需詳細資訊，請參閱[使用對稱和非對稱金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)。 ## 限制 + 若要執行下列步驟，您必須擁有下列許可：`kms:CreateKey`、`kms:GetKeyPolicy` 和 `kms:PutKeyPolicy`。 + 建立或取消金鑰與查詢結果的關聯後，操作會在 5 分鐘內生效。 + 如果您撤銷 CloudWatch Logs 對已關聯金鑰的存取權，或刪除所關聯的 KMS 金鑰，您將無法再擷取 CloudWatch Logs 中的加密資料。 + 您無法使用 CloudWatch 主控台為金鑰建立關聯，必須使用 AWS CLI 或 CloudWatch Logs API 才行。 ## 步驟 1：建立 AWS KMS key 若要建立 KMS 金鑰，請使用以下 [create-key](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html) 命令： ``` aws kms create-key ``` 輸出包含金鑰 ID 和金鑰的 Amazon Resource Name (ARN)。下列為範例輸出： ``` { "KeyMetadata": { "Origin": "AWS_KMS", "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "Description": "", "KeyManager": "CUSTOMER", "Enabled": true, "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "Enabled", "CreationDate": 1478910250.94, "Arn": "arn:aws:kms:us-west-2:123456789012:key/6f815f63-e628-448c-8251-e40cb0d29f59", "AWSAccountId": "123456789012", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ] } } ``` ## 步驟 2：設定 KMS 金鑰許可 根據預設，所有 KMS 金鑰皆屬私有。只有資源擁有者可以使用它來加密和解密資料。然而，資源擁有者可以授予其他使用者和資源存取金鑰的許可。在此步驟中，您會給予 CloudWatch Logs 服務主體使用金鑰的許可。此服務主體必須位於存放金鑰的相同 AWS 區域中。 根據最佳實務，建議您將金鑰的使用限制為您指定的 AWS 帳戶。 首先，使用以下 [get-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) 命令，將 KMS 金鑰的預設政策儲存為 `policy.json`： ``` aws kms get-key-policy --key-id key-id --policy-name default --output text > ./policy.json ``` 在文字編輯器中開啟 `policy.json` 檔案，並從下列其中一個陳述式中加入區段 (以粗體顯示)。使用逗號從新陳述式中分隔現有陳述式。這些陳述式使用`Condition`區段來增強 AWS KMS 金鑰的安全性。如需詳細資訊，請參閱[AWS KMS 金鑰和加密內容](encrypt-log-data-kms.md#encrypt-log-data-kms-policy)。 此範例中的 `Condition`區段會將 AWS KMS 金鑰的使用限制在指定帳戶中的 CloudWatch Logs Insights 查詢結果。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "key-default-1", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Effect": "Allow", "Principal": { "Service": "logs.region.amazonaws.com" }, "Action": [ "kms:Encrypt*", "kms:Decrypt*", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:Describe*" ], "Resource": "*", "Condition": { "ArnEquals": { "aws:SourceArn": "arn:aws:logs:us-east-1:111122223333:query-result:*" }, "StringEquals": { "aws:SourceAccount": "111122223333" } } } ] } ``` ------ 最後，使用下列 [put-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html) 命令新增更新的政策： ``` aws kms put-key-policy --key-id key-id --policy-name default --policy file://policy.json ``` ## 步驟 3：為 KMS 金鑰與您的查詢結果建立關聯 **若要為 KMS 金鑰與帳戶中的查詢結果建立關聯** 使用 [disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html) 命令，如下所示： ``` aws logs associate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*" --kms-key-id "key-arn" ``` ## 步驟 4：將金鑰與帳戶中的查詢結果取消關聯 若要取消 KMS 金鑰與查詢結果的關聯，請使用以下 [disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html) 命令： ``` aws logs disassociate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*" ``` # 從 CloudWatch Logs Insights 查詢結果產生自然語言摘要 分析日誌資料對於了解應用程式的行為至關重要，但解譯大量日誌項目可能很耗時。CloudWatch Logs Insights 現在提供自然語言摘要功能，可將複雜的查詢結果轉換為清晰、簡潔的摘要。此功能可協助您快速識別問題，並從日誌資料中取得可行的洞見。 ## 運作方式 CloudWatch Logs Insights 可以使用 Amazon Bedrock 從查詢結果產生人類可讀取的摘要。此功能支援所有 CloudWatch Logs Insights 查詢語言，並提供清晰、可行的日誌資料洞見。 ## 區域可用性和資料處理 **重要** 當您使用此功能時，您的查詢結果可能會在不同的 中處理 AWS 區域。例如，如果您在美國東部 （維吉尼亞北部） 執行查詢，則摘要可能發生在美國西部 （奧勒岡）。 下表列出查詢結果功能可用 AWS 區域 之不同地理位置的可能處理方式： | 支援的 CloudWatch Logs 地理位置 | 可能的處理區域 | | --- | --- | | 美國 (US) | 美國東部 (維吉尼亞北部) 區域 美國東部 (俄亥俄) 區域 美國西部 (奧勒岡) 區域 | | 歐洲 | 歐洲 (法蘭克福) 區域 歐洲 (愛爾蘭) 區域 歐洲 (巴黎) 區域 歐洲 (斯德哥爾摩) 區域 歐洲 (倫敦) 區域 | | 亞太區域 | 美國東部 (維吉尼亞北部) 區域 美國東部 (俄亥俄) 區域 美國西部 (奧勒岡) 區域 | | 南美洲 | 美國東部 (維吉尼亞北部) 區域 美國東部 (俄亥俄) 區域 美國西部 (奧勒岡) 區域 | ## 開始使用 **產生自然語言摘要** 1. 執行 CloudWatch Logs Insights 查詢。 1. 查詢完成後，選取**摘要結果**。 ## 許可 您必須具有下列其中一項： + `CloudWatchLogsFullAccess` 許可 + `CloudWatchLogsReadOnlyAccess` 許可 + 自訂 IAM 政策，包括 `cloudwatch:GenerateQueryResultsSummary`、 `logs:GetQueryResults``logs:DescribeQueries`和 `logs:FilterLogEvents`動作 ## 資料隱私權 您的查詢結果會安全地處理，不會用於訓練或改善 CloudWatch Logs Insights 或 Amazon Bedrock。如果您選擇使用意見回饋按鈕提供查詢結果摘要的意見回饋，您的意見回饋會指出您對 CloudWatch Logs Insights 所提供功能的滿意度。