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

# 使用指標查詢編輯器
<a name="CloudWatch-using-the-metric-query-editor"></a>

指標查詢編輯器可讓您建置兩種類型的查詢：**指標搜尋**和**指標查詢**。**指標查詢**選項會使用 CloudWatch Metrics Insights 查詢資料。

## 常見查詢編輯器欄位
<a name="metrics-insights-common-fields"></a>

 **指標搜尋**和**指標查詢**模式都常見三個欄位。

 **常見欄位**

**Id**  
`GetMetricData` API 要求所有查詢都必須有唯一的 ID。使用此欄位來指定選擇的 ID。ID 可以包含數字、字母和底線，且必須以小寫字母開頭。如果未指定 ID，Amazon Managed Grafana 會使用下列模式產生 ID：`query[refId of the current query row]`。例如， `queryA`代表面板編輯器中的第一個查詢列。

**Period**  
期間是與特定 CloudWatch 統計資料相關聯的時間長度。期間是以秒數定義。有效值包括 1、5、10、30 或 60 的任何倍數。如果您將期間欄位保持空白或設定為 `auto`，則會根據時間範圍和 CloudWatch 保留政策自動計算。使用的公式是 `time range in seconds / 2000`，然後在根據保留移除期間之後，在預先定義的期間 【60、300、900、3600、21600、86400】 陣列中移至下一個較高的值。若要查看 Amazon Managed Grafana 使用的期間，請在**查詢編輯器中選擇顯示查詢預覽**。

**Alias (別名)**  
適用下列別名模式。      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/grafana/latest/userguide/CloudWatch-using-the-metric-query-editor.html)

# 使用指標搜尋選項
<a name="CloudWatch-using-the-metric-search"></a>

 若要在**指標搜尋**中建立有效的查詢，您必須指定命名空間、指標名稱和至少一個統計資料。如果已開啟 **Match Exact**，您也必須指定所查詢指標的所有維度。指標結構描述必須完全相符。如需詳細資訊，請參閱 [CloudWatch 搜尋表達式語法 ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/search-expression-syntax.html)。

如果關閉 **Match Exact**，您可以指定要篩選的任何維度數量。最多傳回 100 個符合您篩選條件的指標。

## 使用維度萬用字元的動態查詢
<a name="dynamic-queries-using-dimension-wildcards"></a>

 您可以針對一或多個維度值使用星號 (`*`) 萬用字元來監控指標的動態清單。

 這可協助您監控 AWS 資源的指標，例如 EC2 執行個體或容器。例如，當新執行個體建立為自動擴展事件的一部分時，它們會自動出現在圖形中，而不必追蹤新的執行個體 IDs。此功能目前限制為擷取最多 100 個指標。您可以選擇**顯示查詢預覽**，以查看為支援萬用字元而自動建置的搜尋表達式。

 根據預設，搜尋表達式的定義方式是查詢的指標必須完全符合定義的維度名稱。這表示在範例中，只會`InstanceId`傳回具有完全相同名稱維度的指標。

 若要包含已定義其他維度的指標，您可以關閉 **Match Exact**。關閉 **Match Exact** 也會建立搜尋表達式，即使您不使用萬用字元。Grafana 會搜尋任何至少符合命名空間、指標名稱和所有定義維度的指標。

## 多值範本變數
<a name="cloudwatch-multi-value-template-variables"></a>

 根據多值範本變數定義維度值時，系統會使用搜尋表達式來查詢相符指標。這可在單一查詢中使用多個範本變數。您也可以將範本變數用於關閉 **Match Exact** 選項的查詢。

 搜尋表達式目前限制為 1024 個字元，因此如果您有長的值清單，您的查詢可能會失敗。如果您想要查詢具有特定維度名稱任何值的所有指標，建議您使用星號 (`*`) 萬用字元，而非 `All`選項。

 只有維度值支援使用多值範本變數。`Metric Name` 不支援對 `Region`、 `Namespace`或 使用多值範本變數。

## 指標數學表達式
<a name="cloudwatch-metric-math-expressions"></a>

 您可以使用數學函數在 CloudWatch 指標上操作，以建立新的時間序列指標。支援算術運算子、無索引減法和其他函數，並且可以套用至 CloudWatch 指標。如需 CloudWatch 指標數學函數的詳細資訊，請參閱[使用指標數學](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html)。

 例如，若要在指標上套用算術操作，請將 ID （唯一字串） 提供給原始指標。然後，您可以使用此 ID，並在新指標的 `Expression` 欄位中對其套用算術操作。

 如果您使用 `Expression` 欄位來參考另一個查詢，例如 `queryA * 2`，則無法根據該查詢建立提醒規則。

