ステップ 1: アカウントで Application Signals を有効にするステップ 2: IAM ロールを作成するステップ 3: CloudWatch エージェント設定を準備するステップ 4: CloudWatch エージェントを使用してアプリケーションを計測するステップ 5: アプリケーションをデプロイする

カスタムセットアップを使用して Amazon ECS で Application Signals を有効にする

Amazon ECS で稼働するアプリケーションを CloudWatch Application Signals にオンボーディングするには、次のカスタムセットアップの手順を実行します。CloudWatch エージェントと AWS Distro for OpenTelemetry は、ご自身でインストールし、設定します。

重要

awsvpc ネットワークモードのみサポートされています。EC2 と Fargate の両方の起動タイプがサポートされています。

Amazon ECS クラスターの Application Signals では、サービスの名前が自動検出されません。カスタムセットアップの際にサービス名を指定する必要があります。ここで指定した名前が Application Signals ダッシュボードに表示されことになります。

ステップ 1: アカウントで Application Signals を有効にする

このアカウントで Application Signals をまだ有効にしていない場合は、サービスの検出に必要なアクセス権限を Application Signals に付与する必要があります。このためには、次の操作を行います。この操作はアカウントごとに 1 回のみ必要です。

特定のアプリケーション向けに Application Signals を有効にするには

