# カスタムメトリクスをパブリッシュする
OpenTelemetry Protocol (OTLP) または CloudWatch API を使用して、独自のメトリクスを CloudWatch に発行できます。
## OpenTelemetry を使用してメトリクスを発行する (推奨)
新しい実装では、OpenTelemetry を使用してカスタムメトリクスを CloudWatch に発行することをお勧めします。OpenTelemetry は、ベンダーに依存しない計装に、より豊富な説明ラベルと、ゲージ、合計、ヒストグラム、指数ヒストグラムなどのメトリクスタイプのサポートを提供します。
OpenTelemetry を使用してメトリクスを発行するには、CloudWatch OTLP エンドポイントにメトリクスを送信するように OpenTelemetry Collector または SDK を設定します。OTLP を介して送信されるメトリクスは、CloudWatch Query Studio の Prometheus クエリ言語 (PromQL) を使用してクエリできます。これらのメトリクスに基づいた PromQL ベースの CloudWatch アラームを設定することもできます。
CloudWatch API アプローチとの主な違い:
| 機能 | OpenTelemetry (OTLP) | CloudWatch API (PutMetricData) |
| --- | --- | --- |
| メトリクスあたりのラベル | 最大 150 | 最大 30 個のディメンション |
| メトリクスのタイプ | ゲージ、合計、ヒストグラム、指数ヒストグラム | 単一の値、統計セット |
| 詳細度 | 送信された解像度で取り込まれている | 1 秒 (高解像度) または 1 分 (標準) |
| クエリ言語 | PromQL | GetMetricStatistics、Metrics Insights |
| アラーム | PromQL ベースの CloudWatch アラーム | 標準 CloudWatch アラーム |
| インストルメンテーション | ベンダーに依存しない OpenTelemetry SDK と Collector | AWS SDK または CLI |
開始するには、「[OpenTelemetry を使用したメトリクスの送信](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html)」を参照してください。
## CloudWatch API を使用してメトリクスを発行する
PutMetricData API または AWS CLI を使用してカスタムメトリクスを発行することもできます。このアプローチでは、CloudWatch 名前空間、メトリクス名、およびディメンションを使用します。
**Topics**
+ [OpenTelemetry を使用してメトリクスを発行する (推奨)](#publishMetricsOTLP)
+ [CloudWatch API を使用してメトリクスを発行する](#publishMetricsCWAPI)
+ [高解像度のメトリクス](#high-resolution-metrics)
+ [ディメンションを使用する](#usingDimensions)
+ [単一データポイントを公開する](#publishingDataPoints)
+ [統計セットを公開する](#publishingDataPoints1)
+ [値ゼロを公開する](#publishingZero)
+ [メトリクスの公開を停止する](#CloudWatch-Stop-Publishing-Metrics)
## 高解像度のメトリクス
各メトリクスは次のいずれかです。
+ 詳細度が 1 分のデータを含む、標準の解像度
+ 詳細度が 1 秒のデータを含む高解像度
AWS のサービスによって生成されたメトリクスは、デフォルトで標準解像度になります。カスタムメトリクスを発行するときは、標準解像度または高解像度のいずれかとして定義できます。高分解能のメトリクスをパブリッシュすると、CloudWatch はそれを 1 秒の分解能で保存します。ユーザーは、1 秒、5 秒、10 秒、30 秒、または 60 秒の倍数の期間でメトリクスを読み取り、取得できます。
高解像度メトリクスを使用すれば、アプリケーションの 1 分未満のアクティビティをより迅速に把握できます。`PutMetricData` がカスタムメトリクスを呼び出す場合、課金されることに注意してください。そのため、高解像度で `PutMetricData` を頻繁に呼び出すと、高額な料金が発生する可能性があります。CloudWatch の料金の詳細については、[Amazon CloudWatch の料金](https://aws.amazon.com/cloudwatch/pricing/)をご覧ください。
高解像度メトリクスでアラームを設定する場合、10 秒または 30 秒の期間で高解像度アラームを指定するか、60 秒の倍数の期間で通常のアラームを設定できます。10 秒または 30 秒の期間の高解像度アラームでは、料金が高くなります。
## ディメンションを使用する
カスタムメトリクスでは、`--dimensions` パラメータは一般的です。ディメンションでは、これに加えて、メトリクスの内容やメトリクスによって保存されるデータまで分かります。1 つのメトリクスには最大 30 個のディメンションを割り当てることができ、各ディメンションは名前と値のペアで定義されます。
使用するコマンドが異なる場合は、使用するディメンションも異なります。[put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html) を使用する場合は、各ディメンションを *MyName*=*MyValue* と指定しますが、[get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) または [put-metric-alarm](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-alarm.html) を使用する場合は、`Name=`*MyName*、`Value=`*MyValue* を使用します。たとえば、次のコマンドでは、「`InstanceId`」と「`InstanceType`」という名前の 2 つのディメンションを持つ「`Buffers`」メトリクスを発行します。
```
aws cloudwatch put-metric-data --metric-name Buffers --namespace MyNameSpace --unit Bytes --value 231434333 --dimensions InstanceId=1-23456789,InstanceType=m1.small
```
このコマンドは、同一メトリクスの統計情報を取得します。ディメンションが 1 つの場合は、名前と値をカンマで区切り、複数ある場合は、1 つめのディメンションと 2 つめのディメンションの間にスペースを使用します。
```
aws cloudwatch get-metric-statistics --metric-name Buffers --namespace MyNameSpace --dimensions Name=InstanceId,Value=1-23456789 Name=InstanceType,Value=m1.small --start-time 2016-10-15T04:00:00Z --end-time 2016-10-19T07:00:00Z --statistics Average --period 60
```
また、1 つのメトリクスに複数のディメンションを含む場合は、[get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) を使用するときに、定義されているディメンションごとに値を指定する必要があります。例えば、Amazon S3 メトリクス `BucketSizeBytes` に、`BucketName` と `StorageType` の 2 つのディメンションが含まれている場合は、[get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) を使用して両方のディメンションを指定する必要があります。
```
aws cloudwatch get-metric-statistics --metric-name BucketSizeBytes --start-time 2017-01-23T14:23:00Z --end-time 2017-01-26T19:30:00Z --period 3600 --namespace AWS/S3 --statistics Maximum --dimensions Name=BucketName,Value=amzn-s3-demo-bucket Name=StorageType,Value=StandardStorage --output table
```
メトリクスに定義されているディメンションを確認するには、[list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) コマンドを使用します。
## 単一データポイントを公開する
新規または既存のメトリクスに単一のデータポイントをパブリッシュするには、1 つの値とタイムスタンプで [put-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/put-metric-data.html) コマンドを呼び出します。たとえば、次のアクションはそれぞれ 1 つのデータポイントを発行しています。
```
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 2 --timestamp 2016-10-20T12:00:00.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 4 --timestamp 2016-10-20T12:00:01.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --value 5 --timestamp 2016-10-20T12:00:02.000Z
```
新しいメトリクス名でこのコマンドを呼び出すと、CloudWatch がメトリクスを作成します。そうでない場合、CloudWatch は指定した既存のメトリクスとデータを関連付けます。
**注記**
メトリクスを作成したら、[get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) コマンドを用いてその新規メトリクスの統計を取得できるようになるまで最大 2 分かかります。ただし、[list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) コマンドを用いて取得したメトリクスのリストに新規メトリクスが表示されるまでは最大 15 分かかることがあります。
粒度が 1 秒の 1,000 分の 1 のタイムスタンプでデータポイントをパブリッシュできますが、CloudWatch は、データを最小粒度の 1 秒に集約します。CloudWatch は 1 分の期間ごとに受け取った値の平均 (すべての項目の合計を項目数で割った値) と、同じ期間内のサンプル数、最大値、最小値を記録します。たとえば、前の例の `PageViewCount` メトリクスには、3 つのデータポイントで、数秒違いのタイムスタンプがあります。期間が 1 分に設定されている場合、3 つのデータポイントはタイムスタンプがすべて 1 分の期間内にあるため、CloudWatch はそれらを集約します。
パブリッシュしたデータポイントを基に、**get-metric-statistics** コマンドを用いて統計を取得できます。
```
aws cloudwatch get-metric-statistics --namespace MyService --metric-name PageViewCount \
--statistics "Sum" "Maximum" "Minimum" "Average" "SampleCount" \
--start-time 2016-10-20T12:00:00.000Z --end-time 2016-10-20T12:05:00.000Z --period 60
```
以下は出力の例です。
```
{
"Datapoints": [
{
"SampleCount": 3.0,
"Timestamp": "2016-10-20T12:00:00Z",
"Average": 3.6666666666666665,
"Maximum": 5.0,
"Minimum": 2.0,
"Sum": 11.0,
"Unit": "None"
}
],
"Label": "PageViewCount"
}
```
## 統計セットを公開する
さらに、CloudWatch にパブリッシュする前にデータを集約することができます。各分に複数のデータポイントがある場合、データを集約して **put-metric-data** への呼び出し回数を最小化できます。たとえば、互いに 3 秒以内の位置にある 3 つのデータポイントに対して **put-metric-data** を複数回呼び出す代わりに、`--statistic-values` パラメータを使用して、1 回の呼び出しで発行できる統計セットにデータを集約できます。
```
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace MyService --statistic-values Sum=11,Minimum=2,Maximum=5,SampleCount=3 --timestamp 2016-10-14T12:00:00.000Z
```
CloudWatch は、raw データポイントを使用してパーセンタイルを計算します。統計セットを使用してデータを発行する場合は、以下の条件のいずれかが真である場合を除き、このデータのパーセンタイル統計を取得することはできません。
+ 統計セットの `SampleCount` が 1
+ 統計セットの `Minimum` と `Maximum` が同一である
## 値ゼロを公開する
データが散発的で、関連データがない期間がある場合、その期間に対して値ゼロ `0` をパブリッシュするか、全く値なしにするかを選択できます。アプリケーションの状態をモニターリングするために `PutMetricData` を周期的に呼び出す場合、値なしにするのではなく、値ゼロ (0) をパブリッシュすることができます。例えば、アプリケーションが 5 分ごとにメトリクスをパブリッシュできない場合、CloudWatch アラームを設定できます。そのようなアプリケーションに関連データがない期間ではゼロ（0）をパブリッシュさせることができます。
また、データポイントの総数を追跡する場合、または最小値や平均値などの統計に値 0 のデータポイントを含める場合も 0 をパブリッシュすることがあります。
## メトリクスの公開を停止する
CloudWatch へのカスタムメトリクスの公開を停止するには、アプリケーションまたはサービスのコードを変更して、**PutMetricData** の使用を停止します。CloudWatch はアプリケーションからメトリクスをプルせず、プッシュされたもののみを受信するため、メトリクスの公開を停止するには、ソースでメトリクスを停止する必要があります。