.*?)/ | 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)。