## Period
<a name="cloudwatch-period"></a>

 期間是與特定 Amazon CloudWatch 統計資料相關聯的時間長度。期間是以秒數定義。有效值包括 1、5、10、30 或 60 的任何倍數。

如果您將期間欄位保留空白或設定為**自動**，則會根據時間範圍自動計算。使用的公式是 `time range in seconds / 2000`，然後移至預先定義期間 陣列中的下一個較高的值`[60, 300, 900, 3600, 21600, 86400]`。若要查看 Amazon Managed Grafana 使用的期間，請在**查詢編輯器中選擇顯示查詢預覽**。

## 從 Grafana 面板深度連結至 CloudWatch 主控台
<a name="deep-linking-from-grafana-panels-to-the-cloudwatch-console"></a>

 在面板中選擇時間序列會顯示內容功能表，其中包含在 ** CloudWatch 主控台中檢視**的連結。選擇該連結會開啟新標籤，帶您前往 CloudWatch 主控台，並顯示該查詢的所有指標。如果您目前尚未登入 CloudWatch 主控台，連結會將您轉送至登入頁面。提供的連結適用於任何 ， AWS 帳戶 但只有在您登入對應至 Grafana 中所選資料來源的 時 AWS 帳戶 ，才會顯示正確的指標。

 此功能不適用於以指標數學表達式為基礎的指標。

# 使用指標查詢選項來查詢 CloudWatch Metrics Insights 資料
<a name="CloudWatch-using-the-metric-query"></a>

**注意**  
Amazon CloudWatch Metrics Insights 處於預覽狀態。CloudWatch Metrics Insights 功能開放給所有 AWS 帳戶。功能可能會有所變更。

 您可以在指標查詢**編輯器**中選擇 `metric query` 模式來查詢 CloudWatch Metrics Insights 資料。

 CloudWatch Metrics Insights 是功能強大的高效能 SQL 查詢引擎，可用來大規模查詢您的指標。這是一個快速、靈活、以 SQL 為基礎的查詢引擎，您可以用來即時識別所有 CloudWatch 指標中的趨勢和模式。它使用 SQL 的方言。如需 Metrics Insights 查詢語法的詳細資訊，請參閱 [查詢語法和關鍵字](#metrics-insights-syntax-keywords)。

## 查詢語法和關鍵字
<a name="metrics-insights-syntax-keywords"></a>

CloudWatch Metrics Insights 使用 SQL 方言。下列範例顯示查詢語法。

```
SELECT FUNCTION(metricName)
FROM namespace | [ SCHEMA(namespace[, labelKey [, ...] ]) ]
     [ WHERE labelKey OPERATOR labelValue [AND|OR|([...])*] [, ...] ]
[ GROUP BY labelKey [, ...]]
[ ORDER BY FUNCTION() [DESC | ASC] ]
[ LIMIT number]
```

 關鍵字不區分大小寫，但識別符區分大小寫。識別符包括指標的名稱、命名空間和維度。

 下表提供查詢關鍵字及其描述。


|  關鍵字  |  Description  | 
| --- | --- | 
|  FUNCTION  |  必要. 指定要使用的彙總函數，並指定要查詢的指標名稱。有效值為AVG、COUNT、MAX、MIN、SUM。 | 
|  MetricName   |  必要. 例如 CPUUtilization。 | 
|  FROM  |  必要. 指定指標的來源。您可以指定包含要查詢之指標的指標命名空間，或 SCHEMA 資料表函數。有些命名空間範例是 AWS/EC2和 AWS/Lambda。 | 
|  SCHEMA  |  （選用） 篩選查詢結果，以僅顯示完全相符的指標，或不相符的指標。 | 
|  WHERE  |  （選用） 篩選結果，以僅顯示符合您指定表達式的指標。例如 WHERE InstanceType \$1= 'c3.4xlarge'。 | 
|  GROUP BY  |  （選用） 將查詢結果分組為多個時間序列。例如 GROUP BY ServiceName。 | 
|  ORDER BY  |  （選用） 指定要傳回的時間序列順序。選項為 ASC和 DESC。 | 
|  LIMIT  |  （選用） 限制要傳回的時間序列數目。 | 

下列是一些範例：
+ 

  ```
  SELECT AVG(CPUUtilization) FROM "AWS/EC2" 
  ```

   符合`AWS/EC2`命名空間中的所有`CPUUtilization`指標、忽略其維度，並傳回單一彙總時間序列。
+ 

  ```
  SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2")
  ```

   僅比對`AWS/EC2`命名空間中未定義任何維度的`CPUUtilization`指標。
+ 

  ```
  SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId)
  ```

   只比對回報給 CloudWatch 的`CPUUtilization`指標，且只有一個維度 `InstanceId`。
+ 

  ```
  SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer,
  AvailabilityZone)
  ```

   僅處理從 向 CloudWatch 報告的`RequestCount`指標，`AWS/ApplicationELB`只有兩個維度 `LoadBalancer`和 `AvailabilityZone`。

 標籤值必須以單引號括住。

### 逸出字元
<a name="escape-characters"></a>

在查詢中，標籤值一律必須以單引號括住。  例如 `SELECT MAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'`。

 包含字母、數字和底線 (`_`) 以外字元的指標命名空間、指標名稱和標籤索引鍵，必須以雙引號括住。例如 `SELECT MAX("My.Metric")`。如果其中一個包含雙引號本身 （例如 `Bytes"Input"`)，您必須逸出具有反斜線的雙引號，如 所示`SELECT AVG("Bytes\"Input\"")`。如果指標命名空間、指標名稱或標籤索引鍵包含在 Metrics Insights 中保留關鍵字的文字，則這些文字也必須以雙引號括住。例如，如果您的指標名為 `LIMIT`，則您可以使用 `SELECT AVG("LIMIT")`。也可以用雙引號括住任何命名空間、指標名稱或標籤，即使其不包含保留的關鍵字也一樣。