CloudWatch コンソール (https://console.aws.amazon.com/cloudwatch/) を開きます。
ナビゲーションペインで [Services (サービス)] を選択します。
[サービスの検出を開始] を選択します。
チェックボックスを選択し、[サービスの検出を開始] を選択します。

このステップをアカウントで初めて完了すると、[AWSServiceRoleForCloudWatchApplicationSignals] サービスリンクロールが作成されます。このロールによって、Application Signals に次のアクセス権限が付与されます。
- xray:GetServiceGraph
- logs:StartQuery
- logs:GetQueryResults
- cloudwatch:GetMetricData
- cloudwatch:ListMetrics
- tag:GetResources
このロールの詳細については、「CloudWatch Application Signals のサービスリンクロールのアクセス許可」を参照してください。

ステップ 2: IAM ロールを作成する

IAM ロールを作成する必要があります。このロールが作成済みであっても、アクセス権限の追加が必要となる場合があります。

ECS タスクロール – コンテナは、このロールを使用して実行します。アクセス権限では、アプリケーションに必要な権限の他に、CloudWatchAgentServerPolicy を指定する必要があります。

IAM ロールの作成についての詳細は、「IAM ロールの作成」を参照してください。

ステップ 3: CloudWatch エージェント設定を準備する

最初に、Application Signals を有効にしてエージェント設定を準備します。これを行うには、/tmp/ecs-cwagent.json という名前のローカルファイルを作成します。


{
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}

次に、この設定を SSM Parameter Store にアップロードします。これを行うには、次のコマンドを入力します。ファイル内の $REGION を実際のリージョン名に置き換えます。


aws ssm put-parameter \
--name "ecs-cwagent" \
--type "String" \
--value "`cat /tmp/ecs-cwagent.json`" \
--region "$REGION"

ステップ 4: CloudWatch エージェントを使用してアプリケーションを計測する

次のステップは、CloudWatch Application Signals のアプリケーションを計測することです。

Java

CloudWatch エージェントを使用して Amazon ECS で稼働するアプリケーションを計測するには

最初に、バインドマウントを指定します。次のステップでは、このボリュームを使用してコンテナ間でファイルを共有します。このバインドマウントは、そのステップの後半で使用します。
```
"volumes": [
  {
    "name": "opentelemetry-auto-instrumentation"
  }
]
```
CloudWatch エージェントのサイドカー定義を追加します。これを行うには、ecs-cwagent という新規コンテナをアプリケーションのタスク定義に追加します。$REGION は実際のリージョン名に置き換えてください。また、$IMAGE を Amazon Elastic Container Registry にある最新の CloudWatch コンテナイメージへのパスに置き換えます。詳細については、Amazon ECR の「cloudwatch-agent」を参照してください。
```
{
  "name": "ecs-cwagent",
  "image": "$IMAGE",
  "essential": true,
  "secrets": [
    {
      "name": "CW_CONFIG_CONTENT",
      "valueFrom": "ecs-cwagent"
    }
  ],
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-create-group": "true",
      "awslogs-group": "/ecs/ecs-cwagent",
      "awslogs-region": "$REGION",
      "awslogs-stream-prefix": "ecs"
    }
  }
}
```

アプリケーションのタスク定義に新規コンテナ init を追加します。$IMAGE は、AWS Distro for OpenTelemetry Amazon ECR イメージリポジトリにある最新イメージに置き換えてください。


{
  "name": "init",
  "image": "$IMAGE",
  "essential": false,
  "command": [
    "cp",
    "/javaagent.jar",
    "/otel-auto-instrumentation/javaagent.jar"
  ],
  "mountPoints": [
    {
      "sourceVolume": "opentelemetry-auto-instrumentation",
      "containerPath": "/otel-auto-instrumentation",
      "readOnly": false
    }
  ]
}

次の環境変数をアプリケーションコンテナに追加します。Java の場合、AWS Distro for OpenTelemetry 自動計測エージェントのバージョン 1.32.2 以降を使用している必要があります

環境変数	Application Signals を有効にする設定
`OTEL_RESOURCE_ATTRIBUTES`	次の情報をキーと値のペアとして指定します。サービス名を設定するには、`service.name` を使用します。これは、Application Signals ダッシュボードにアプリケーションのサービス名として表示されます。このキーの値を指定しない場合、`UnknownService` (デフォルト値) が使用されます。アプリケーションの稼働環境を設定するには、`deployment.environment` を使用します。これは、アプリケーションの [ホスト元] 環境として Application Signals ダッシュボードに表示されます。これを指定しない場合、デフォルト値の `generic:default` が使用されます。この属性キーは Application Signals にのみ使用され、X-Ray トレースのアノテーションと CloudWatch メトリクスのディメンションに変換されます。 (オプション) トレースログの相関を有効にするには、追加で環境変数 `aws.log.group.names` にアプリケーションログのロググループ名を設定します。これにより、アプリケーションが生成したトレースをこの特定のロググループ内の該当するログエントリと関連付けることができます。この変数では、`$YOUR_APPLICATION_LOG_GROUP` をアプリケーションのロググループ名に置き換えます。また、アプリケーションのログ記録設定を変更する必要があります。詳細については、「トレースログの相関を有効にする」を参照してください。
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	`true` に設定すると、コンテナが X-Ray トレースと CloudWatch メトリクスを Application Signals に送信し始めます。
`OTEL_METRICS_EXPORTER`	他のメトリクスエクスポーターを無効にするには `none` に設定します。
`OTEL_LOGS_EXPORTER`	他のログエクスポーターを無効にするには `none` に設定します。
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf` に設定すると、HTTP を使用してメトリクスとトレースを Application Signals に送信できます。
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	CloudWatch サイドカーにメトリクスを送信するには、`http://localhost:4316/v1/metrics` に設定します。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	トレースを CloudWatch サイドカーに送信するには、`http://localhost:4316/v1/traces` に設定します。
`OTEL_TRACES_SAMPLER`	`xray` に設定すると、X-Ray をトレースの見本として設定できます。
`OTEL_PROPAGATORS`	`xray` をプロパゲーターの 1 つとして設定します。
`JAVA_TOOL_OPTIONS`	`" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"` に設定すると、`AWS_ADOT_JAVA_INSTRUMENTATION_PATH` を AWS Distro for OpenTelemetry Java 自動計測エージェントが保存されているパスに置き換えることができます。例えば、`/otel-auto-instrumentation/javaagent.jar`

この手順のステップ 1 で定義したボリューム opentelemetry-auto-instrumentation をマウントします。

Java アプリケーションの場合は、以下を使用してください。


{
  "name": "my-app",
   ...
  "environment": [
    {
      "name": "OTEL_RESOURCE_ATTRIBUTES",
      "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME"
    },
    {
      "name": "OTEL_LOGS_EXPORTER",
      "value": "none"
    },
    {
      "name": "OTEL_METRICS_EXPORTER",
      "value": "none"
    },
    {
      "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
      "value": "http/protobuf"
    },
    {
      "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
      "value": "true"
    },
    {
      "name": "JAVA_TOOL_OPTIONS",
      "value": " -javaagent:/otel-auto-instrumentation/javaagent.jar"
    },
    {
      "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
      "value": "http://localhost:4316/v1/metrics"
    },
    {
      "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
      "value": "http://localhost:4316/v1/traces"
    },
    {
      "name": "OTEL_TRACES_SAMPLER",
      "value": "xray"
    },
    {
      "name": "OTEL_PROPAGATORS",
      "value": "tracecontext,baggage,b3,xray"
    }
  ],
  "mountPoints": [
    {
      "sourceVolume": "opentelemetry-auto-instrumentation",
      "containerPath": "/otel-auto-instrumentation",
      "readOnly": false
    }
  ]
}

Python

Python アプリケーションの Application Signals を有効にする前に、以下の考慮事項に注意してください。

コンテナ化されたアプリケーションの一部は、PYTHONPATH 環境変数がないことが原因でアプリケーションが起動しなくなることがあります。これを解決するには、PYTHONPATH 環境変数をアプリケーションの作業ディレクトリの場所に設定します。これは OpenTelemetry の自動計測に関する既知の問題によるものです。この問題の詳細については、「Python autoinstrumentation setting of PYTHONPATH is not compliant」を参照してください。
Django アプリケーションには、OpenTelemetry Python ドキュメントで概説されている追加の必須設定があります。
- --noreload フラグを使用すると、自動リロードを防ぐことができます。
- Django アプリケーションの settings.py ファイルの場所に DJANGO_SETTINGS_MODULE 環境変数を設定します。これにより、OpenTelemetry がユーザーの Django 設定に正しくアクセスして統合できるようになります。

CloudWatch エージェントを使用して Amazon ECS で稼働する Python アプリケーションを計測するには

最初に、バインドマウントを指定します。次のステップでは、このボリュームを使用してコンテナ間でファイルを共有します。このバインドマウントは、そのステップの後半で使用します。
```
"volumes": [
  {
    "name": "opentelemetry-auto-instrumentation-python"
  }
]
```
CloudWatch エージェントのサイドカー定義を追加します。これを行うには、ecs-cwagent という新規コンテナをアプリケーションのタスク定義に追加します。$REGION は実際のリージョン名に置き換えてください。また、$IMAGE を Amazon Elastic Container Registry にある最新の CloudWatch コンテナイメージへのパスに置き換えます。詳細については、Amazon ECR の「cloudwatch-agent」を参照してください。
```
{
  "name": "ecs-cwagent",
  "image": "$IMAGE",
  "essential": true,
  "secrets": [
    {
      "name": "CW_CONFIG_CONTENT",
      "valueFrom": "ecs-cwagent"
    }
  ],
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-create-group": "true",
      "awslogs-group": "/ecs/ecs-cwagent",
      "awslogs-region": "$REGION",
      "awslogs-stream-prefix": "ecs"
    }
  }
}
```


{
    "name": "init",
    "image": "$IMAGE",
    "essential": false,
    "command": [
        "cp",
        "-a",
        "/autoinstrumentation/.",
        "/otel-auto-instrumentation-python"
    ],
    "mountPoints": [
        {
            "sourceVolume": "opentelemetry-auto-instrumentation-python",
            "containerPath": "/otel-auto-instrumentation-python",
            "readOnly": false
        }
    ]
}

次の環境変数をアプリケーションコンテナに追加します。

環境変数	Application Signals を有効にする設定
`OTEL_RESOURCE_ATTRIBUTES`	次の情報をキーと値のペアとして指定します。サービス名を設定するには、`service.name` を使用します。これは、Application Signals ダッシュボードにアプリケーションのサービス名として表示されます。このキーの値を指定しない場合、`UnknownService` (デフォルト値) が使用されます。アプリケーションの稼働環境を設定するには、`deployment.environment` を使用します。これは、アプリケーションの [ホスト元] 環境として Application Signals ダッシュボードに表示されます。これを指定しない場合、デフォルト値の `generic:default` が使用されます。この属性キーは Application Signals にのみ使用され、X-Ray トレースのアノテーションと CloudWatch メトリクスのディメンションに変換されます。 (オプション) トレースログの相関を有効にするには、追加で環境変数 `aws.log.group.names` にアプリケーションログのロググループ名を設定します。これにより、アプリケーションが生成したトレースをこの特定のロググループ内の該当するログエントリと関連付けることができます。この変数では、`$YOUR_APPLICATION_LOG_GROUP` をアプリケーションのロググループ名に置き換えます。また、アプリケーションのログ記録設定を変更する必要があります。詳細については、「トレースログの相関を有効にする」を参照してください。
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	`true` に設定すると、コンテナが X-Ray トレースと CloudWatch メトリクスを Application Signals に送信し始めます。
`OTEL_METRICS_EXPORTER`	他のメトリクスエクスポーターを無効にするには `none` に設定します。
`OTEL_EXPORTER_OTLP_PROTOCOL`	HTTP を使用して CloudWatch にメトリクスとトレースを送信するには、`http/protobuf` に設定します。
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	CloudWatch サイドカーにメトリクスを送信するには、`http://127.0.0.1:4316/v1/metrics` に設定します。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	トレースを CloudWatch サイドカーに送信するには、`http://127.0.0.1:4316/v1/traces` に設定します。
`OTEL_TRACES_SAMPLER`	`xray` に設定すると、X-Ray をトレースの見本として設定できます。
`OTEL_PROPAGATORS`	プロパゲーターの 1 つとして `xray` を追加します。
`OTEL_PYTHON_DISTRO`	ADOT Python 計測を使用するには、`aws_distro` に設定します。
`OTEL_PYTHON_CONFIGURATOR`	ADOT Python コンフィギュレーションを使用するには、`aws_configuration` に設定します。
`PYTHONPATH`	`$APP_PATH` をコンテナ内のアプリケーションの作業ディレクトリの場所に置き換えます。これは Python インタープリターがアプリケーションモジュールを見つけるために必要です。
`DJANGO_SETTINGS_MODULE`	Django アプリケーションでのみ必要です。これは Django アプリケーションの `settings.py` ファイルの場所に設定してください。`$PATH_TO_SETTINGS` を置換します。

この手順のステップ 1 で定義したボリューム opentelemetry-auto-instrumentation-python をマウントします。以下の例では、OTEL_RESOURCE_ATTRIBUTES の値にオプションの aws.log.group.names などがあり、トレースログの相関を有効にできます。詳細については、前のステップの表を参照してください。

Python アプリケーションの場合は、以下を使用します。


{
  "name": "my-app",
  ...
  "environment": [
    {
      "name": "PYTHONPATH",
      "value": "/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:$APP_PATH:/otel-auto-instrumentation-python"
    },
    {
      "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
      "value": "http/protobuf"
    },
    {
      "name": "OTEL_TRACES_SAMPLER",
      "value": "xray"
    },
    {
      "name": "OTEL_TRACES_SAMPLER_ARG",
      "value": "endpoint=http://localhost:2000"
    },
    {
      "name": "OTEL_LOGS_EXPORTER",
      "value": "none"
    },
    {
      "name": "OTEL_PYTHON_DISTRO",
      "value": "aws_distro"
    },
    {
      "name": "OTEL_PYTHON_CONFIGURATOR",
      "value": "aws_configurator"
    },
    {
      "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
      "value": "http://localhost:4316/v1/traces"
    },
    {
      "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
      "value": "http://localhost:4316/v1/metrics"
    },
    {
      "name": "OTEL_METRICS_EXPORTER",
      "value": "none"
    },
    {
      "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
      "value": "true"
    },
    {
      "name": "OTEL_RESOURCE_ATTRIBUTES",
      "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME"
    },
    {
      "name": "DJANGO_SETTINGS_MODULE",
      "value": "$PATH_TO_SETTINGS.settings"
    }
  ],
  "mountPoints": [
    {
      "sourceVolume": "opentelemetry-auto-instrumentation-python",
      "containerPath": "/otel-auto-instrumentation-python",
      "readOnly": false
    }
  ]
}

ステップ 5: アプリケーションをデプロイする

タスク定義のリビジョンを新規作成し、アプリケーションクラスターにデプロイします。新規作成したタスクに次の 3 つのコンテナが表示されます。

init
ecs-cwagent
my-app

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

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

ドキュメントの表記規則

Amazon EC2、Amazon ECS、または Kubernetes で Application Signals を有効にする

Amazon EC2 で Application Signals を有効にする