仕様: 埋め込みメトリクスフォーマット - Amazon CloudWatch

仕様: 埋め込みメトリクスフォーマット

CloudWatch 埋め込みメトリクスフォーマットは、構造化ログイベントに埋め込まれたメトリクス値を自動的に抽出するように CloudWatch Logs に指示するために使用される JSON 仕様です。CloudWatch を使用して、抽出されたメトリクス値のアラームをグラフ化および作成できます。

埋め込みメトリクスフォーマット仕様の表記規則

このフォーマット仕様では、「する必要がある」、「することはできない」、「必須」、「しなければならない」、「してはならない」、「すべきである」、「すべきではない」、「推奨」、「することができる」、「オプション」というキーワードは、キーワード RFC 2119で説明されているように解釈されます。

このフォーマット仕様では、「JSON」、「JSON テキスト」、「JSON 値」、「メンバー」、「要素」、「オブジェクト」、「配列」、「数値」、「文字列」、「boolean」、「true」、「false」、「null」という用語は、JavaScript Object Notation RFC8259 で定義されているように解釈されます。

埋め込みメトリクスフォーマット仕様の PutLogEvents リクエスト形式

CloudWatch Logs PutLogEvents API を使用して埋め込みメトリクスフォーマットのドキュメントを送信する場合、クライアントは次のログフォーマットヘッダーを使用する必要があります。

x-amzn-logs-format: json/emf

Lambda では、このヘッダーを自分で設定する必要はありません。埋め込みメトリクス形式で JSON を標準出力に書き込むだけで十分です。Lambda は、タイムスタンプやリクエスト ID などのメタデータをログイベントの先頭に付加しますが、このメタデータの後の有効な埋め込みメトリクス形式ドキュメントは有効と見なされます。

埋め込みメトリクスフォーマットドキュメントの構造

このセクションでは、ログフォーマットヘッダー x-amzn-logs-format: json/emf で識別される埋め込みメトリックフォーマットドキュメントの構造について説明します。埋め込みメトリックフォーマットドキュメントは、JavaScript Object Notation RFC8259 で定義されています。

特に明記されていない限り、この仕様で定義されたオブジェクトに追加のメンバーを含めることはできません。この仕様で認識されないメンバーは無視する必要があります。この仕様で定義されているメンバーは、大文字と小文字が区別されます。

埋め込みメトリクスフォーマットは、標準 CloudWatch Logs イベントと同じ制限が適用され、最大サイズは 256 KB に制限されます。

ルートノード

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 名前空間を表す文字列。

  • DimensionsDimensionSet 配列

  • MetricsMetricDefinition オブジェクトの配列。この配列に、100 個を超える MetricDefinition オブジェクトを含めることはできません。

DimensionSet 配列

DimensionSet は、ドキュメント内のすべてのメトリックに適用されるディメンションキーを含む文字列の配列です。この配列内の値は、ターゲットメンバー と呼ばれる、ルートノード上のメンバーである必要もあります。

DimensionSet に、9 個を超えるディメンションキーを含めることはできません。DimensionSet が空である可能性があります。

ターゲットメンバーには文字列値が必要です。ターゲットメンバーにより、メトリック ID の一部として発行されるディメンションが定義されます。使用する DimensionSet ごとに、CloudWatch に新しいメトリクスが作成されます。ディメンションの詳細については、「Dimension」と「ディメンション」を参照してください。

{ "_aws": { "CloudWatchMetrics": [ { "Dimensions": [ [ "functionVersion" ] ], ... } ] }, "functionVersion": "$LATEST" }
注記

カスタムメトリックの使用状況と対応する請求に影響するため、メトリックの抽出を設定するときには注意が必要です。高カーディナリティディメンション(requestId など)に基づいて意図せずにメトリックを作成すると、埋め込みメトリックフォーマットにより、各一意のディメンションの組み合わせに対応するカスタムメトリックが意図的に作成されます。詳細については、「ディメンション」を参照してください。

MetricDefinition オブジェクト

MetricDefinition は、次のメンバーを含める必要があるオブジェクトです。

  • Name – メトリクス 参照値 に対する文字列 ターゲットメンバー。メトリックターゲットは、数値または数値の配列でなければなりません。

MetricDefinition オブジェクトには、次のメンバーを含めることができます。

  • Unit – 対応するメトリクスの測定単位を表すオプションの文字列値。値は有効な CloudWatch メトリクス単位である必要があります。有効な単位については、「MetricDatum」を参照してください。値を指定しない場合は、デフォルト値の NONE が使用されます。

{ "_aws": { "CloudWatchMetrics": [ { "Metrics": [ { "Name": "Time", "Unit": "Milliseconds" } ], ... } ] }, "Time": 1 }

参照値

参照値は、ルートノード上の ターゲットメンバー メンバーを参照する文字列値です。これらの参照は、RFC6901 で説明されている JSON ポインタと混同しないでください。ターゲット値をネストすることはできません。

ターゲットメンバー

有効なターゲットは、ルートノード上のメンバーでなければならず、ネストされたオブジェクトにすることはできません。たとえば、"A.a" の _reference_ 値は、次のメンバーと一致する必要があります。

{ "A.a" }

ネストされたメンバーと一致してはなりません。

{ "A": { "a" } }

ターゲットメンバーの有効な値は、それらを参照しているものによって異なります。メトリクスターゲットは、数値または数値の配列である必要があります。数値配列メトリクスターゲットは、100 を超えるメンバーを持つことはできません。ディメンションターゲットには文字列値が必要です。

埋め込みメトリクスフォーマットの例と JSON スキーマ

次に、埋め込みメトリックフォーマットの有効な例を示します。

{ "_aws": { "Timestamp": 1574109732004, "CloudWatchMetrics": [ { "Namespace": "lambda-function-metrics", "Dimensions": [["functionVersion"]], "Metrics": [ { "Name": "time", "Unit": "Milliseconds" } ] } ] }, "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": 255 }, "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": 9, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items", "type": "string", "title": "DimensionReference", "examples": [ "Operation" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 255 } } }, "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": 255 }, "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)$" } } } } } } } } } } }