## 建置器模式和程式碼模式
<a name="metrics-insights-query-modes"></a>

您可以在 `Builder` 模式或 `Code` 模式中建立查詢。

**在 `Builder` 模式下建立查詢**

1. 使用上表中的資訊瀏覽並選取指標命名空間、指標名稱、篩選條件、群組和順序選項。

1. 對於每個選項，請從可能的選項清單中選擇。

**在 `Code` 模式下建立查詢**

1. 在程式碼編輯器中寫入您的查詢。

1. 若要執行查詢，請在程式碼編輯器中選擇**執行查詢**。

若要在 `builder` 模式中建立查詢：
+ 使用上表中的資訊瀏覽並選取指標命名空間、指標名稱、篩選條件、群組和順序選項。
+ 對於每個選項，請從可能的選項清單中選擇。

Grafana 會根據您的選擇自動建構 SQL 查詢。

 若要在 `code` 模式中建立查詢：
+ 在程式碼編輯器中寫入您的查詢。
+ 若要執行查詢，請選擇程式碼編輯器上的**執行查詢**。

程式碼編輯器具有內建的自動完成功能，可提供關鍵字、彙總、命名空間、指標、標籤和標籤值的建議。當您輸入空格、逗號或貨幣符號時，會顯示建議。您也可以使用鍵盤組合 `CTRL+Space`。

程式碼編輯器可以自動完成查詢。不過，在程式碼編輯器中使用範本變數可能會干擾自動完成。

## CloudWatch Metrics Insights 範例
<a name="goldeneye-examples"></a>

**注意**  
CloudWatch Metrics Insights 為開放預覽。預覽版開放給所有 AWS 帳戶，您不需要請求存取權。在宣布一般可用性之前，可能會新增或變更功能。

本節包含實用的 CloudWatch Metrics Insights 查詢範例，您可以直接複製和使用，或在查詢編輯器中複製和修改。部分範例已在主控台中提供，您可以藉由在 **Metrics** (指標) 檢視中選擇 **Add query** (新增查詢)，來存取這些範例。

### EC2 範例
<a name="goldeneye-EC2-examples"></a>

 檢視每個執行個體指標的 CPU 使用率

```
SELECT AVG(CPUUtilization)
FROM "AWS/EC2"
GROUP BY InstanceId
```

檢視整個機群的平均 CPU 使用率

```
SELECT AVG(CPUUtilization)
FROM SCHEMA("AWS/EC2", InstanceId)
```

 檢視平均 CPU 使用率最高的 10 個執行個體 

```
SELECT MAX(CPUUtilization)
FROM "AWS/EC2"
GROUP BY InstanceId
LIMIT 10
```

檢視 CPU 使用率最高的 10 個執行個體，依上限排序，以遞減順序排列

```
SELECT AVG(CPUUtilization)
FROM "AWS/EC2"
GROUP BY InstanceId
ORDER BY MAX() DESC
LIMIT 10
```

