# Amazon ECS에서 애플리케이션 활성화
이 섹션에 설명된 사용자 지정 설정 단계를 사용하여 Amazon ECS에서 CloudWatch Application Signals를 활성화합니다.
Amazon ECS에서 실행되는 애플리케이션의 경우 CloudWatch 에이전트와 AWS Distro for OpenTelemetry를 직접 설치하고 구성합니다. 사용자 지정 Application Signals 설정으로 활성화된 이러한 아키텍처에서는 Application Signals가 서비스 이름이나 서비스가 실행되는 호스트 또는 클러스터를 자동으로 검색하지 않습니다. 사용자 지정 설정 중에 이러한 이름을 지정해야 하며, 지정하는 이름은 Application Signals 대시보드에 표시됩니다.
## 사용자 지정 설정을 사용하여 Amazon ECS에서 Application Signals를 활성화합니다.
이 사용자 지정 설정 지침을 사용하여 Amazon ECS의 애플리케이션을 CloudWatch Application Signals에 온보딩합니다. CloudWatch 에이전트와 AWS Distro for OpenTelemetry를 직접 설치하고 구성합니다.
Amazon ECS에 Application Signals를 배포하는 방법에는 두 가지가 있습니다. 환경에 가장 적합한 것을 선택하세요.
+ [사이드카 전략을 사용한 배포](CloudWatch-Application-Signals-ECS-Sidecar.md) - 클러스터의 각 태스크 정의에 CloudWatch 에이전트 사이드카 컨테이너를 추가합니다.
장점:
+ `ec2` 및 `Fargate` 시작 유형을 모두 지원합니다.
+ 환경 변수를 설정할 때 `localhost`를 항상 IP 주소로 사용할 수 있습니다.
단점:
+ 클러스터에서 실행되는 각 서비스 태스크에 대해 CloudWatch 에이전트 사이드카 컨테이너를 설정해야 합니다.
+ `awsvpc` 네트워크 모드만 지원됩니다.
+ [대몬 전략을 사용하여 배포](CloudWatch-Application-Signals-ECS-Daemon.md) - 클러스터에 CloudWatch 에이전트 태스크를 한 번만 추가하면 [Amazon ECS 대몬 예약 전략](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html#service_scheduler_daemon)이 필요에 따라 배포합니다. 이는 각 인스턴스가 트레이스 및 지표를 지속적으로 수신하도록 하여 에이전트가 각 애플리케이션 태스크 정의와 함께 사이드카로 실행할 필요 없이 중앙 집중식 가시성을 제공합니다.
장점:
+ 클러스터에서 CloudWatch 에이전트에 대한 대몬 서비스를 한 번만 설정하면 됩니다.
단점:
+ Fargate 시작 유형을 지원하지 않습니다.
+ `awsvpc` 또는 `bridge` 네트워크 모드를 사용하는 경우 환경 변수에서 각 컨테이너 인스턴스의 프라이빗 IP 주소를 수동으로 지정해야 합니다.
두 모드는 Amazon ECS 클러스터에서 Application Signals가 서비스의 이름을 자동으로 검색하지 않습니다. 사용자 지정 설정 중 서비스 이름을 지정해야 하며 해당 이름은 Application Signals 대시보드에 표시됩니다.
# 사이드카 전략을 사용한 배포
## 1단계: 계정에서 Application Signals 활성화
먼저 계정에서 Application Signals를 활성화해야 합니다. 그렇지 않은 경우 [계정에서 Application Signals 활성화](CloudWatch-Application-Signals-Enable.md) 섹션을 참조하세요.
## 2단계: IAM 역할 생성
IAM 역할을 생성해야 합니다. 이 역할을 이미 생성한 경우 권한을 추가해야 할 수 있습니다.
+ **ECS 태스크 역할** - 컨테이너는 이 역할을 사용하여 실행됩니다. **CloudWatchAgentServerPolicy** 외에도 권한은 애플리케이션에 필요한 것이어야 합니다.
IAM 역할 생성에 대한 자세한 내용은 [IAM 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html) 단원을 참조하세요.
## 3단계: CloudWatch 에이전트 구성 준비
먼저 Application Signals가 활성화된 에이전트 구성을 준비합니다. 이렇게 하려면 `/tmp/ecs-cwagent.json`이라는 로컬 파일을 생성합니다.
```
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
```
그런 다음, 이 구성을 SSM Parameter Store에 업로드합니다. 이를 위해 다음 명령을 입력합니다. 파일에서 *\$1REGION*을 실제 리전 이름으로 바꿉니다.
```
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에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation"
}
]
```
1. CloudWatch 에이전트 사이드카 정의를 추가합니다. 이렇게 하려면 애플리케이션의 작업 정의에 `ecs-cwagent`라는 새 컨테이너를 추가합니다. *\$1REGION*을 실제 리전 이름으로 바꿉니다. *\$1IMAGE*를 Amazon Elastic Container Registry의 최신 CloudWatch 컨테이너 이미지 경로로 바꿉니다. 자세한 내용은 Amazon ECR의 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)를 참조하세요.
대신 대몬 전략으로 CloudWatch 에이전트를 활성화하려면 [대몬 전략을 사용하여 배포](CloudWatch-Application-Signals-ECS-Daemon.md)의 지침을 참조하세요.
```
{
"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"
}
}
}
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)의 최신 이미지로 바꿉니다.
```
{
"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
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다. Java용 AWS Distro for OpenTelemetry [자동 계측 에이전트](https://opentelemetry.io/docs/zero-code/java/agent/) 버전 1.32.2 이상을 사용해야 합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 Java 애플리케이션에 대한 다음 예제를 사용합니다. 로그 상관 관계를 활성화하려면 다음 단계를 대신 참조하세요.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "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"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"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](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)를 참조하세요.
+ Django 애플리케이션의 경우 추가 필수 구성이 있으며, [OpenTelemetry Python 설명서](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)에서 설명합니다.
+ `--noreload` 플래그를 사용하여 자동 재로드를 방지합니다.
+ `DJANGO_SETTINGS_MODULE` 환경 변수를 Django 애플리케이션 `settings.py` 파일의 위치로 설정합니다. 이렇게 하면 OpenTelemetry가 올바르게 액세스하여 Django 설정에 통합할 수 있습니다.
+ Python 애플리케이션에 WSGI 서버를 사용하는 경우 이 섹션의 다음 단계 외에도 [WSGI 서버를 사용하는 Python 애플리케이션에 대한 Application Signals 데이터 없음](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) 섹션을 참조하여 Application Signals 작동 정보를 확인하세요.
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 Python 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation-python"
}
]
```
1. CloudWatch 에이전트 사이드카 정의를 추가합니다. 이렇게 하려면 애플리케이션의 작업 정의에 `ecs-cwagent`라는 새 컨테이너를 추가합니다. *\$1REGION*을 실제 리전 이름으로 바꿉니다. *\$1IMAGE*를 Amazon Elastic Container Registry의 최신 CloudWatch 컨테이너 이미지 경로로 바꿉니다. 자세한 내용은 Amazon ECR의 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)를 참조하세요.
대신 대몬 전략으로 CloudWatch 에이전트를 활성화하려면 [대몬 전략을 사용하여 배포](CloudWatch-Application-Signals-ECS-Daemon.md)의 지침을 참조하세요.
```
{
"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"
}
}
}
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python)의 최신 이미지로 바꿉니다.
```
{
"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
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation-python`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 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": "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
}
]
}
```
1. (선택 사항) 로그 상관 관계를 활성화하려면 볼륨을 마운트하기 전에 다음을 수행하세요. `OTEL_RESOURCE_ATTRIBUTES`에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 `aws.log.group.names`를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP*을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(`&`)를 사용하여 로그 그룹을 구분할 수 있습니다. `aws.log.group.names=log-group-1&log-group-2` 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 [로그 상관 관계에 대한 지표 활성화](Application-Signals-MetricLogCorrelation.md) 섹션을 참조하세요. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 [로그 상관 관계에 대한 추적 활성화](Application-Signals-TraceLogCorrelation.md) 섹션을 참조하세요.
다음은 예입니다. 로그 상관 관계를 활성화하려면 이 절차의 1단계에서 정의한 `opentelemetry-auto-instrumentation-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,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
}
]
}
```
------
#### [ .NET ]
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation"
}
]
```
1. CloudWatch 에이전트 사이드카 정의를 추가합니다. 이렇게 하려면 애플리케이션의 작업 정의에 `ecs-cwagent`라는 새 컨테이너를 추가합니다. *\$1REGION*을 실제 리전 이름으로 바꿉니다. *\$1IMAGE*를 Amazon Elastic Container Registry의 최신 CloudWatch 컨테이너 이미지 경로로 바꿉니다. 자세한 내용은 Amazon ECR의 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)를 참조하세요.
대신 대몬 전략으로 CloudWatch 에이전트를 활성화하려면 [대몬 전략을 사용하여 배포](CloudWatch-Application-Signals-ECS-Daemon.md)의 지침을 참조하세요.
```
{
"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"
}
}
}
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet)의 최신 이미지로 바꿉니다.
Linux 컨테이너 인스턴스의 경우 다음을 사용합니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"cp",
"-a",
"autoinstrumentation/.",
"/otel-auto-instrumentation"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "/otel-auto-instrumentation",
"readOnly": false
}
]
}
```
Windows Server 컨테이너 인스턴스의 경우 다음을 사용합니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"CMD",
"/c",
"xcopy",
"/e",
"C:\\autoinstrumentation\\*",
"C:\\otel-auto-instrumentation",
"&&",
"icacls",
"C:\\otel-auto-instrumentation",
"/grant",
"*S-1-1-0:R",
"/T"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "C:\\otel-auto-instrumentation",
"readOnly": false
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다. .NET용 AWS Distro for OpenTelemetry [자동 계측 에이전트](https://opentelemetry.io/docs/zero-code/net/) 버전 1.1.0 이상을 사용해야 합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation`을 마운트합니다. Linux의 경우 다음을 사용합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "service.name=$SVC_NAME"
},
{
"name": "CORECLR_ENABLE_PROFILING",
"value": "1"
},
{
"name": "CORECLR_PROFILER",
"value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
},
{
"name": "CORECLR_PROFILER_PATH",
"value": "/otel-auto-instrumentation/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so"
},
{
"name": "DOTNET_ADDITIONAL_DEPS",
"value": "/otel-auto-instrumentation/AdditionalDeps"
},
{
"name": "DOTNET_SHARED_STORE",
"value": "/otel-auto-instrumentation/store"
},
{
"name": "DOTNET_STARTUP_HOOKS",
"value": "/otel-auto-instrumentation/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
},
{
"name": "OTEL_DOTNET_AUTO_HOME",
"value": "/otel-auto-instrumentation"
},
{
"name": "OTEL_DOTNET_AUTO_PLUGINS",
"value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
},
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=aws-dotnet-service-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": "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_EXPORTER_OTLP_ENDPOINT",
"value": "http://localhost:4316"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://localhost:2000"
},
{
"name": "OTEL_PROPAGATORS",
"value": "tracecontext,baggage,b3,xray"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "/otel-auto-instrumentation",
"readOnly": false
}
]
}
```
Windows Server의 경우 다음을 사용합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "service.name=$SVC_NAME"
},
{
"name": "CORECLR_ENABLE_PROFILING",
"value": "1"
},
{
"name": "CORECLR_PROFILER",
"value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
},
{
"name": "CORECLR_PROFILER_PATH",
"value": "C:\\otel-auto-instrumentation\\win-x64\\OpenTelemetry.AutoInstrumentation.Native.dll"
},
{
"name": "DOTNET_ADDITIONAL_DEPS",
"value": "C:\\otel-auto-instrumentation\\AdditionalDeps"
},
{
"name": "DOTNET_SHARED_STORE",
"value": "C:\\otel-auto-instrumentation\\store"
},
{
"name": "DOTNET_STARTUP_HOOKS",
"value": "C:\\otel-auto-instrumentation\\net\\OpenTelemetry.AutoInstrumentation.StartupHook.dll"
},
{
"name": "OTEL_DOTNET_AUTO_HOME",
"value": "C:\\otel-auto-instrumentation"
},
{
"name": "OTEL_DOTNET_AUTO_PLUGINS",
"value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
},
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=dotnet-service-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": "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_EXPORTER_OTLP_ENDPOINT",
"value": "http://localhost:4316"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://localhost:2000"
},
{
"name": "OTEL_PROPAGATORS",
"value": "tracecontext,baggage,b3,xray"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "C:\\otel-auto-instrumentation",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
------
#### [ Node.js ]
**참고**
ESM을 사용하는 Node.js 애플리케이션용 Application Signals를 활성화하는 경우 이들 단계를 시작하기 전에 [Setting up a Node.js application with the ESM module format](#ECS-NodeJs-ESM)을(를) 참조합니다.
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation-node"
}
]
```
1. CloudWatch 에이전트 사이드카 정의를 추가합니다. 이렇게 하려면 애플리케이션의 작업 정의에 `ecs-cwagent`라는 새 컨테이너를 추가합니다. *\$1REGION*을 실제 리전 이름으로 바꿉니다. *\$1IMAGE*를 Amazon Elastic Container Registry의 최신 CloudWatch 컨테이너 이미지 경로로 바꿉니다. 자세한 내용은 Amazon ECR의 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)를 참조하세요.
대신 대몬 전략으로 CloudWatch 에이전트를 활성화하려면 [대몬 전략을 사용하여 배포](CloudWatch-Application-Signals-ECS-Daemon.md)의 지침을 참조하세요.
```
{
"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"
}
}
}
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node)의 최신 이미지로 바꿉니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"cp",
"-a",
"/autoinstrumentation/.",
"/otel-auto-instrumentation-node"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 Node.js 애플리케이션에 대한 다음 예를 사용합니다. 로그 상관 관계를 활성화하려면 다음 단계를 대신 참조하세요.
애플리케이션 컨테이너의 경우 애플리케이션 컨테이너가 시작되기 전에 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "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": "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_TRACES_SAMPLER_ARG",
"value": "endpoint=http://localhost:2000"
},
{
"name": "NODE_OPTIONS",
"value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
1. (선택 사항) 로그 상관 관계를 활성화하려면 볼륨을 마운트하기 전에 다음을 수행하세요. `OTEL_RESOURCE_ATTRIBUTES`에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 `aws.log.group.names`를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP*을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(`&`)를 사용하여 로그 그룹을 구분할 수 있습니다. `aws.log.group.names=log-group-1&log-group-2` 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 [로그 상관 관계에 대한 지표 활성화](Application-Signals-MetricLogCorrelation.md) 섹션을 참조하세요. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 [로그 상관 관계에 대한 추적 활성화](Application-Signals-TraceLogCorrelation.md) 섹션을 참조하세요.
다음은 예입니다. 이 예제를 사용하여 이 절차의 1단계에서 정의한 `opentelemetry-auto-instrumentation` 볼륨을 마운트할 때 로그 상관 관계를 활성화합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,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": "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_TRACES_SAMPLER_ARG",
"value": "endpoint=http://localhost:2000"
},
{
"name": "NODE_OPTIONS",
"value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
**ESM 모듈 형식으로 Node.js 애플리케이션 설정**
ESM 모듈 형식의 Node.js 애플리케이션을 제한적으로 지원합니다. 자세한 내용은 [ESM 사용 Node.js에 대해 알려진 제한 사항](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)을 참조하세요.
ESM 모듈 형식의 경우 `init` 컨테이너를 사용한 Node.js 계측 SDK 주입에는 해당되지 않습니다. ESM을 사용하는 Node.js용 Application Signals를 활성화하려면 이전 절차의 1단계와 3단계를 건너뛰고 대신 다음을 수행합니다.
**ESM을 사용하는 Node.js 애플리케이션에 Application Signals를 활성화하려면**
1. 관련 종속성을 자동 계측용 Node.js 애플리케이션에 설치합니다.
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
npm install @opentelemetry/instrumentation@0.54.0
```
1. 이전 절차의 5단계와 6단계에서 볼륨 `opentelemetry-auto-instrumentation-node`의 탑재를 제거합니다.
```
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
]
```
노드 옵션을 다음 중 하나로 변경합니다.
```
{
"name": "NODE_OPTIONS",
"value": "--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs"
}
```
------
## 5단계: 애플리케이션 배포
작업 정의의 새 버전을 생성하여 애플리케이션 클러스터에 배포합니다. 새로 생성된 작업에는 세 개의 컨테이너가 표시되어야 합니다.
+ `init`– Application Signals를 초기화하는 데 필요한 컨테이너입니다.
+ `ecs-cwagent`– CloudWatch 에이전트를 실행하는 컨테이너입니다.
+ `my-app`- 설명서의 예제 애플리케이션 컨테이너입니다. 실제 워크로드에서는 이 특정 컨테이너가 존재하지 않거나 자체 서비스 컨테이너로 대체될 수 있습니다.
## (선택 사항) 6단계: 애플리케이션 상태 모니터링
Amazon ECS에서 애플리케이션을 활성화하면 애플리케이션 상태를 모니터링할 수 있습니다. 자세한 내용은 [Application Signals를 사용하여 애플리케이션의 운영 상태 모니터링](Services.md) 섹션을 참조하세요.
# 대몬 전략을 사용하여 배포
## 1단계: 계정에서 Application Signals 활성화
먼저 계정에서 Application Signals를 활성화해야 합니다. 그렇지 않은 경우 [계정에서 Application Signals 활성화](CloudWatch-Application-Signals-Enable.md) 섹션을 참조하세요.
## 2단계: IAM 역할 생성
IAM 역할을 생성해야 합니다. 이 역할을 이미 생성한 경우 권한을 추가해야 할 수 있습니다.
+ **ECS 태스크 역할** - 컨테이너는 이 역할을 사용하여 실행됩니다. **CloudWatchAgentServerPolicy** 외에도 권한은 애플리케이션에 필요한 것이어야 합니다.
IAM 역할 생성에 대한 자세한 내용은 [IAM 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html) 단원을 참조하세요.
## 3단계: CloudWatch 에이전트 구성 준비
먼저 Application Signals가 활성화된 에이전트 구성을 준비합니다. 이렇게 하려면 `/tmp/ecs-cwagent.json`이라는 로컬 파일을 생성합니다.
```
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
```
그런 다음, 이 구성을 SSM Parameter Store에 업로드합니다. 이를 위해 다음 명령을 입력합니다. 파일에서 *\$1REGION*을 실제 리전 이름으로 바꿉니다.
```
aws ssm put-parameter \
--name "ecs-cwagent" \
--type "String" \
--value "`cat /tmp/ecs-cwagent.json`" \
--region "$REGION"
```
## 4단계: CloudWatch 에이전트 대몬 서비스 배포
다음 태스크 정의를 생성하여 애플리케이션 클러스터에 배포합니다. *\$1REGION*을 실제 리전 이름으로 바꿉니다. *\$1TASK\$1ROLE\$1ARN* 및 *\$1EXECUTION\$1ROLE\$1ARN*을 [2단계: IAM 역할 생성](#Application-Signals-Enable-ECS-IAM-Daemon)에서 준비한 IAM 역할로 바꿉니다. *\$1IMAGE*를 Amazon Elastic Container Registry의 최신 CloudWatch 컨테이너 이미지 경로로 바꿉니다. 자세한 내용은 Amazon ECR의 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)를 참조하세요.
**참고**
대몬 서비스는 호스트에 2개의 포트를 노출합니다. 포트 4316은 지표 및 트레이스를 수신하는 엔드포인트로 사용되고 2000은 CloudWatch 트레이스 샘플러 엔드포인트로 사용됩니다. 이 설정을 사용하면 에이전트가 호스트에서 실행되는 모든 애플리케이션 태스크에서 원격 측정 데이터를 수집하고 전송할 수 있습니다. 충돌을 방지하기 위해 호스트의 다른 서비스에서 이러한 포트를 사용하지 않도록 합니다.
```
{
"family": "ecs-cwagent-daemon",
"taskRoleArn": "$TASK_ROLE_ARN",
"executionRoleArn": "$EXECUTION_ROLE_ARN",
"networkMode": "bridge",
"containerDefinitions": [
{
"name": "ecs-cwagent",
"image": "$IMAGE",
"essential": true,
"portMappings": [
{
"containerPort": 4316,
"hostPort": 4316
},
{
"containerPort": 2000,
"hostPort": 2000
}
],
"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"
}
}
}
],
"requiresCompatibilities": [
"EC2"
],
"cpu": "128",
"memory": "64"
}
```
## 5단계: 애플리케이션 계측
다음 단계는 Application Signals에 대해 애플리케이션을 계측하는 것입니다.
------
#### [ Java ]
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation"
}
]
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)의 최신 이미지로 바꿉니다.
```
{
"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
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다. Java용 AWS Distro for OpenTelemetry [자동 계측 에이전트](https://opentelemetry.io/docs/zero-code/java/agent/) 버전 1.32.2 이상을 사용해야 합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Daemon.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 Java 애플리케이션에 대한 다음 예제를 사용합니다. 로그 상관 관계를 활성화하려면 다음 단계를 대신 참조하세요.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "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://CW_CONTAINER_IP:4316/v1/metrics"
},
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_PROPAGATORS",
"value": "tracecontext,baggage,b3,xray"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"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](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)를 참조하세요.
+ Django 애플리케이션의 경우 추가 필수 구성이 있으며, [OpenTelemetry Python 설명서](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)에서 설명합니다.
+ `--noreload` 플래그를 사용하여 자동 재로드를 방지합니다.
+ `DJANGO_SETTINGS_MODULE` 환경 변수를 Django 애플리케이션 `settings.py` 파일의 위치로 설정합니다. 이렇게 하면 OpenTelemetry가 올바르게 액세스하여 Django 설정에 통합할 수 있습니다.
+ Python 애플리케이션에 WSGI 서버를 사용하는 경우 이 섹션의 다음 단계 외에도 [WSGI 서버를 사용하는 Python 애플리케이션에 대한 Application Signals 데이터 없음](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) 섹션을 참조하여 Application Signals 작동 정보를 확인하세요.
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 Python 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation-python"
}
]
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python)의 최신 이미지로 바꿉니다.
```
{
"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
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Daemon.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation-python`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 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://CW_CONTAINER_IP: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://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/metrics"
},
{
"name": "OTEL_METRICS_EXPORTER",
"value": "none"
},
{
"name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
"value": "true"
},
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "service.name=$SVC_NAME"
},
{
"name": "DJANGO_SETTINGS_MODULE",
"value": "$PATH_TO_SETTINGS.settings"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-python",
"containerPath": "/otel-auto-instrumentation-python",
"readOnly": false
}
]
}
```
1. (선택 사항) 로그 상관 관계를 활성화하려면 볼륨을 마운트하기 전에 다음을 수행하세요. `OTEL_RESOURCE_ATTRIBUTES`에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 `aws.log.group.names`를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP*을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(`&`)를 사용하여 로그 그룹을 구분할 수 있습니다. `aws.log.group.names=log-group-1&log-group-2` 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 [로그 상관 관계에 대한 지표 활성화](Application-Signals-MetricLogCorrelation.md) 섹션을 참조하세요. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 [로그 상관 관계에 대한 추적 활성화](Application-Signals-TraceLogCorrelation.md) 섹션을 참조하세요.
다음은 예입니다. 로그 상관 관계를 활성화하려면 이 절차의 1단계에서 정의한 `opentelemetry-auto-instrumentation-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://CW_CONTAINER_IP: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://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://CW_CONTAINER_IP: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,service.name=$SVC_NAME"
},
{
"name": "DJANGO_SETTINGS_MODULE",
"value": "$PATH_TO_SETTINGS.settings"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-python",
"containerPath": "/otel-auto-instrumentation-python",
"readOnly": false
}
]
}
```
------
#### [ .NET ]
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation"
}
]
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet)의 최신 이미지로 바꿉니다.
Linux 컨테이너 인스턴스의 경우 다음을 사용합니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"cp",
"-a",
"autoinstrumentation/.",
"/otel-auto-instrumentation"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "/otel-auto-instrumentation",
"readOnly": false
}
]
}
```
Windows Server 컨테이너 인스턴스의 경우 다음을 사용합니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"CMD",
"/c",
"xcopy",
"/e",
"C:\\autoinstrumentation\\*",
"C:\\otel-auto-instrumentation",
"&&",
"icacls",
"C:\\otel-auto-instrumentation",
"/grant",
"*S-1-1-0:R",
"/T"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "C:\\otel-auto-instrumentation",
"readOnly": false
}
]
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가합니다.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다. .NET용 AWS Distro for OpenTelemetry [자동 계측 에이전트](https://opentelemetry.io/docs/zero-code/net/) 버전 1.1.0 이상을 사용해야 합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Daemon.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation`을 마운트합니다. Linux의 경우 다음을 사용합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "service.name=$SVC_NAME"
},
{
"name": "CORECLR_ENABLE_PROFILING",
"value": "1"
},
{
"name": "CORECLR_PROFILER",
"value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
},
{
"name": "CORECLR_PROFILER_PATH",
"value": "/otel-auto-instrumentation/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so"
},
{
"name": "DOTNET_ADDITIONAL_DEPS",
"value": "/otel-auto-instrumentation/AdditionalDeps"
},
{
"name": "DOTNET_SHARED_STORE",
"value": "/otel-auto-instrumentation/store"
},
{
"name": "DOTNET_STARTUP_HOOKS",
"value": "/otel-auto-instrumentation/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
},
{
"name": "OTEL_DOTNET_AUTO_HOME",
"value": "/otel-auto-instrumentation"
},
{
"name": "OTEL_DOTNET_AUTO_PLUGINS",
"value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
},
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=dotnet-service-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": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://localhost:4316/v1/metrics"
},
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_EXPORTER_OTLP_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://CW_CONTAINER_IP:2000"
},
{
"name": "OTEL_PROPAGATORS",
"value": "tracecontext,baggage,b3,xray"
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "/otel-auto-instrumentation",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
Windows Server의 경우 다음을 사용합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "service.name=$SVC_NAME"
},
{
"name": "CORECLR_ENABLE_PROFILING",
"value": "1"
},
{
"name": "CORECLR_PROFILER",
"value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
},
{
"name": "CORECLR_PROFILER_PATH",
"value": "C:\\otel-auto-instrumentation\\win-x64\\OpenTelemetry.AutoInstrumentation.Native.dll"
},
{
"name": "DOTNET_ADDITIONAL_DEPS",
"value": "C:\\otel-auto-instrumentation\\AdditionalDeps"
},
{
"name": "DOTNET_SHARED_STORE",
"value": "C:\\otel-auto-instrumentation\\store"
},
{
"name": "DOTNET_STARTUP_HOOKS",
"value": "C:\\otel-auto-instrumentation\\net\\OpenTelemetry.AutoInstrumentation.StartupHook.dll"
},
{
"name": "OTEL_DOTNET_AUTO_HOME",
"value": "C:\\otel-auto-instrumentation"
},
{
"name": "OTEL_DOTNET_AUTO_PLUGINS",
"value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
},
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=dotnet-service-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": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/metrics"
},
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_EXPORTER_OTLP_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://CW_CONTAINER_IP:2000"
},
{
"name": "OTEL_PROPAGATORS",
"value": "tracecontext,baggage,b3,xray"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation",
"containerPath": "C:\\otel-auto-instrumentation",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
------
#### [ Node.js ]
**참고**
ESM을 사용하는 Node.js 애플리케이션용 Application Signals를 활성화하는 경우 이들 단계를 시작하기 전에 [Setting up a Node.js application with the ESM module format](#ECSDaemon-NodeJs-ESM)을(를) 참조합니다.
**CloudWatch 에이전트를 사용하여 Amazon ECS에서 애플리케이션 계측**
1. 먼저 바인드 탑재를 지정합니다. 다음 단계에서 이 볼륨은 컨테이너 간에 파일을 공유하는 데 사용됩니다. 이 바인드 탑재는 이 절차의 뒷부분에서 사용합니다.
```
"volumes": [
{
"name": "opentelemetry-auto-instrumentation-node"
}
]
```
1. 애플리케이션의 작업 정의에 새 컨테이너 `init`를 추가합니다. *\$1IMAGE*를 [AWS Distro for OpenTelemetry Amazon ECR 이미지 리포지토리](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node)의 최신 이미지로 바꿉니다.
```
{
"name": "init",
"image": "$IMAGE",
"essential": false,
"command": [
"cp",
"-a",
"/autoinstrumentation/.",
"/otel-auto-instrumentation-node"
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
}
```
1. 애플리케이션 컨테이너가 시작되기 전에 이 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가하세요.
```
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
```
1. 애플리케이션 컨테이너에 다음 환경 변수를 추가합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Daemon.html)
1. 이 절차의 1단계에서 정의한 볼륨을 `opentelemetry-auto-instrumentation-node`을 마운트합니다. 지표 및 추적과의 로그 상관 관계를 활성화할 필요가 없는 경우 Node.js 애플리케이션에 대한 다음 예를 사용합니다. 로그 상관 관계를 활성화하려면 다음 단계를 대신 참조하세요.
애플리케이션 컨테이너의 경우 애플리케이션 컨테이너가 시작되기 전에 컨테이너가 완료되도록 `init` 컨테이너에 종속성을 추가합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "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": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/metrics"
},
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://CW_CONTAINER_IP:2000"
},
{
"name": "NODE_OPTIONS",
"value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
1. (선택 사항) 로그 상관 관계를 활성화하려면 볼륨을 마운트하기 전에 다음을 수행하세요. `OTEL_RESOURCE_ATTRIBUTES`에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 `aws.log.group.names`를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP*을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(`&`)를 사용하여 로그 그룹을 구분할 수 있습니다. `aws.log.group.names=log-group-1&log-group-2` 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 [로그 상관 관계에 대한 지표 활성화](Application-Signals-MetricLogCorrelation.md) 섹션을 참조하세요. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 [로그 상관 관계에 대한 추적 활성화](Application-Signals-TraceLogCorrelation.md) 섹션을 참조하세요.
다음은 예입니다. 이 예제를 사용하여 이 절차의 1단계에서 정의한 `opentelemetry-auto-instrumentation` 볼륨을 마운트할 때 로그 상관 관계를 활성화합니다.
```
{
"name": "my-app",
...
"environment": [
{
"name": "OTEL_RESOURCE_ATTRIBUTES",
"value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,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": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/metrics"
},
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://CW_CONTAINER_IP:4316/v1/traces"
},
{
"name": "OTEL_TRACES_SAMPLER",
"value": "xray"
},
{
"name": "OTEL_TRACES_SAMPLER_ARG",
"value": "endpoint=http://CW_CONTAINER_IP:2000"
},
{
"name": "NODE_OPTIONS",
"value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
}
],
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
],
"dependsOn": [
{
"containerName": "init",
"condition": "SUCCESS"
}
]
}
```
**ESM 모듈 형식으로 Node.js 애플리케이션 설정**
ESM 모듈 형식의 Node.js 애플리케이션을 제한적으로 지원합니다. 자세한 내용은 [ESM 사용 Node.js에 대해 알려진 제한 사항](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)을 참조하세요.
ESM 모듈 형식의 경우 `init` 컨테이너를 사용한 Node.js 계측 SDK 주입에는 해당되지 않습니다. ESM을 사용하는 Node.js용 Application Signals를 활성화하려면 이전 절차의 1단계와 2단계를 건너뛰고 대신 다음을 수행합니다.
**ESM을 사용하는 Node.js 애플리케이션에 Application Signals를 활성화하려면**
1. 관련 종속성을 자동 계측용 Node.js 애플리케이션에 설치합니다.
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
npm install @opentelemetry/instrumentation@0.54.0
```
1. 이전 절차의 4단계와 5단계에서 볼륨 `opentelemetry-auto-instrumentation-node`의 탑재를 제거합니다.
```
"mountPoints": [
{
"sourceVolume": "opentelemetry-auto-instrumentation-node",
"containerPath": "/otel-auto-instrumentation-node",
"readOnly": false
}
]
```
노드 옵션을 다음 중 하나로 변경합니다.
```
{
"name": "NODE_OPTIONS",
"value": "--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs"
}
```
------
## 6단계: 애플리케이션 배포
작업 정의의 새 버전을 생성하여 애플리케이션 클러스터에 배포합니다. 새로 생성된 태스크에는 두 개의 컨테이너가 표시되어야 합니다.
+ `init`– Application Signals를 초기화하는 데 필요한 컨테이너입니다.
+ `my-app`- 설명서의 예제 애플리케이션 컨테이너입니다. 실제 워크로드에서는 이 특정 컨테이너가 존재하지 않거나 자체 서비스 컨테이너로 대체될 수 있습니다.
## (선택 사항) 7단계: 애플리케이션 상태 모니터링
Amazon ECS에서 애플리케이션을 활성화하면 애플리케이션 상태를 모니터링할 수 있습니다. 자세한 내용은 [Application Signals를 사용하여 애플리케이션의 운영 상태 모니터링](Services.md) 섹션을 참조하세요.
# AWS CDK를 사용하여 Amazon ECS에서 Application Signals 활성화
AWS CDK를 사용하여 Amazon ECS에서 Application Signals를 활성화하려면 다음을 수행합니다.
1. 애플리케이션에 대해 Application Signals 활성화 - 이 계정에서 아직 Application Signals를 활성화하지 않은 경우 서비스를 검색하는 데 필요한 권한을 Application Signals에 부여해야 합니다.
```
import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';
const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
'ApplicationSignalsServiceRole', { }
);
```
Discovery CloudFormation 리소스는 Application Signals에 다음 권한을 부여합니다.
+ `xray:GetServiceGraph`
+ `logs:StartQuery`
+ `logs:GetQueryResults`
+ `cloudwatch:GetMetricData`
+ `cloudwatch:ListMetrics`
+ `tag:GetResources`
이에 대한 자세한 내용은 [CloudWatch Application Signals에 대한 서비스 연결 역할 권한](using-service-linked-roles.md#service-linked-role-signals) 섹션을 참조하세요.
1. AWS CDK의 [AWS::ApplicationSignals Construct Library](https://www.npmjs.com/package/@aws-cdk/aws-applicationsignals-alpha)로 애플리케이션을 계측합니다. 이 문서의 코드 조각은 *TypeScript*로 제공되었습니다. 다른 언어별 버전은 [AWS CDK에 지원되는 프로그래밍 언어](https://docs.aws.amazon.com/cdk/v2/guide/languages.html)를 참조하세요.
+ **사이드카 모드로 Amazon ECS에서 Application Signals 활성화**
1. `instrumentation`을 구성하여 AWS Distro for OpenTelemetry(ADOT) SDK 에이전트로 애플리케이션을 계측합니다. 다음은 Java 애플리케이션을 계측하는 예제입니다. 지원되는 모든 언어 버전은 [InstrumentationVersion](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-applicationsignals-alpha.InstrumentationVersion.html)을 참조하세요.
1. `cloudWatchAgentSidecar`를 지정하여 CloudWatch 에이전트를 사이드카 컨테이너로 구성합니다.
```
import { Construct } from 'constructs';
import * as appsignals from '@aws-cdk/aws-applicationsignals-alpha';
import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
class MyStack extends cdk.Stack {
public constructor(scope?: Construct, id?: string, props: cdk.StackProps = {}) {
super();
const vpc = new ec2.Vpc(this, 'TestVpc', {});
const cluster = new ecs.Cluster(this, 'TestCluster', { vpc });
const fargateTaskDefinition = new ecs.FargateTaskDefinition(this, 'SampleAppTaskDefinition', {
cpu: 2048,
memoryLimitMiB: 4096,
});
fargateTaskDefinition.addContainer('app', {
image: ecs.ContainerImage.fromRegistry('test/sample-app'),
});
new appsignals.ApplicationSignalsIntegration(this, 'ApplicationSignalsIntegration', {
taskDefinition: fargateTaskDefinition,
instrumentation: {
sdkVersion: appsignals.JavaInstrumentationVersion.V2_10_0,
},
serviceName: 'sample-app',
cloudWatchAgentSidecar: {
containerName: 'ecs-cwagent',
enableLogging: true,
cpu: 256,
memoryLimitMiB: 512,
}
});
new ecs.FargateService(this, 'MySampleApp', {
cluster: cluster,
taskDefinition: fargateTaskDefinition,
desiredCount: 1,
});
}
}
```
+ **대몬 모드로 Amazon ECS에서 Application Signals 활성화**
**참고**
대몬 배포 전략은 Amazon ECS Fargate에서 지원되지 않으며 Amazon EC2의 Amazon ECS에서만 지원됩니다.
1. CloudWatch Agent를 `HOST` 네트워크 모드의 대몬 서비스로 실행합니다.
1. `instrumentation`를 구성하여 ADOT Python 에이전트로 애플리케이션을 계측합니다.
```
import { Construct } from 'constructs';
import * as appsignals from '@aws-cdk/aws-applicationsignals-alpha';
import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
class MyStack extends cdk.Stack {
public constructor(scope?: Construct, id?: string, props: cdk.StackProps = {}) {
super(scope, id, props);
const vpc = new ec2.Vpc(this, 'TestVpc', {});
const cluster = new ecs.Cluster(this, 'TestCluster', { vpc });
// Define Task Definition for CloudWatch agent (Daemon)
const cwAgentTaskDefinition = new ecs.Ec2TaskDefinition(this, 'CloudWatchAgentTaskDefinition', {
networkMode: ecs.NetworkMode.HOST,
});
new appsignals.CloudWatchAgentIntegration(this, 'CloudWatchAgentIntegration', {
taskDefinition: cwAgentTaskDefinition,
containerName: 'ecs-cwagent',
enableLogging: false,
cpu: 128,
memoryLimitMiB: 64,
portMappings: [
{
containerPort: 4316,
hostPort: 4316,
},
{
containerPort: 2000,
hostPort: 2000,
},
],
});
// Create the CloudWatch Agent daemon service
new ecs.Ec2Service(this, 'CloudWatchAgentDaemon', {
cluster,
taskDefinition: cwAgentTaskDefinition,
daemon: true, // Runs one container per EC2 instance
});
// Define Task Definition for user application
const sampleAppTaskDefinition = new ecs.Ec2TaskDefinition(this, 'SampleAppTaskDefinition', {
networkMode: ecs.NetworkMode.HOST,
});
sampleAppTaskDefinition.addContainer('app', {
image: ecs.ContainerImage.fromRegistry('test/sample-app'),
cpu: 0,
memoryLimitMiB: 512,
});
// No CloudWatch Agent sidecar is needed as application container communicates to CloudWatch Agent daemon through host network
new appsignals.ApplicationSignalsIntegration(this, 'ApplicationSignalsIntegration', {
taskDefinition: sampleAppTaskDefinition,
instrumentation: {
sdkVersion: appsignals.PythonInstrumentationVersion.V0_8_0
},
serviceName: 'sample-app'
});
new ecs.Ec2Service(this, 'MySampleApp', {
cluster,
taskDefinition: sampleAppTaskDefinition,
desiredCount: 1,
});
}
}
```
+ **복제본 모드로 Amazon ECS에서 Application Signals 활성화**
**참고**
복제본 모드를 사용하여 CloudWatch Agent 서비스를 실행하려면 다른 서비스와 통신할 수 있는 특정 보안 그룹 구성이 필요합니다. Application Signals 기능의 경우 최소 인바운드 규칙인 포트 2000(HTTP) 및 포트 4316(HTTP)으로 보안 그룹을 구성합니다. 이 구성에서는 CloudWatch 에이전트와 종속 서비스 간의 적절한 연결이 확보됩니다.
1. 서비스 연결을 통해 CloudWatch Agent를 복제본 서비스로 실행합니다.
1. `instrumentation`를 구성하여 ADOT Python 에이전트로 애플리케이션을 계측합니다.
1. Service Connect 연결 엔드포인트를 사용하여 CloudWatch 에이전트 서버와 통신하도록 `overrideEnvironments`를 구성하여 환경 변수를 재정의합니다.
```
import { Construct } from 'constructs';
import * as appsignals from '@aws-cdk/aws-applicationsignals-alpha';
import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import { PrivateDnsNamespace } from 'aws-cdk-lib/aws-servicediscovery';
class MyStack extends cdk.Stack {
public constructor(scope?: Construct, id?: string, props: cdk.StackProps = {}) {
super(scope, id, props);
const vpc = new ec2.Vpc(this, 'TestVpc', {});
const cluster = new ecs.Cluster(this, 'TestCluster', { vpc });
const dnsNamespace = new PrivateDnsNamespace(this, 'Namespace', {
vpc,
name: 'local',
});
const securityGroup = new ec2.SecurityGroup(this, 'ECSSG', { vpc });
securityGroup.addIngressRule(securityGroup, ec2.Port.tcpRange(0, 65535));
// Define Task Definition for CloudWatch agent (Replica)
const cwAgentTaskDefinition = new ecs.FargateTaskDefinition(this, 'CloudWatchAgentTaskDefinition', {});
new appsignals.CloudWatchAgentIntegration(this, 'CloudWatchAgentIntegration', {
taskDefinition: cwAgentTaskDefinition,
containerName: 'ecs-cwagent',
enableLogging: false,
cpu: 128,
memoryLimitMiB: 64,
portMappings: [
{
name: 'cwagent-4316',
containerPort: 4316,
hostPort: 4316,
},
{
name: 'cwagent-2000',
containerPort: 2000,
hostPort: 2000,
},
],
});
// Create the CloudWatch Agent replica service with service connect
new ecs.FargateService(this, 'CloudWatchAgentService', {
cluster: cluster,
taskDefinition: cwAgentTaskDefinition,
securityGroups: [securityGroup],
serviceConnectConfiguration: {
namespace: dnsNamespace.namespaceArn,
services: [
{
portMappingName: 'cwagent-4316',
dnsName: 'cwagent-4316-http',
port: 4316,
},
{
portMappingName: 'cwagent-2000',
dnsName: 'cwagent-2000-http',
port: 2000,
},
],
},
desiredCount: 1,
});
// Define Task Definition for user application
const sampleAppTaskDefinition = new ecs.FargateTaskDefinition(this, 'SampleAppTaskDefinition', {});
sampleAppTaskDefinition.addContainer('app', {
image: ecs.ContainerImage.fromRegistry('test/sample-app'),
cpu: 0,
memoryLimitMiB: 512,
});
// Overwrite environment variables to connect to the CloudWatch Agent service just created
new appsignals.ApplicationSignalsIntegration(this, 'ApplicationSignalsIntegration', {
taskDefinition: sampleAppTaskDefinition,
instrumentation: {
sdkVersion: appsignals.PythonInstrumentationVersion.V0_8_0,
},
serviceName: 'sample-app',
overrideEnvironments: [
{
name: appsignals.CommonExporting.OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT,
value: 'http://cwagent-4316-http:4316/v1/metrics',
},
{
name: appsignals.TraceExporting.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
value: 'http://cwagent-4316-http:4316/v1/traces',
},
{
name: appsignals.TraceExporting.OTEL_TRACES_SAMPLER_ARG,
value: 'endpoint=http://cwagent-2000-http:2000',
},
],
});
// Create ECS Service with service connect configuration
new ecs.FargateService(this, 'MySampleApp', {
cluster: cluster,
taskDefinition: sampleAppTaskDefinition,
serviceConnectConfiguration: {
namespace: dnsNamespace.namespaceArn,
},
desiredCount: 1,
});
}
}
```
1. ESM 모듈 형식으로 Node.js 애플리케이션을 설정합니다. ESM 모듈 형식의 Node.js 애플리케이션은 제한적으로 지원됩니다. 자세한 내용은 [ESM 사용 Node.js에 대해 알려진 제한 사항](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-supportmatrix.html#ESM-limitations)을 참조하세요.
ESM 모듈 형식의 경우 `init` 컨테이너를 사용한 Application Signals 활성화를 통한 Node.js 계측 SDK 주입에는 해당되지 않습니다. 이 절차의 2단계를 건너뛰고 다음을 대신 수행합니다.
+ 관련 종속성을 자동 계측용 Node.js 애플리케이션에 설치합니다.
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
npm install @opentelemetry/instrumentation@0.54.
```
+ TaskDefinition을 업데이트합니다.
1. 애플리케이션 컨테이너에 추가 구성을 추가합니다.
1. `NODE_OPTIONS`를 구성합니다.
1. (선택 사항) 사이드카 모드를 선택한 경우 CloudWatch 에이전트를 추가합니다.
```
import { Construct } from 'constructs';
import * as appsignals from '@aws-cdk/aws-applicationsignals-alpha';
import * as ecs from 'aws-cdk-lib/aws-ecs';
class MyStack extends cdk.Stack {
public constructor(scope?: Construct, id?: string, props: cdk.StackProps = {}) {
super(scope, id, props);
const fargateTaskDefinition = new ecs.FargateTaskDefinition(stack, 'TestTaskDefinition', {
cpu: 256,
memoryLimitMiB: 512,
});
const appContainer = fargateTaskDefinition.addContainer('app', {
image: ecs.ContainerImage.fromRegistry('docker/cdk-test'),
});
const volumeName = 'opentelemetry-auto-instrumentation'
fargateTaskDefinition.addVolume({name: volumeName});
// Inject additional configurations
const injector = new appsignals.NodeInjector(volumeName, appsignals.NodeInstrumentationVersion.V0_5_0);
injector.renderDefaultContainer(fargateTaskDefinition);
// Configure NODE_OPTIONS
appContainer.addEnvironment('NODE_OPTIONS', '--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs')
// Optional: add CloudWatch agent
const cwAgent = new appsignals.CloudWatchAgentIntegration(stack, 'AddCloudWatchAgent', {
containerName: 'ecs-cwagent',
taskDefinition: fargateTaskDefinition,
memoryReservationMiB: 50,
});
appContainer.addContainerDependencies({
container: cwAgent.agentContainer,
condition: ecs.ContainerDependencyCondition.START,
});
}
```
1. 업데이트된 스택 배포 - 애플리케이션의 기본 디렉터리에서 `cdk synth` 명령을 실행합니다. AWS 계정에 서비스를 배포하려면 애플리케이션의 기본 디렉터리에서 `cdk deploy` 명령을 실행합니다.
사이드카 전략을 사용한 경우 한 가지 서비스가 생성됩니다.
+ *APPLICATION\$1SERVICE*는 애플리케이션의 서비스입니다. 여기에는 다음 세 가지의 구성 옵션이 포함됩니다.
+ `init`– Application Signals를 초기화하는 데 필요한 컨테이너입니다.
+ `ecs-cwagent`– CloudWatch 에이전트를 실행하는 컨테이너입니다.
+ `my-app`- 설명서의 예제 애플리케이션 컨테이너입니다. 실제 워크로드에서는 이 특정 컨테이너가 존재하지 않거나 자체 서비스 컨테이너로 대체될 수 있습니다.
대몬 전략을 사용한 경우 두 가지 서비스가 생성됩니다.
+ *CloudWatchAgentDaemon*은 CloudWatch 에이전트 대몬 서비스입니다.
+ *APPLICATION\$1SERVICE*는 애플리케이션의 서비스입니다. 여기에는 다음 두 가지의 구성 옵션이 포함됩니다.
+ `init`– Application Signals를 초기화하는 데 필요한 컨테이너입니다.
+ `my-app`- 설명서의 예제 애플리케이션 컨테이너입니다. 실제 워크로드에서는 이 특정 컨테이너가 존재하지 않거나 자체 서비스 컨테이너로 대체될 수 있습니다.
복제본 전략을 사용한 경우 두 가지 서비스가 생성됩니다.
+ *CloudWatchAgentService*는 CloudWatch 에이전트 복제본 서비스입니다.
+ *APPLICATION\$1SERVICE*는 애플리케이션의 서비스입니다. 여기에는 다음 두 가지의 구성 옵션이 포함됩니다.
+ `init`– Application Signals를 초기화하는 데 필요한 컨테이너입니다.
+ `my-app`- 설명서의 예제 애플리케이션 컨테이너입니다. 실제 워크로드에서는 이 특정 컨테이너가 존재하지 않거나 자체 서비스 컨테이너로 대체될 수 있습니다.
## Model Context Protocol(MCP)을 사용하여 Amazon ECS에서 Application Signals 활성화
CloudWatch Application Signals Model Context Protocol(MCP) 서버를 사용하면 대화형 AI 상호 작용을 통해 Amazon ECS 클러스터에서 Application Signals를 활성화할 수 있습니다. 이렇게 하면 Application Signals 모니터링을 설정하기 위한 자연어 인터페이스가 제공됩니다.
MCP 서버는 사용자의 요구 사항을 파악하고 적합한 구성을 생성하여 활성화 프로세스를 자동화합니다. 사용자는 수동으로 콘솔 단계를 따르거나 CDK 코드를 작성하는 대신, 활성화하려는 항목을 설명하기만 하면 됩니다.
### 사전 조건
MCP 서버를 사용하여 Application Signals를 활성화하기 전에 다음 요소를 갖추고 있는지 확인합니다.
+ MCP를 지원하는 개발 환경(예: Kiro, Claude Desktop, MCP 확장이 포함된 VSCode 또는 기타 MCP 호환 도구)
+ IDE에 구성된 CloudWatch Application Signals MCP 서버. 자세한 설정 지침은 [CloudWatch Application Signals MCP 서버 설명서](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)를 참조하세요.
### MCP 서버 사용
IDE에서 CloudWatch Application Signals MCP 서버를 구성하면 자연어 프롬프트를 사용하여 활성화 지침을 요청할 수 있습니다. 코딩 어시스턴트가 프로젝트 구조에서 컨텍스트를 추론할 수 있긴 하지만, 프롬프트에 구체적인 세부 정보를 제공하면 더 정확하고 연관성 높은 가이드를 받을 수 있습니다. 애플리케이션 언어, Amazon ECS 클러스터 이름, 배포 전략(사이드카 또는 대몬), 인프라 및 애플리케이션 코드의 절대 경로 등과 같은 정보를 포함하세요.
**모범 사례 프롬프트(구체적이고 완전함):**
```
"Enable Application Signals for my Python service running on ECS.
My app code is in /home/user/flask-api and IaC is in /home/user/flask-api/terraform"
"I want to add observability to my Node.js application on ECS cluster 'production-cluster' using sidecar deployment.
The application code is at /Users/dev/checkout-service and
the task definitions are at /Users/dev/checkout-service/ecs"
"Help me instrument my Java Spring Boot application on ECS with Application Signals using daemon strategy.
Application directory: /opt/apps/payment-api
CDK infrastructure: /opt/apps/payment-api/cdk"
```
**효과가 떨어지는 프롬프트:**
```
"Enable monitoring for my app"
→ Missing: platform, language, paths
"Enable Application Signals. My code is in ./src and IaC is in ./infrastructure"
→ Problem: Relative paths instead of absolute paths
"Enable Application Signals for my ECS service at /home/user/myapp"
→ Missing: programming language, deployment strategy
```
**빠른 템플릿:**
```
"Enable Application Signals for my [LANGUAGE] service on ECS.
Deployment strategy: [sidecar/daemon]
App code: [ABSOLUTE_PATH_TO_APP]
IaC code: [ABSOLUTE_PATH_TO_IAC]"
```
### MCP 서버 사용의 이점
CloudWatch Application Signals MCP 서버를 사용하면 다음과 같은 몇 가지 장점이 제공됩니다.
+ **자연어 인터페이스:** 명령이나 구성 구문을 외우지 않고도 활성화하려는 내용을 설명할 수 있습니다.
+ **컨텍스트를 인식하는 가이드:** MCP 서버는 사용자의 특정 환경을 이해하고 맞춤형 권장 사항을 제공합니다.
+ **오류 감소:** 자동화된 구성 생성으로 수동 입력 오류를 최소화합니다.
+ **더 빠른 설정:** 의도한 개념에서 구현까지 더 빠르게 실현합니다.
+ **학습 도구:** 생성된 구성을 확인하고 Application Signals의 작동 방식을 이해합니다.
### 추가 리소스
CloudWatch Application Signals MCP 서버 구성 및 사용에 대한 자세한 내용은 [MCP 서버 설명서](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)를 참조하세요.