# 仕様: 埋め込みメトリクスフォーマット
CloudWatch 埋め込みメトリクスフォーマットは、構造化ログイベントに埋め込まれたメトリクス値を自動的に抽出するように CloudWatch Logs に指示するために使用される JSON 仕様です。CloudWatch を使用して、抽出されたメトリクス値のアラームをグラフ化および作成できます。このセクションでは、埋め込みメトリクスフォーマットの仕様規則と埋め込みメトリクスフォーマットのドキュメント構造について説明します。
## 埋め込みメトリクスフォーマット仕様の表記規則
このフォーマット仕様では、「する必要がある」、「することはできない」、「必須」、「しなければならない」、「してはならない」、「すべきである」、「すべきではない」、「推奨」、「することができる」、「オプション」というキーワードは、[キーワード RFC 2119](http://tools.ietf.org/html/rfc2119)で説明されているように解釈されます。
このフォーマット仕様では、「JSON」、「JSON テキスト」、「JSON 値」、「メンバー」、「要素」、「オブジェクト」、「配列」、「数値」、「文字列」、「boolean」、「true」、「false」、「null」という用語は、[JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259) で定義されているように解釈されます。
**注記**
埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「[埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する](CloudWatch_Embedded_Metric_Format_Alarms.md)」の推奨事項を参照してください。
## 埋め込みメトリクスフォーマットドキュメントの構造
このセクションでは、埋め込みメトリクスフォーマットドキュメントの構造について説明します。埋め込みメトリックフォーマットドキュメントは、[JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259) で定義されています。
特に明記されていない限り、この仕様で定義されたオブジェクトに追加のメンバーを含めることはできません。この仕様で認識されないメンバーは無視する必要があります。この仕様で定義されているメンバーは、大文字と小文字が区別されます。
埋め込みメトリクスフォーマットは、標準 CloudWatch Logs イベントと同じ制限が適用され、最大サイズは 1 MB に制限されます。
埋め込みメトリクス形式を使用すると、アカウントの `AWS/Logs` 名前空間で公開されるメトリクスによって、EMF ログの処理を追跡することができます。これらのメトリクスは、EMF からのメトリクス生成の失敗を追跡するために使用できます。また、障害が発生したのは解析によるものなのか、検証によるものなのかを追跡できます。詳細については、「[CloudWatch メトリクスによるモニタリング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)」を参照してください。
### ルートノード
LogEvent メッセージは、LogEvent メッセージ文字列の先頭または末尾に追加データがない有効な JSON オブジェクトである必要があります。LogEvent 構造の詳細については、「[InputLogEvent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html)」を参照してください。
埋め込みメトリックフォーマットドキュメントには、ルートノード上の次の最上位メンバーが含まれている必要があります。これは [メタデータオブジェクト](#CloudWatch_Embedded_Metric_Format_Specification_structure_metadata) オブジェクトです。
```
{
"_aws": {
"CloudWatchMetrics": [ ... ]
}
}
```
ルートノードには、[MetricDirective オブジェクト](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) の参照によって定義されたすべての [ターゲットメンバー](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) メンバーが含まれている必要があります。
ルートノードには、上記の要件に含まれていない他のメンバーを含めることができます。これらのメンバーの値は有効な JSON 型である必要があります。
### メタデータオブジェクト
`_aws` メンバーを使用して、ダウンストリームサービスに LogEvent の処理方法を通知するペイロードに関するメタデータを表すことができます。値はオブジェクトでなければならず、次のメンバーが含まれている必要があります。
+ **CloudWatchMetrics** – LogEvent のルートノードからメトリクスを抽出するように CloudWatch に指示するために使用される [MetricDirective オブジェクト](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) の配列。
```
{
"_aws": {
"CloudWatchMetrics": [ ... ]
}
}
```
+ **Timestamp** – イベントから抽出されたメトリクスに使用されるタイムスタンプを表す数値。値は、1970 年 1 月 1 日 00:00:00 UTC からのミリ秒数で表される必要があります。
```
{
"_aws": {
"Timestamp": 1559748430481
}
}
```
### MetricDirective オブジェクト
MetricDirective オブジェクトは、CloudWatch に抽出および発行されるメトリクスが LogEvent に含まれていることをダウンストリームサービスに通知します。MetricDirectives には、次のメンバーが含まれている必要があります。
+ **Namespace** – メトリクスの CloudWatch 名前空間を表す文字列。
+ **Dimensions** – [DimensionSet 配列](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset)。
+ **Metrics** – [MetricDefinition オブジェクト](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition) オブジェクトの配列。この配列に、100 個を超える MetricDefinition オブジェクトを含めることはできません。
### DimensionSet 配列
DimensionSet は、ドキュメント内のすべてのメトリックに適用されるディメンションキーを含む文字列の配列です。この配列内の値は、[ターゲットメンバー](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) と呼ばれる、ルートノード上のメンバーである必要もあります。
DimensionSet に、30 個を超えるディメンションキーを含めることはできません。DimensionSet が空である可能性があります｡
ターゲットメンバーには文字列値が必要です。この値には、1024 文字以上を含めることはできません。ターゲットメンバーにより、メトリック ID の一部として発行されるディメンションが定義されます。使用する DimensionSet ごとに、CloudWatch に新しいメトリクスが作成されます。ディメンションの詳細については、「[Dimension](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html)」と「[ディメンション](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)」を参照してください。
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Dimensions": [ [ "functionVersion" ] ],
...
}
]
},
"functionVersion": "$LATEST"
}
```
**注記**
カスタムメトリックの使用状況と対応する請求に影響するため、メトリックの抽出を設定するときには注意が必要です。高カーディナリティディメンション（`requestId` など）に基づいて意図せずにメトリックを作成すると、埋め込みメトリックフォーマットにより、各一意のディメンションの組み合わせに対応するカスタムメトリックが意図的に作成されます。詳細については、「[ディメンション](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)」を参照してください。
### MetricDefinition オブジェクト
MetricDefinition は、次のメンバーを含める必要があるオブジェクトです。
+ **Name** – メトリクス [ターゲットメンバー](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) に対する文字列 [参照値](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues)。メトリックターゲットは、数値または数値の配列でなければなりません。
MetricDefinition オブジェクトには、以下のメンバーを含めることができます。
+ **Unit** – 対応するメトリクスの測定単位を表すオプションの文字列値。値は有効な CloudWatch メトリクス単位である必要があります。有効な単位については、「[MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)」を参照してください。値を指定しない場合は、デフォルト値の NONE が使用されます。
+ **StorageResolution** – 対応するメトリクスのストレージ解像度を表すオプションの整数値。これを 1 に設定すると、このメトリクスが高解像度メトリクスとして指定されるので、CloudWatch は 1 分未満 (最小 1 秒) の解像度でメトリクスを保存します。これを 60 に設定すると、このメトリクスが標準解像度メトリクスとして指定され、CloudWatch は 1 分の解像度でメトリクスを保存します。値は、CloudWatch がサポートする有効な解像度 (1 または 60) にする必要があります。値が指定されない場合は、デフォルト値の 60 が想定されます。
高解像度メトリクスの詳細については、「[高解像度のメトリクス](publishingMetrics.md#high-resolution-metrics)」を参照してください。
**注記**
埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「[埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する](CloudWatch_Embedded_Metric_Format_Alarms.md)」の推奨事項を参照してください。
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Metrics": [
{
"Name": "Time",
"Unit": "Milliseconds",
"StorageResolution": 60
}
],
...
}
]
},
"Time": 1
}
```
### 参照値
参照値は、ルートノード上の [ターゲットメンバー](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) メンバーを参照する文字列値です。これらの参照は、[RFC6901](https://tools.ietf.org/html/rfc6901) で説明されている JSON ポインタと混同しないでください。ターゲット値をネストすることはできません。
### ターゲットメンバー
有効なターゲットは、ルートノード上のメンバーでなければならず、ネストされたオブジェクトにすることはできません。たとえば、`"A.a"` の \$1reference\$1 値は、次のメンバーと一致する必要があります。
```
{ "A.a" }
```
ネストされたメンバーと一致してはなりません。
```
{ "A": { "a" } }
```
ターゲットメンバーの有効な値は、それらを参照しているものによって異なります。メトリクスターゲットは、数値または数値の配列である必要があります。数値配列メトリクスターゲットは、100 を超えるメンバーを持つことはできません。ディメンションターゲットには文字列値が必要です。
### 埋め込みメトリクスフォーマットの例と JSON スキーマ
次に、埋め込みメトリックフォーマットの有効な例を示します。
```
{
"_aws": {
"Timestamp": 1574109732004,
"CloudWatchMetrics": [
{
"Namespace": "lambda-function-metrics",
"Dimensions": [["functionVersion"]],
"Metrics": [
{
"Name": "time",
"Unit": "Milliseconds",
"StorageResolution": 60
}
]
}
]
},
"functionVersion": "$LATEST",
"time": 100,
"requestId": "989ffbf8-9ace-4817-a57c-e4dd734019ee"
}
```
次のスキーマを使用して、埋め込みメトリックフォーマットドキュメントを検証できます。
```
{
"type": "object",
"title": "Root Node",
"required": [
"_aws"
],
"properties": {
"_aws": {
"$id": "#/properties/_aws",
"type": "object",
"title": "Metadata",
"required": [
"Timestamp",
"CloudWatchMetrics"
],
"properties": {
"Timestamp": {
"$id": "#/properties/_aws/properties/Timestamp",
"type": "integer",
"title": "The Timestamp Schema",
"examples": [
1565375354953
]
},
"CloudWatchMetrics": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics",
"type": "array",
"title": "MetricDirectives",
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items",
"type": "object",
"title": "MetricDirective",
"required": [
"Namespace",
"Dimensions",
"Metrics"
],
"properties": {
"Namespace": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Namespace",
"type": "string",
"title": "CloudWatch Metrics Namespace",
"examples": [
"MyApp"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 1024
},
"Dimensions": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions",
"type": "array",
"title": "The Dimensions Schema",
"minItems": 1,
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items",
"type": "array",
"title": "DimensionSet",
"minItems": 0,
"maxItems": 30,
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items",
"type": "string",
"title": "DimensionReference",
"examples": [
"Operation"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 250
}
}
},
"Metrics": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics",
"type": "array",
"title": "MetricDefinitions",
"items": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items",
"type": "object",
"title": "MetricDefinition",
"required": [
"Name"
],
"properties": {
"Name": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Name",
"type": "string",
"title": "MetricName",
"examples": [
"ProcessingLatency"
],
"pattern": "^(.*)$",
"minLength": 1,
"maxLength": 1024
},
"Unit": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Unit",
"type": "string",
"title": "MetricUnit",
"examples": [
"Milliseconds"
],
"pattern": "^(Seconds|Microseconds|Milliseconds|Bytes|Kilobytes|Megabytes|Gigabytes|Terabytes|Bits|Kilobits|Megabits|Gigabits|Terabits|Percent|Count|Bytes\\/Second|Kilobytes\\/Second|Megabytes\\/Second|Gigabytes\\/Second|Terabytes\\/Second|Bits\\/Second|Kilobits\\/Second|Megabits\\/Second|Gigabits\\/Second|Terabits\\/Second|Count\\/Second|None)$"
},
"StorageResolution": {
"$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/StorageResolution",
"type": "integer",
"title": "StorageResolution",
"examples": [
60
]
}
}
}
}
}
}
}
}
}
}
}
```
## EMF 形式のエンティティ情報
埋め込みメトリクス形式 (EMF) を使用して Amazon CloudWatch にログを発行する場合、ログイベントにエンティティ情報を含めることができます。このセクションでは、エンティティ情報を指定する方法と、CloudWatch がこの情報を処理する方法について説明します。
### エンティティタイプ
`PutLogEvents` リクエストでエンティティが指定されていない場合、CloudWatch は EMF ログコンテンツ内のエンティティ情報を検索します。
+ **サービスタイプのエンティティ**
必須フィールド: `Service` および `Environment`
+ **リソースタイプのエンティティ**
必須フィールド: `ResourceType` および `Identifier`
### プラットフォーム属性
CloudWatch は、これらの属性に基づいてプラットフォームタイプを自動的に決定します。
+ **Kubernetes (K8s):**
必須: `K8s.Cluster`
オプション: `K8s.Namespace`、`K8s.Workload`、`K8s.Node`、`K8s.Pod`、`EC2.InstanceId`、`EC2.AutoScalingGroup`
+ **Amazon EKS**
必須: `EKS.Cluster`
オプション: `K8s.Namespace`、`K8s.Workload`、`K8s.Node`、`K8s.Pod`、`EC2.InstanceId`
+ **Amazon ECS:**
必須: `ECS.Cluster`
オプション: `ECS.Service`、`ECS.Task`
+ **Amazon EC2**
必須: `EC2.InstanceId`
オプション: `EC2.AutoScalingGroup`
+ **Lambda:**
必須: `Lambda.Function`
+ **汎用ホスト:**
必須: `Host`
### EMF ログ形式の例
```
{
"_aws": {
"CloudWatchMetrics": [
{
"Metrics": [
{"Name": "RequestLatency", "Unit": "Milliseconds"}
],
"Namespace": "MyApplication"
}
]
},
"Service": "PaymentService",
"Environment": "Production",
"K8s.Cluster": "main-cluster",
"K8s.Namespace": "payment-ns",
"K8s.Pod": "payment-pod-123",
"K8s.Node": "worker-node-1",
"K8s.Workload": "payment-deployment",
"RequestLatency": 135.5,
"timestamp": 1622163600000
}
```
### 生成されたエンティティ
上記の EMF ログでは、次のエンティティが生成されます。
```
{
"KeyAttributes": {
"Type": "Service",
"Name": "PaymentService",
"Environment": "Production"
},
"Attributes": {
"PlatformType": "K8s",
"K8s.Cluster": "main-cluster",
"K8s.Namespace": "payment-ns",
"K8s.Pod": "payment-pod-123",
"K8s.Node": "worker-node-1",
"K8s.Workload": "payment-deployment"
}
}
```
### エンティティ処理
CloudWatch はエンティティ情報を次のように処理します。
+ **KeyAttributes:**
+ 必須フィールドに基づいてエンティティタイプを決定します
+ サービスタイプの場合、サービス名と環境を抽出します
+ これらはエンティティのプライマリ識別子になります
+ **属性:**
+ 含まれているプラットフォーム属性に基づいて PlatformType を設定します
+ 関連するプラットフォーム固有の情報をすべて含みます
+ テレメトリデータの関係コンテキストを維持します
CloudWatch では、このエンティティ情報を使用して、さまざまなテレメトリデータ間の関係を確立し、アプリケーションとインフラストラクチャのオブザーバビリティとコンテキスト分析を可能にします。詳細については、「[CloudWatch に送信されるカスタムテレメトリに関連情報を追加する方法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html)」を参照してください。
**注記**
エンティティ情報は、CloudWatch がアプリケーションのテレメトリデータとインフラストラクチャ内での関係の全体像を作成するのに役立ちます。