在此情況下，CloudWatch 代理程式會收集每個應用程式的 CPUUtilization 指標。此查詢會針對特定應用程式名稱篩選此指標的平均值。

```
SELECT AVG(CPUUtilization)
FROM "AWS/CWAgent"
WHERE ApplicationName = 'eCommerce'
SELECT AVG(ConcurrentExecutions)
FROM "AWS/Lambda"
```

檢視前 10 個 Lambda 函數的平均執行時間，依最大值排序，以遞減順序排列

```
SELECT AVG(Duration)
FROM "AWS/Lambda"
GROUP BY FunctionName
ORDER BY MAX() DESC
LIMIT 10
```

檢視 Lambda 執行時間的最大值、平均值和最小值

```
SELECT MAX(Duration)
FROM "AWS/Lambda"
```

### Application Load Balancer 範例
<a name="application-loadbalancer-examples"></a>

 檢視具有 **LoadBalancer** 和 **AvailabilityZone** 維度的指標

```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
```

檢視具有作用中並行 TCP 連線數目的指標

```
SELECT AVG(ActiveConnectionCount)
FROM "AWS/ApplicationELB"
```

### Amazon EBS 範例
<a name="Amazon-elastic-block-store-examples"></a>

 依遞減順序檢視每個磁碟區前 10 個平均寫入位元組

```
SELECT AVG(VolumeWriteBytes)
FROM "AWS/EBS"
GROUP BY VolumeId
ORDER BY MAX() DESC
LIMIT 10
```

檢視平均 Amazon EBS 磁碟區寫入時間

```
SELECT AVG(VolumeTotalWriteTime)
FROM "AWS/EBS"
```

檢視平均 Amazon EBS 磁碟區閒置時間

```
SELECT AVG(VolumeIdleTime)
FROM "AWS/EBS"
View average burst balance per volume
SELECT AVG(BurstBalance)
FROM "AWS/EBS"
GROUP BY VolumeId
View average read bytes across Amazon EBS volumes
SELECT AVG(VolumeReadBytes)
FROM "AWS/EBS"
```

檢視跨 Amazon EBS 磁碟區的平均寫入位元組

```
SELECT AVG(VolumeWriteBytes)
FROM "AWS/EBS"
```

### Amazon Simple Storage Service 範例
<a name="simple-storage-service-examples"></a>

 依儲存貯體名稱檢視平均延遲群組

```
SELECT AVG(TotalRequestLatency)
FROM "AWS/S3"
GROUP BY BucketName
```

檢視所有 Amazon S3 儲存貯體中每個儲存貯體的平均物件數量

```
SELECT AVG(NumberOfObjects)
FROM "AWS/S3"
GROUP BY BucketName
```

### Amazon Simple Notification Service 範例
<a name="Amazon-simple-notificaation-service-examples"></a>

Amazon-simple-notificaation-service-examples 

```
SELECT AVG(NumberOfMessagesPublished)
FROM "AWS/SNS"
```

檢視每個主題名稱的平均失敗訊息數量

```
SELECT AVG(NumberOfNotificationsFailed)
FROM "AWS/SNS"
GROUP BY TopicName
```

### AWS API 用量範例
<a name="AWS-API-usage-examples"></a>

依您帳戶中的呼叫數量檢視前 20 AWS APIs 

```
SELECT COUNT(CallCount)
FROM "AWS/Usage"
WHERE "Type" = 'API'
GROUP BY "Service", "Resource"
ORDER BY SUM() DESC
LIMIT 20
```

## CloudWatch Metrics Insights 限制
<a name="metrics-insights-limits"></a>

CloudWatch Metrics Insights 目前具有下列限制：
+ 您只能查詢最近三個小時的資料。
+ 單一查詢可處理不超過 10,000 個指標。這表示如果 `SELECT`、 `FROM`和 `WHERE`子句符合超過 10，000 個指標，則查詢只會處理前 10，000 個找到的這些指標。
+ 單個查詢可以傳回不超過 500 個時間序列。這表示如果查詢正在處理超過 500 個指標，則並非所有指標都會在查詢結果中傳回。如果您使用 `ORDER BY`子句，則會排序處理的所有指標，並傳回根據您的`ORDER BY`子句具有最高或最低值的 500。如果您不包含 `ORDER BY`子句，則無法控制傳回的 500 個相符指標。
+ 每個`GetMetricData`操作只能有一個查詢，但您可以在儀表板中擁有多個小工具，每個小工具都包含查詢。