仕様: 埋め込みメトリクスフォーマット
CloudWatch 埋め込みメトリクスフォーマットは、構造化ログイベントに埋め込まれたメトリクス値を自動的に抽出するように CloudWatch Logs に指示するために使用される JSON 仕様です。CloudWatch を使用して、抽出されたメトリクス値のアラームをグラフ化および作成できます。このセクションでは、埋め込みメトリクスフォーマットの仕様規則と埋め込みメトリクスフォーマットのドキュメント構造について説明します。
埋め込みメトリクスフォーマット仕様の表記規則
このフォーマット仕様では、「する必要がある」、「することはできない」、「必須」、「しなければならない」、「してはならない」、「すべきである」、「すべきではない」、「推奨」、「することができる」、「オプション」というキーワードは、キーワード RFC 2119
このフォーマット仕様では、「JSON」、「JSON テキスト」、「JSON 値」、「メンバー」、「要素」、「オブジェクト」、「配列」、「数値」、「文字列」、「boolean」、「true」、「false」、「null」という用語は、JavaScript Object Notation RFC8259
注記
埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する」の推奨事項を参照してください。
埋め込みメトリクスフォーマットドキュメントの構造
このセクションでは、埋め込みメトリクスフォーマットドキュメントの構造について説明します。埋め込みメトリックフォーマットドキュメントは、JavaScript Object Notation RFC8259
特に明記されていない限り、この仕様で定義されたオブジェクトに追加のメンバーを含めることはできません。この仕様で認識されないメンバーは無視する必要があります。この仕様で定義されているメンバーは、大文字と小文字が区別されます。
埋め込みメトリクスフォーマットは、標準 CloudWatch Logs イベントと同じ制限が適用され、最大サイズは 256 KB に制限されます。
埋め込みメトリクス形式を使用すると、アカウントの AWS/Logs
名前空間で公開されるメトリクスによって、EMF ログの処理を追跡することができます。これらのメトリクスは、EMF からのメトリクス生成の失敗を追跡するために使用できます。また、障害が発生したのは解析によるものなのか、検証によるものなのかを追跡できます。詳細については、「CloudWatch メトリクスによるモニタリング」を参照してください。
ルートノード
LogEvent メッセージは、LogEvent メッセージ文字列の先頭または末尾に追加データがない有効な JSON オブジェクトである必要があります。LogEvent 構造の詳細については、「InputLogEvent」を参照してください。
埋め込みメトリックフォーマットドキュメントには、ルートノード上の次の最上位メンバーが含まれている必要があります。これは メタデータオブジェクト オブジェクトです。
{ "_aws": { "CloudWatchMetrics": [ ... ] } }
ルートノードには、MetricDirective オブジェクト の参照によって定義されたすべての ターゲットメンバー メンバーが含まれている必要があります。
ルートノードには、上記の要件に含まれていない他のメンバーを含めることができます。これらのメンバーの値は有効な JSON 型である必要があります。
メタデータオブジェクト
_aws
メンバーを使用して、ダウンストリームサービスに LogEvent の処理方法を通知するペイロードに関するメタデータを表すことができます。値はオブジェクトでなければならず、次のメンバーが含まれている必要があります。
CloudWatchMetrics – LogEvent のルートノードからメトリクスを抽出するように CloudWatch に指示するために使用される MetricDirective オブジェクト の配列。
{ "_aws": { "CloudWatchMetrics": [ ... ] } }
Timestamp – イベントから抽出されたメトリクスに使用されるタイムスタンプを表す数値。値は、1970 年 1 月 1 日 00:00:00 UTC からのミリ秒数で表される必要があります。
{ "_aws": { "Timestamp": 1559748430481 } }
MetricDirective オブジェクト
MetricDirective オブジェクトは、CloudWatch に抽出および発行されるメトリクスが LogEvent に含まれていることをダウンストリームサービスに通知します。MetricDirectives には、次のメンバーが含まれている必要があります。
Namespace – メトリクスの CloudWatch 名前空間を表す文字列。
Dimensions – DimensionSet 配列。
Metrics – MetricDefinition オブジェクトの配列。この配列に、100 個を超える MetricDefinition オブジェクトを含めることはできません。
DimensionSet 配列
DimensionSet は、ドキュメント内のすべてのメトリックに適用されるディメンションキーを含む文字列の配列です。この配列内の値は、ターゲットメンバー と呼ばれる、ルートノード上のメンバーである必要もあります。
DimensionSet に、30 個を超えるディメンションキーを含めることはできません。DimensionSet が空である可能性があります。
ターゲットメンバーには文字列値が必要です。この値には、1024 文字以上を含めることはできません。ターゲットメンバーにより、メトリック ID の一部として発行されるディメンションが定義されます。使用する DimensionSet ごとに、CloudWatch に新しいメトリクスが作成されます。ディメンションの詳細については、「Dimension」と「ディメンション」を参照してください。
{ "_aws": { "CloudWatchMetrics": [ { "Dimensions": [ [ "functionVersion" ] ], ... } ] }, "functionVersion": "$LATEST" }
注記
カスタムメトリックの使用状況と対応する請求に影響するため、メトリックの抽出を設定するときには注意が必要です。高カーディナリティディメンション(requestId
など)に基づいて意図せずにメトリックを作成すると、埋め込みメトリックフォーマットにより、各一意のディメンションの組み合わせに対応するカスタムメトリックが意図的に作成されます。詳細については、「ディメンション」を参照してください。
MetricDefinition オブジェクト
MetricDefinition は、次のメンバーを含める必要があるオブジェクトです。
MetricDefinition オブジェクトには、以下のメンバーを含めることができます。
Unit – 対応するメトリクスの測定単位を表すオプションの文字列値。値は有効な CloudWatch メトリクス単位である必要があります。有効な単位については、「MetricDatum」を参照してください。値を指定しない場合は、デフォルト値の NONE が使用されます。
StorageResolution – 対応するメトリクスのストレージ解像度を表すオプションの整数値。これを 1 に設定すると、このメトリクスが高解像度メトリクスとして指定されるので、CloudWatch は 1 分未満 (最小 1 秒) の解像度でメトリクスを保存します。これを 60 に設定すると、このメトリクスが標準解像度メトリクスとして指定され、CloudWatch は 1 分の解像度でメトリクスを保存します。値は、CloudWatch がサポートする有効な解像度 (1 または 60) にする必要があります。値が指定されない場合は、デフォルト値の 60 が想定されます。
高解像度メトリクスの詳細については、「高解像度のメトリクス」を参照してください。
注記
埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する」の推奨事項を参照してください。
{ "_aws": { "CloudWatchMetrics": [ { "Metrics": [ { "Name": "Time", "Unit": "Milliseconds", "StorageResolution": 60 } ], ... } ] }, "Time": 1 }
参照値
参照値は、ルートノード上の ターゲットメンバー メンバーを参照する文字列値です。これらの参照は、RFC6901
ターゲットメンバー
有効なターゲットは、ルートノード上のメンバーでなければならず、ネストされたオブジェクトにすることはできません。たとえば、"A.a"
の _reference_ 値は、次のメンバーと一致する必要があります。
{ "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 ] } } } } } } } } } } }