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

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 は、次のメンバーを含める必要があるオブジェクトです。

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

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 で説明されている 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",
            "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
                                            ]
                                         }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

クライアントライブラリを使用する

PutLogEvents API を使用した手動作成の埋め込みメトリクスフォーマットログの送信