本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 ```