翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# メトリクスクエリを使用して CloudWatch Metrics Insights データをクエリする
<a name="CloudWatch-using-the-metric-query"></a>

**注記**  
Amazon CloudWatch Metrics Insights はプレビュー中です。CloudWatch Metrics Insights の機能は、すべての AWS アカウントが利用できます。機能は変更される可能性があります。

 CloudWatch Metrics Insights のデータは、**[メトリクスクエリエディタ]**で `metric query` モードを選択することでクエリできます。

 CloudWatch Metrics Insights は、高性能な SQL クエリエンジンであり、これにより、メトリクスに対し大量のクエリを実行できます。これは、すべての CloudWatch メトリクス内の傾向とパターンをリアルタイムで特定するために使用できる、高速で柔軟な SQL ベースのクエリエンジンです。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]
```

 キーワードでは大文字と小文字は区別されませんが、識別子では大文字と小文字は区別されます。識別子には、メトリクスの名前、名前空間、ディメンションが含まれます。

 次の表に、クエリのキーワードとその説明を示します。


|  キーワード  |  説明  | 
| --- | --- | 
|  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 に報告された 1 つのディメンション (`InstanceId`) を持つ `CPUUtilization` メトリクスのみを一致させます。
+ 

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

   CloudWatch に `AWS/ApplicationELB` から報告された 2 つのディメンション（`LoadBalancer` と `AvailabilityZone`）を持つ `RequestCount` メトリクスのみを一致させます。

 ラベル値は一重引用符で囲む必要があります。

### エスケープ文字
<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 クエリの例を紹介します。これらの例の内のいくつかは、コンソールで既に利用可能な状態であり、**[メトリクス]** ビューで **[クエリを追加]** をクリックしてアクセスすることができます。

### 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 エージェントはアプリケーションごとに CPU 使用率のメトリクスを収集しています。このクエリは、特定のアプリケーション名について、このメトリクスの平均によるフィルタリングを行います。

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

Lambda 関数の平均実行時間上位 10 個を降順で表示

```
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-Notification-Service-での例 

```
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 には現在、次の制限があります。
+ 直近 3 時間分のデータにのみクエリを実行できます。
+ 1 つのクエリで処理できるメトリクスは 10,000 個以下です。つまり、`SELECT` 句、`FROM` 句、および `WHERE` 句が 10,000 を超えるメトリクスと一致した場合、見つかったこれらのメトリクスのうち最初の 10,000 のみがクエリによって処理されます。
+ 1 つのクエリで 500 を超える時系列を返すことはできません。これは、クエリが 500 個を超えるメトリクスを処理している場合でも、クエリ結果にすべてのメトリクスが返されるわけではないことを意味します。`ORDER BY` 句を使用すると、処理されているすべてのメトリクスがソートされます。その中から (`ORDER BY` 句に応じ) 最大値または最小値を持つ 500 個が返されます。`ORDER BY` 句を含めない場合は、一致したメトリクスの中から、どの 500 個が選択され返されるのかを制御することはできません。
+ 個別の `GetMetricData` オペレーションに含めることができるクエリは 1 つだけですが、ダッシュボードには、それぞれにクエリを 1 つ含んだ複数のウィジェットを用意することができます。