CloudWatch エージェントのインストール CloudWatch エージェントを使用した埋め込みメトリクスフォーマットログの送信

CloudWatch エージェントを使用した埋め込みメトリクスフォーマットログの送信

このセクションでは、CloudWatch エージェントをインストールして使用する方法について説明します。このセクションの最初の部分では、CloudWatch エージェントをインストールする方法について説明します。このセクションの 2 番目の部分では、CloudWatch エージェントを使用して埋め込みメトリクスフォーマットログを送信する方法について説明します。この方法を使用する場合は、埋め込みメトリクスフォーマットログを送信する AWS のサービスの CloudWatch エージェントをインストールする必要があります。その後、イベントの送信を開始できます。CloudWatch エージェントは、バージョン 1.230621.0 以降である必要があります。

注記

Lambda 関数からログを送信するために CloudWatch エージェントをインストールする必要はありません。

Lambda 関数のタイムアウトは自動的に処理されません。つまり、メトリックがフラッシュされる前に関数がタイムアウトすると、その呼び出しのメトリックはキャプチャされません。

CloudWatch エージェントのインストール

埋め込みメトリクスフォーマットログを送信するサービスごとに CloudWatch エージェントをインストールします。

EC2 への CloudWatch エージェントのインストール

まず、インスタンスに CloudWatch エージェントをインストールします。(詳細については、CloudWatch エージェントのインストールを参照してください)。

エージェントをインストールしたら、埋め込みメトリックフォーマットログを UDP または TCP ポートでリッスンするようにエージェントを設定します。次に、デフォルトソケット tcp:25888 をリッスンするこの設定の例を示します。エージェント設定の詳細については、「CloudWatch エージェント設定ファイルを手動で作成または編集する」を参照してください。


{
  "logs": {
    "metrics_collected": {
      "emf": { }
    }
  }
}

Amazon ECS への CloudWatch エージェントのインストール

Amazon ECS に CloudWatch エージェントをデプロイする最も簡単な方法は、それをサイドカーとして実行し、アプリケーションと同じタスク定義で定義することです。

エージェント設定ファイルを作成する

CloudWatch エージェント設定ファイルをローカルに作成します。この例では、相対ファイルパスは amazon-cloudwatch-agent.json になります。

エージェント設定の詳細については、「CloudWatch エージェント設定ファイルを手動で作成または編集する」を参照してください。


{
  "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 サンプルリポジトリを参照してください。

次に、ブリッジモードの例を示します。ブリッジモードネットワーキングが有効な場合、エージェントは 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 ゲートウェイ」を参照してください。CloudWatch Logs VPC エンドポイントの設定の詳細については、「CloudWatch Logs とインターフェイス VPC エンドポイントの使用」を参照してください。

次に、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 がアタッチされている必要があります。詳細については、「セットアップガイド (AWS CLI)」を参照してください。

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) 文字を含めることはできません。

ログイベントは、埋め込みメトリックフォーマットの仕様に従う必要もあります。詳細については、「仕様: 埋め込みメトリクスフォーマット」を参照してください。

埋め込みメトリクス形式を使用して作成されたメトリクスに対してアラームを作成する予定がある場合は、「埋め込みメトリクス形式で作成されたメトリクスにアラームを設定する」の推奨事項を参照してください。

次に、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 メトリクスによるモニタリング」を参照してください。

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

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

ドキュメントの表記規則

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

OpenTelemetry 用の AWS ディストリビューションでの埋め込みメトリクスフォーマットの使用