# ログ内へのメトリクスの埋め込み
CloudWatch 埋め込みメトリクス形式を使用すると、CloudWatch Logs に書き込まれるログの形式でカスタムメトリクスを非同期的に生成できます。詳細なログイベントデータと一緒にカスタムメトリクスを埋め込むことができます。CloudWatch はカスタムメトリクスを自動的に抽出し、リアルタイムのインシデント検出のためにそれらを可視化して警告できるようにします。また、CloudWatch Logs Insights を使用して、抽出されたメトリクスに関連付けられた詳細なログイベントを照会し、運用イベントの根本原因に関する深い洞察を提供できます。
埋め込みメトリクスフォーマットは、Lambda 関数やコンテナなどの一時的なリソースから実用的なカスタムメトリクスを生成するのに役立ちます。埋め込みメトリックフォーマットを使用してこれらの一時的なリソースからログを送信することにより、ログデータの強力な分析機能を獲得しながら、個別のコードをインストルメント化または保守することなく、カスタムメトリックを簡単に作成できるようになりました。
埋め込みメトリクス形式を使用するために設定は必要ありません。[埋め込みメトリクス形式の仕様](CloudWatch_Embedded_Metric_Format_Specification.md)に従ってログを構造化するか、クライアントライブラリを使用してログを生成し、[PutLogEvents API](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) または [CloudWatch エージェント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html)を使用して CloudWatch Logs に送信します。
埋め込みメトリクス形式のログからメトリクスを生成するには、`logs:PutLogEvents` アクセス許可が必要ですが、`cloudwatch:PutMetricData` アクセス許可は必要ありません。
ログの取り込みとアーカイブ、および生成されるカスタムメトリックには料金が発生します。詳細については、[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing)をご覧ください。
**注記**
カスタムメトリックの使用状況と対応する請求に影響するため、メトリックの抽出を設定するときには注意が必要です。高カーディナリティディメンション（`requestId` など）に基づいて意図せずにメトリックを作成すると、埋め込みメトリックフォーマットにより、各一意のディメンションの組み合わせに対応するカスタムメトリックが意図的に作成されます。詳細については、「[ディメンション](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)」を参照してください。
以下のトピックでは、埋め込みメトリクスフォーマットを使用してログを発行する方法、コンソールでメトリクスとログを表示する方法、埋め込みメトリクスフォーマットで作成されたメトリクスにアラームを設定する方法について説明します。
**Topics**
+ [埋め込みメトリクス形式を使用したログの発行](CloudWatch_Embedded_Metric_Format_Generation.md)
+ [コンソールでのメトリクスおよびログの表示](CloudWatch_Embedded_Metric_Format_View.md)
+ [埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する](CloudWatch_Embedded_Metric_Format_Alarms.md)
# 埋め込みメトリクス形式を使用したログの発行
次の方法を使用して、埋め込みメトリクスフォーマットログを生成できます。
+ [オープンソースのクライアントライブラリ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Libraries.html)を使用してログを生成して送信する
+ [埋め込みメトリクス形式の仕様](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html)を使用してログを手動で生成し、[CloudWatch エージェント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html)または [PutLogEvents API](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) を使用してログを送信します。
以下のトピックでは、埋め込みメトリクスについて詳しく説明します。
**Topics**
+ [クライアントライブラリを使用した埋め込みメトリクス形式でのログの作成](CloudWatch_Embedded_Metric_Format_Libraries.md)
+ [仕様: 埋め込みメトリクスフォーマット](CloudWatch_Embedded_Metric_Format_Specification.md)
+ [PutLogEvents API を使用した手動作成の埋め込みメトリクスフォーマットログの送信](CloudWatch_Embedded_Metric_Format_Generation_PutLogEvents.md)
+ [CloudWatch エージェントを使用した埋め込みメトリクスフォーマットログの送信](CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.md)
+ [OpenTelemetry 用の AWS ディストリビューションでの埋め込みメトリクスフォーマットの使用](CloudWatch_Embedded_Metric_Format_OpenTelemetry.md)
# クライアントライブラリを使用した埋め込みメトリクス形式でのログの作成
Amazon が提供するオープンソースのクライアントライブラリを使用して、埋め込みメトリクスフォーマットログを作成できます。さまざまな設定の完全な例は、**/examples** の下のクライアントライブラリにあります。ライブラリとその使用方法の手順は Github にあります。
+ [Node.Js](https://github.com/awslabs/aws-embedded-metrics-node)
**注記**
Node.js の場合、Lambda JSON ログ形式を使用するには、バージョン 4.1.1 以降、3.0.2 以降、2.0.7 以降が必要です。このような Lambda 環境で以前のバージョンを使用すると、メトリクスが失われます。
詳細については、「[AWS Lambda の Amazon CloudWatch Logs へのアクセス](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html)」を参照してください。
+ [Python](https://github.com/awslabs/aws-embedded-metrics-python)
+ [Java](https://github.com/awslabs/aws-embedded-metrics-java)
+ [C\$1](https://github.com/awslabs/aws-embedded-metrics-dotnet)
クライアントライブラリは、すぐに CloudWatch エージェントで動作するように設計されています。生成された埋め込みメトリクス形式のログは CloudWatch エージェントに送信され、CloudWatch エージェントはそれらを集約して CloudWatch Logs に発行します。
**注記**
Lambda を使用する場合、CloudWatch にログを送信するエージェントは必要ありません。STDOUT にログ記録されたものはすべて、Lambda Logging Agent 経由で CloudWatch Logs に送信されます。
# 仕様: 埋め込みメトリクスフォーマット
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 がアプリケーションのテレメトリデータとインフラストラクチャ内での関係の全体像を作成するのに役立ちます。
# PutLogEvents API を使用した手動作成の埋め込みメトリクスフォーマットログの送信
CloudWatch Logs の [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) API を使用して、埋め込みメトリクスフォーマットログを CloudWatch Logs に送信できます。PutLogEvents を呼び出すときに、メトリクスを抽出する必要があることを CloudWatch Logs に指示する次の HTTP ヘッダーを含めるオプションがありますが、これは必須ではありません。
```
x-amzn-logs-format: json/emf
```
AWS SDK for Java 2.x を使用した詳細な例を次に示します。
```
package org.example.basicapp;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.cloudwatchlogs.CloudWatchLogsClient;
import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsRequest;
import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsResponse;
import software.amazon.awssdk.services.cloudwatchlogs.model.InputLogEvent;
import software.amazon.awssdk.services.cloudwatchlogs.model.PutLogEventsRequest;
import java.util.Collections;
public class EmbeddedMetricsExample {
public static void main(String[] args) {
final String usage = "To run this example, supply a Region code (eg. us-east-1), log group, and stream name as command line arguments"
+ "Ex: PutLogEvents ";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String regionId = args[0];
String logGroupName = args[1];
String logStreamName = args[2];
CloudWatchLogsClient logsClient = CloudWatchLogsClient.builder().region(Region.of(regionId)).build();
// Build a JSON log using the EmbeddedMetricFormat.
long timestamp = System.currentTimeMillis();
String message = "{" +
" \"_aws\": {" +
" \"Timestamp\": " + timestamp + "," +
" \"CloudWatchMetrics\": [" +
" {" +
" \"Namespace\": \"MyApp\"," +
" \"Dimensions\": [[\"Operation\"], [\"Operation\", \"Cell\"]]," +
" \"Metrics\": [{ \"Name\": \"ProcessingLatency\", \"Unit\": \"Milliseconds\", \"StorageResolution\": 60 }]" +
" }" +
" ]" +
" }," +
" \"Operation\": \"Aggregator\"," +
" \"Cell\": \"001\"," +
" \"ProcessingLatency\": 100" +
"}";
InputLogEvent inputLogEvent = InputLogEvent.builder()
.message(message)
.timestamp(timestamp)
.build();
// Specify the request parameters.
PutLogEventsRequest putLogEventsRequest = PutLogEventsRequest.builder()
.logEvents(Collections.singletonList(inputLogEvent))
.logGroupName(logGroupName)
.logStreamName(logStreamName)
.build();
logsClient.putLogEvents(putLogEventsRequest);
System.out.println("Successfully put CloudWatch log event");
}
}
```
**注記**
埋め込みメトリクス形式を使用すると、アカウントの `AWS/Logs` 名前空間で公開されるメトリクスによって、EMF ログの処理を追跡することができます。これらのメトリクスは、EMF からのメトリクス生成の失敗を追跡するために使用できます。また、障害が発生したのは解析によるものなのか、検証によるものなのかを追跡できます。詳細については、「[CloudWatch メトリクスによるモニタリング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)」を参照してください。
# CloudWatch エージェントを使用した埋め込みメトリクスフォーマットログの送信
このセクションでは、CloudWatch エージェントをインストールして使用する方法について説明します。このセクションの最初の部分では、CloudWatch エージェントをインストールする方法について説明します。このセクションの 2 番目の部分では、CloudWatch エージェントを使用して埋め込みメトリクスフォーマットログを送信する方法について説明します。この方法を使用する場合は、埋め込みメトリクスフォーマットログを送信する AWS のサービス の CloudWatch エージェントをインストールする必要があります。その後、イベントの送信を開始できます。CloudWatch エージェントは、バージョン 1.230621.0 以降である必要があります。
**注記**
Lambda 関数からログを送信するために CloudWatch エージェントをインストールする必要はありません。
Lambda 関数のタイムアウトは自動的に処理されません。つまり、メトリックがフラッシュされる前に関数がタイムアウトすると、その呼び出しのメトリックはキャプチャされません。
## CloudWatch エージェントのインストール
埋め込みメトリクスフォーマットログを送信するサービスごとに CloudWatch エージェントをインストールします。
### EC2 への CloudWatch エージェントのインストール
まず、インスタンスに CloudWatch エージェントをインストールします。(詳細については、[CloudWatch エージェントのインストール](install-CloudWatch-Agent-on-EC2-Instance.md) を参照してください)。
エージェントをインストールしたら、埋め込みメトリックフォーマットログを UDP または TCP ポートでリッスンするようにエージェントを設定します。次に、デフォルトソケット `tcp:25888` をリッスンするこの設定の例を示します。エージェント設定の詳細については、「[CloudWatch エージェント設定ファイルを手動で作成または編集する](CloudWatch-Agent-Configuration-File-Details.md)」を参照してください。
```
{
"logs": {
"metrics_collected": {
"emf": { }
}
}
}
```
### Amazon ECS への CloudWatch エージェントのインストール
Amazon ECS に CloudWatch エージェントをデプロイする最も簡単な方法は、それをサイドカーとして実行し、アプリケーションと同じタスク定義で定義することです。
**エージェント設定ファイルを作成する**
CloudWatch エージェント設定ファイルをローカルに作成します。この例では、相対ファイルパスは `amazon-cloudwatch-agent.json` になります。
エージェント設定の詳細については、「[CloudWatch エージェント設定ファイルを手動で作成または編集する](CloudWatch-Agent-Configuration-File-Details.md)」を参照してください。
```
{
"logs": {
"metrics_collected": {
"emf": { }
}
}
}
```
**設定を SSM パラメータストアにプッシュする**
次のコマンドを入力して、CloudWatch エージェント設定ファイルを AWS Systems Manager (SSM) Parameter Store にプッシュします。
```
aws ssm put-parameter \
--name "cwagentconfig" \
--type "String" \
--value "`cat amazon-cloudwatch-agent.json`" \
--region "{{region}}"
```
**タスク定義を設定する**
CloudWatch エージェントを使用して TCP または UDP ポートを公開するようにタスク定義を設定します。使用するサンプルのタスク定義は、ネットワークモードによって異なります。
`webapp` によって `AWS_EMF_AGENT_ENDPOINT` 環境変数が指定されることに注意してください。これはライブラリで使用され、エージェントがリッスンしているエンドポイントを指している必要があります。さらに、`cwagent` により、前の手順で作成した SSM 設定を指す「valueFrom」パラメータとして `CW_CONFIG_CONTENT` が指定されます。
このセクションでは、ブリッジモードの例と、ホストモードまたは awsvpc モードの例を 1 つ説明します。Amazon ECS で CloudWatch エージェントを設定する方法の例については、[Github サンプルリポジトリ](https://github.com/aws-samples/amazon-cloudwatch-container-insights/tree/master/ecs-task-definition-templates/deployment-mode/sidecar)を参照してください。
次に、ブリッジモードの例を示します。ブリッジモードネットワーキングが有効な場合、エージェントは `links` パラメータを使用してアプリケーションにリンクし、コンテナ名を使用してアドレス指定する必要があります。
```
{
"containerDefinitions": [
{
"name": "webapp",
"links": [ "cwagent" ],
"image": "my-org/web-app:latest",
"memory": 256,
"cpu": 256,
"environment": [{
"name": "AWS_EMF_AGENT_ENDPOINT",
"value": "tcp://cwagent:25888"
}],
},
{
"name": "cwagent",
"mountPoints": [],
"image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
"memory": 256,
"cpu": 256,
"portMappings": [{
"protocol": "tcp",
"containerPort": 25888
}],
"environment": [{
"name": "CW_CONFIG_CONTENT",
"valueFrom": "cwagentconfig"
}],
}
],
}
```
次に、ホストモードまたは awsvpc モードの例を示します。これらのネットワークモードで実行している場合は、`localhost` を介してエージェントをアドレス指定することができます。
```
{
"containerDefinitions": [
{
"name": "webapp",
"image": "my-org/web-app:latest",
"memory": 256,
"cpu": 256,
"environment": [{
"name": "AWS_EMF_AGENT_ENDPOINT",
"value": "tcp://127.0.0.1:25888"
}],
},
{
"name": "cwagent",
"mountPoints": [],
"image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
"memory": 256,
"cpu": 256,
"portMappings": [{
"protocol": "tcp",
"containerPort": 25888
}],
"environment": [{
"name": "CW_CONFIG_CONTENT",
"valueFrom": "cwagentconfig"
}],
}
],
}
```
**注記**
awsvpc モードでは、VPC にパブリック IP アドレスを割り当てるか (Fargate のみ)、NAT ゲートウェイをセットアップするか、CloudWatch Logs VPC エンドポイントを設定する必要があります。NAT のセットアップの詳細については、「[NAT ゲートウェイ](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)」を参照してください。CloudWatch Logs VPC エンドポイントの設定の詳細については、「[CloudWatch Logs とインターフェイス VPC エンドポイントの使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html)」を参照してください。
次に、Fargate 起動タイプを使用するタスクにパブリック IP アドレスを割り当てる方法の例を示します。
```
aws ecs run-task \
--cluster {{cluster-name}} \
--task-definition cwagent-fargate \
--region {{region}} \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}"
```
**許可を確認する**
タスクを実行する IAM ロールに SSM Parameter Store から読み取るためのアクセス許可があることを確認します。このアクセス許可を追加するには、**AmazonSSMReadOnlyAccess** ポリシーをアタッチします。これを行うには、次のコマンドを入力します。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole
```
### Amazon EKS への CloudWatch エージェントのインストール
このクラスターに CloudWatch Container Insights を既にインストールしている場合は、このプロセスの一部をスキップできます。
アクセス許可
Container Insights をまだインストールしていない場合は、まず Amazon EKS ノードに適切な IAM アクセス許可があることを確認してください。これらのノードに **CloudWatchAgentServerPolicy** がアタッチされている必要があります。(詳細については、「[CloudWatch での Container Insights の前提条件の検証](Container-Insights-prerequisites.md)」を参照してください)。
**ConfigMap を作成する**
エージェントの ConfigMap を作成します。また、ConfigMap は TCP ポートまたは UDP ポートでリッスンするようにエージェントに指示します。次の ConfigMap を使用します。
```
# cwagent-emf-configmap.yaml
apiVersion: v1
data:
# Any changes here must not break the JSON format
cwagentconfig.json: |
{
"agent": {
"omit_hostname": true
},
"logs": {
"metrics_collected": {
"emf": { }
}
}
}
kind: ConfigMap
metadata:
name: cwagentemfconfig
namespace: default
```
Container Insights をすでにインストールしている場合は、既存の ConfigMap に次の `"emf": { }` 行を追加します。
**ConfigMap を適用する**
次のコマンドを入力して、ConfigMap を適用します。
```
kubectl apply -f cwagent-emf-configmap.yaml
```
**エージェントをデプロイする**
CloudWatch エージェントをサイドカーとしてデプロイするには、次の例のようにポッド定義にエージェントを追加します。
```
apiVersion: v1
kind: Pod
metadata:
name: myapp
namespace: default
spec:
containers:
# Your container definitions go here
- name: web-app
image: my-org/web-app:latest
# CloudWatch Agent configuration
- name: cloudwatch-agent
image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest
imagePullPolicy: Always
resources:
limits:
cpu: 200m
memory: 100Mi
requests:
cpu: 200m
memory: 100Mi
volumeMounts:
- name: cwagentconfig
mountPath: /etc/cwagentconfig
ports:
# this should match the port configured in the ConfigMap
- protocol: TCP
hostPort: 25888
containerPort: 25888
volumes:
- name: cwagentconfig
configMap:
name: cwagentemfconfig
```
## CloudWatch エージェントを使用した埋め込みメトリクスフォーマットログの送信
CloudWatch エージェントをインストールして実行するときに、埋め込みメトリクスフォーマットログを TCP または UDP 経由で送信できます。エージェント経由でログを送信する場合、次の 2 つの要件があります。
+ ログには、どのロググループを使用するかをエージェントに指示する `LogGroupName` キーを含める必要があります。
+ 各ログイベントは 1 行にする必要があります。つまり、ログイベントに改行 (\$1n) 文字を含めることはできません。
ログイベントは、埋め込みメトリックフォーマットの仕様に従う必要もあります。詳細については、「[仕様: 埋め込みメトリクスフォーマット](CloudWatch_Embedded_Metric_Format_Specification.md)」を参照してください。
埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「[埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する](CloudWatch_Embedded_Metric_Format_Alarms.md)」の推奨事項を参照してください。
次に、Linux の bash シェルからログイベントを手動で送信する例を示します。代わりに、選択したプログラミング言語で提供される UDP ソケットインターフェイスを使用できます。
```
echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \
> /dev/udp/0.0.0.0/25888
```
**注記**
埋め込みメトリクス形式を使用すると、アカウントの `AWS/Logs` 名前空間で公開されるメトリクスによって、EMF ログの処理を追跡することができます。これらのメトリクスは、EMF からのメトリクス生成の失敗を追跡するために使用できます。また、障害が発生したのは解析によるものなのか、検証によるものなのかを追跡できます。詳細については、「[CloudWatch メトリクスによるモニタリング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)」を参照してください。
# OpenTelemetry 用の AWS ディストリビューションでの埋め込みメトリクスフォーマットの使用
OpenTelemetry は、1 つの仕様と API セットを提供することにより、トレース、ログ、およびメトリクスに関するベンダー固有の形式間の境界や制限を取り除くオープンソースのイニシアチブです。詳細については、「[OpenTelemetry](https://opentelemetry.io/)」を参照してください。埋め込みメトリックフォーマットは、OpenTelemetry プロジェクトの一部として使用できます。OpenTelemetry で埋め込みメトリクスフォーマットを使用するには、OpenTelemetry に準拠しているデータソースと、CloudWatch 埋め込みメトリクスフォーマットログで使用できる AWS Distro for OpenTelemetry の 2 つのコンポーネントが必要です。
OpenTelemetry コンポーネントの再配布は、AWS によって維持され、オンボーディングをできるだけ簡単にするために事前設定されています。埋め込みメトリクスフォーマットで OpenTelemetry を使用する方法については、他の AWS のサービスに加えて、「[AWS Distro for OpenTelemetry](https://aws-otel.github.io/)」を参照してください。言語サポートと使用方法の詳細については、「[AWS Observability on Github](https://github.com/aws-observability)」を参照してください。
# コンソールでのメトリクスおよびログの表示
メトリクスを抽出する埋め込みメトリクスフォームログを生成した後、CloudWatch コンソールを使用してメトリクスを表示できます。埋め込みメトリックには、ログの生成時に指定したディメンションがあります。また、クライアントライブラリを使用して生成した埋め込みメトリクスには、次のデフォルトのディメンションもあります。
+ ServiceType
+ ServiceName
+ LogGroup
このセクションでは、CloudWatch コンソールでこれらのメトリクスを表示し、[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) を使用して抽出されたメトリクスをクエリする方法について説明します。
**埋め込みメトリックフォーマットログから生成されたメトリックを表示するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで [**Metrics (メトリクス)**] を選択してください。
1. 埋め込みメトリックの生成時に指定した名前空間を選択します。クライアントライブラリを使用してメトリックを生成し、名前空間を指定しなかった場合は、[**aws-embedded-metrics**] を選択します。これは、クライアントライブラリを使用して生成された埋め込みメトリックのデフォルトの名前空間です。
1. メトリックディメンション（[**ServiceName**] など）を選択します。
1. [**All metrics**] タブには、名前空間内のそのディメンションのメトリクスがすべて表示されます。以下の操作を行うことができます。
1. テーブルを並べ替えるには、列見出しを使用します。
1. メトリクスをグラフ表示するには、メトリクスの横にあるチェックボックスを選択します。すべてのメトリクスを選択するには、テーブルの見出し行にあるチェックボックスを選択します。
1. リソースでフィルタするには、リソース ID を選択し、[**Add to search**] を選択します。
1. メトリクスでフィルタするには、メトリクスの名前を選択し、[**Add to search**] を選択します。
**CloudWatch Logs Insights を使用したログのクエリ**
CloudWatch Logs Insights を使用して、抽出されたメトリクスに関連付けられた詳細なログイベントをクエリし、運用イベントの根本原因に関する深い洞察を提供できます。ログからメトリックを抽出する利点の 1 つは、後で一意のメトリック（メトリック名と一意のディメンションセット）とメトリック値でログをフィルタリングし、集計されたメトリック値に寄与したイベントのコンテキストを取得できることです。
例えば、影響を受けたリクエスト ID または X-Ray トレース ID を取得するには、CloudWatch Logs Insights で次のクエリを実行します。
```
filter Latency > 1000 and Operation = "Aggregator"
| fields RequestId, TraceId
```
また、イベントによって影響を受けた顧客を見つけるなど、高カーディナリティキーに対してクエリ時集計を実行することもできます。以下に示しているのはこのポリシーの例です。
```
filter Latency > 1000 and Operation = "Aggregator"
| stats count() by CustomerId
```
詳細については、「[CloudWatch Logs Insights を使用したログデータの分析](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)」を参照してください
# 埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する
通常、埋め込みメトリクスフォーマットで生成されたメトリクスに対してアラームを作成する場合、他のメトリクスにアラームを作成する場合と同じパターンに従います。詳細については、「[Amazon CloudWatch でのアラームの使用](CloudWatch_Alarms.md)」を参照してください。CloudWatch Logs はログをメトリクスに変換できるように処理する必要があるため、埋め込みメトリクスフォーマットのメトリクス生成はログ公開フローによって異なります。アラームが評価される期間内にメトリクスデータポイントが作成されるように、ログを適時に公開することが重要です。
埋め込みメトリクスフォーマットを使用して高解像度のメトリクスを送信し、そのメトリクスに対してアラームを作成する場合は、5 秒以下の間隔でログを CloudWatch Logs にフラッシュすることをお勧めします。これにより、データが一部しかない、または見つからない際に発生するアラームの原因となる追加の遅延が発生するのを避けることができます。CloudWatch エージェントを使用している場合は、CloudWatch エージェント設定ファイルで `force_flush_interval` パラメータを設定することでフラッシュ間隔を調整できます。この値のデフォルトは 5 秒です。ログのフラッシュ間隔を制御できない他のプラットフォームで Lambda を使用している場合は、「N 中の M」アラームを使用して、アラームに使用するデータポイントの数を制御することを検討してください。詳細については、「[アラーム評価](alarm-evaluation.md)」を参照してください。