# 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 行にする必要があります。つまり、ログイベントに改行 (\\n) 文字を含めることはできません。
ログイベントは、埋め込みメトリックフォーマットの仕様に従う必要もあります。詳細については、「[仕様: 埋め込みメトリクスフォーマット](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)」を参照してください。