# Amazon EC2에서 애플리케이션 활성화
이 섹션에 설명된 사용자 지정 설정 단계를 사용하여 Amazon EC2에서 CloudWatch Application Signals를 활성화합니다.
Amazon EC2에서 실행되는 애플리케이션의 경우 CloudWatch 에이전트와 AWS Distro for OpenTelemetry를 직접 설치하고 구성합니다. 사용자 지정 Application Signals 설정으로 활성화된 이러한 아키텍처에서는 Application Signals가 서비스 이름이나 서비스가 실행되는 호스트 또는 클러스터를 자동으로 검색하지 않습니다. 사용자 지정 설정 중에 이러한 이름을 지정해야 하며, 지정하는 이름은 Application Signals 대시보드에 표시됩니다.
이 섹션의 지침은 Java, Python 및 .NET 애플리케이션에 적용됩니다. 단계는 Amazon EC2 인스턴스에서 테스트되었지만 AWS Distro for OpenTelemetry를 지원하는 다른 아키텍처에서도 작동할 것으로 예상됩니다.
**요구 사항**
+ Application Signals에 대한 지원을 받으려면 CloudWatch 에이전트와 AWS Distro for OpenTelemetry 에이전트 모두 최신 버전을 사용해야 합니다.
+ 인스턴스에 AWS CLI가 설치되어 있어야 합니다. AWS CLI 버전 2를 권장하지만 버전 1도 사용할 수 있습니다. AWS CLI 설치에 대한 자세한 내용은 [최신 버전의 AWS CLI 설치 또는 업데이트](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)를 참조하세요.
**중요**
Application Signals에 대해 활성화하려는 애플리케이션과 함께 이미 OpenTelemetry를 사용하고 있다면 Application Signals를 활성화하기 전에 [지원되는 시스템](CloudWatch-Application-Signals-supportmatrix.md) 섹션을 참조하세요.
## 1단계: 계정에서 Application Signals 활성화
먼저 계정에서 Application Signals를 활성화해야 합니다. 그렇지 않은 경우 [계정에서 Application Signals 활성화](CloudWatch-Application-Signals-Enable.md) 섹션을 참조하세요.
## 2단계: CloudWatch 에이전트 다운로드 및 시작
**Amazon EC2 인스턴스 또는 온프레미스 호스트에서 Application Signals 활성화의 일환으로 CloudWatch 에이전트를 설치하려면 다음을 수행하세요.**
1. 최신 버전의 CloudWatch 에이전트를 인스턴스에 다운로드합니다. 인스턴스에 CloudWatch 에이전트가 이미 설치되어 있는 경우 업데이트해야 할 수 있습니다. 2023년 11월 30일 이후에 릴리스된 에이전트 버전만 CloudWatch Application Signals를 지원합니다.
1. CloudWatch 에이전트를 시작하기 전에 Application Signals를 활성화하도록 구성합니다. 다음 예제는 EC2 호스트의 지표와 트레이스 모두에 대해 Application Signals를 활성화하는 CloudWatch 에이전트 구성입니다.
Linux 시스템에서는 이 파일을 `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json`에 배치하는 것이 좋습니다.
```
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
```
1. Amazon EC2 인스턴스의 IAM 역할에 **CloudWatchAgentServerPolicy** IAM 정책을 연결합니다. 온프레미스 호스트에 대한 권한은 [온프레미스 서버에 대한 권한](#Enable-OnPremise-Permissions) 섹션을 참조하세요.
1. AWS Management Console에 로그인하여 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)에서 IAM 콘솔을 엽니다.
1. **역할**을 선택하고 Amazon EC2 인스턴스에서 사용하는 역할을 찾습니다. 그런 다음, 해당 역할의 이름을 선택합니다.
1. **권한** 탭에서 **권한 추가**, **정책 연결**을 선택합니다.
1. **CloudWatchAgentServerPolicy**를 찾습니다. 필요한 경우 검색 상자를 사용합니다. 그런 다음 해당 정책의 확인란을 선택하고 **권한 추가**를 선택합니다.
1. 다음 명령을 입력하여 CloudWatch 에이전트를 시작합니다. *agent-config-file-path*를 `./amazon-cloudwatch-agent.json` 등의 CloudWatch 에이전트 구성 파일의 경로로 바꿉니다. 다음과 같이 `file:` 접두사를 포함해야 합니다.
```
export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
```
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 -s -c file:agent-config-file-path
```
### 온프레미스 서버에 대한 권한
온프레미스 호스트의 경우 장치에 AWS 인증을 제공해야 합니다.
**온프레미스 호스트에 대한 권한을 설정하려면 다음을 수행하세요.**
1. 온프레미스 호스트에 권한을 제공하는 데 사용할 IAM 사용자를 생성합니다.
1. IAM 콘솔([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))을 엽니다.
1. **사용자**, **사용자 생성**을 선택합니다.
1. **사용자 세부 정보**의 **사용자 이름**에 새 IAM 사용자의 이름을 입력합니다. 이는 호스트를 인증하는 데 사용되는 AWS의 로그인 이름입니다. 그런 다음 [**Next**]를 선택합니다
1. **권한 설정** 페이지의 **권한 옵션** 아래에서 **정책 직접 연결**을 선택합니다.
1. **권한 정책** 목록에서 사용자에게 추가할 **CloudWatchAgentServerPolicy** 정책을 선택합니다. 그리고 **다음**을 선택합니다.
1. **검토 및 생성** 페이지에서 사용자 이름이 만족스러운지, **CloudWatchAgentServerPolicy** 정책이 **권한 요약**에 있는지 확인합니다.
1. **사용자 생성**을 선택합니다.
1. AWS 액세스 키와 비밀 키를 생성하고 검색합니다.
1. IAM 콘솔의 탐색 창에서 **사용자**를 선택한 다음 이전 단계에서 생성한 사용자의 이름을 선택합니다.
1. 사용자의 페이지에서 **보안 자격 증명** 탭을 선택합니다. **액세스 키** 섹션에서 **액세스 키 생성**을 선택합니다.
1. **액세스 키 생성 1단계**에서 **명령줄 인터페이스(CLI)**를 선택합니다.
1. **액세스 키 만들기 2단계**에서 필요에 따라 태그를 입력하고 **다음**을 선택합니다.
1. **액세스 키 생성 3단계**에서 **.csv 파일 다운로드**를 선택하여 IAM 사용자의 액세스 키 및 비밀 액세스 키와 함께 .csv 파일을 저장합니다. 다음 단계에 이 정보가 필요합니다.
1. **완료**를 선택합니다.
1. 다음 명령을 입력하여 온프레미스 호스트에서 AWS 자격 증명을 구성합니다. *ACCESS\$1KEY\$1ID*와 *SECRET\$1ACCESS\$1ID*를 이전 단계에서 다운로드한 .csv 파일에서 새로 생성된 액세스 키와 비밀 액세스 키로 바꿉니다.
```
$ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
```
## 3단계: 애플리케이션 계측 후 시작
다음 단계는 CloudWatch Application Signals에 대해 애플리케이션을 계측하는 것입니다.
------
#### [ Java ]
**Amazon EC2 인스턴스 또는 온프레미스 호스트에서 Application Signals 활성화의 일환으로 Java 애플리케이션을 계측하려면 다음을 수행하세요.**
1. 최신 버전의 AWS Distro for OpenTelemetry Java 자동 계측 에이전트를 다운로드합니다. [이 링크](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar)를 사용하여 최신 버전을 다운로드할 수 있습니다. [aws-otel-java-instrumentation 릴리스](https://github.com/aws-observability/aws-otel-java-instrumentation/releases)에서 모든 릴리스 버전에 대한 정보를 볼 수 있습니다.
1. Application Signals의 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다. 이 정보는 Application Signals 대시보드에 표시됩니다.
1. `OTEL_RESOURCE_ATTRIBUTES` 변수에 대해 다음 정보를 키-값 페어로 지정합니다.
+ (선택 사항) `service.name`은 서비스 이름을 설정합니다. Application Signals 대시보드에 애플리케이션의 서비스 이름으로 표시됩니다. 이 키에 대한 값을 제공하지 않으면 기본값인 `UnknownService`가 사용됩니다.
+ (선택 사항) `deployment.environment`는 애플리케이션이 실행되는 환경을 설정합니다. 이는 Application Signals 대시보드에서 애플리케이션의 **호스팅 위치** 환경으로 표시됩니다. 이를 지정하지 않으면 다음 기본값 중 하나가 사용됩니다.
+ Auto Scaling 그룹의 일부인 인스턴스인 경우 `ec2:name-of-Auto-Scaling-group`으로 설정됩니다.
+ Auto Scaling 그룹의 일부인 Amazon EC2 인스턴스인 경우 `ec2:default`로 설정됩니다.
+ 온프레미스 호스트인 경우 `generic:default`로 설정됩니다.
이 환경 변수는 Application Signals에서만 사용되며 X-Ray 트레이스 주석 및 CloudWatch 지표 측정기준으로 변환됩니다.
+ `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 변수에 대해 트레이스를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`로 설정해야 합니다.
+ `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 변수에 대해 지표를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`로 설정해야 합니다.
+ `JAVA_TOOL_OPTIONS` 변수에 대해 AWS Distro for OpenTelemetry Java 자동 계측 에이전트가 저장되는 경로를 지정합니다.
```
export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"
```
예제:
```
export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar
```
+ `OTEL_METRICS_EXPORTER` 변수에 대해 값을 `none`으로 설정하는 것이 좋습니다. 이렇게 하면 다른 지표 내보내기가 비활성화되어 Application Signals 내보내기만 사용됩니다.
+ `OTEL_AWS_APPLICATION_SIGNALS_ENABLED`를 `true`으로 설정합니다. 이렇게 하면 트레이스에서 Application Signals 지표가 생성됩니다.
1. 이전 단계에 나열된 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.
**참고**
다음 구성은 Java용 AWS Distro for OpenTelemetry 자동 계측 에이전트 버전 1.32.2 이상만 지원합니다.
```
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
```
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) 섹션을 참조하세요.
다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.
```
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
```
------
#### [ Python ]
**참고**
Python 애플리케이션에 WSGI 서버를 사용하는 경우 이 섹션의 다음 단계 외에도 [WSGI 서버를 사용하는 Python 애플리케이션에 대한 Application Signals 데이터 없음](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) 섹션을 참조하여 Application Signals 작동 정보를 확인하세요.
**Amazon EC2 인스턴스에서 Application Signals 활성화의 일환으로 Python 애플리케이션 계측**
1. 최신 버전의 AWS Distro for OpenTelemetry Python 자동 계측 에이전트를 다운로드합니다. 다음 명령을 실행하여 인증서를 설치합니다.
```
pip install aws-opentelemetry-distro
```
[AWS Distro for OpenTelemetry Python 계측](https://github.com/aws-observability/aws-otel-python-instrumentation/releases)에서 모든 릴리스된 버전의 정보를 볼 수 있습니다.
1. Application Signals의 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다. 이 정보는 Application Signals 대시보드에 표시됩니다.
1. `OTEL_RESOURCE_ATTRIBUTES` 변수에 대해 다음 정보를 키-값 페어로 지정합니다.
+ `service.name`은 서비스 이름을 설정합니다. Application Signals 대시보드에 애플리케이션의 서비스 이름으로 표시됩니다. 이 키에 대한 값을 제공하지 않으면 기본값인 `UnknownService`가 사용됩니다.
+ `deployment.environment`는 애플리케이션이 실행되는 환경을 설정합니다. 이는 Application Signals 대시보드에서 애플리케이션의 **호스팅 위치** 환경으로 표시됩니다. 이를 지정하지 않으면 다음 기본값 중 하나가 사용됩니다.
+ Auto Scaling 그룹의 일부인 인스턴스인 경우 `ec2:name-of-Auto-Scaling-group`으로 설정됩니다.
+ Auto Scaling 그룹의 일부인 Amazon EC2 인스턴스인 경우 `ec2:default`로 설정됩니다.
+ 온프레미스 호스트인 경우 `generic:default`로 설정됩니다.
이 속성 키는 Application Signals에서만 사용되며 X-Ray 트레이스 주석 및 CloudWatch 지표 측정기준으로 변환됩니다.
1. `OTEL_EXPORTER_OTLP_PROTOCOL` 변수의 경우 `http/protobuf`를 지정하여 HTTP를 통해 다음 단계에 나열된 CloudWatch 에이전트 엔드포인트로 원격 분석 데이터를 내보냅니다.
1. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 변수에 대해 트레이스를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`로 설정해야 합니다.
1. `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 변수에 대해 지표를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`로 설정해야 합니다.
1. `OTEL_METRICS_EXPORTER` 변수에 대해 값을 `none`으로 설정하는 것이 좋습니다. 이렇게 하면 다른 지표 내보내기가 비활성화되어 Application Signals 내보내기만 사용됩니다.
1. 컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 변수를 `true`로 설정합니다.
1. 이전 단계에서 설명한 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.
+ `$SVC_NAME`을 애플리케이션 이름으로 바꿉니다. Application Signals 대시보드에 애플리케이션 이름으로 표시됩니다.
+ `$PYTHON_APP`을 애플리케이션 위치와 이름으로 바꿉니다.
```
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
```
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 설정에 통합할 수 있습니다.
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) 섹션을 참조하세요.
다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.
```
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_PYTHON_APP.jar
```
------
#### [ .NET ]
**Amazon EC2 인스턴스 또는 온프레미스 호스트에서 Application Signals 활성화의 일부로 .NET 애플리케이션을 계측하는 방법**
1. AWS Distro for OpenTelemetry .NET 자동 계측 패키지의 최신 버전을 다운로드합니다. [ aws-otel-dotnet-instrumentation 릴리스](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases)에서 최신 버전을 다운로드할 수 있습니다.
1. Application Signals을 활성화하려면 애플리케이션을 시작하기 전에 다음과 같은 환경 변수를 설정하여 추가 정보를 제공합니다. .NET 애플리케이션을 시작하기 전에.NET 계측용 시작 후크를 설정하는 데 이러한 변수가 필요합니다. `OTEL_RESOURCE_ATTRIBUTES` 환경 변수의 `dotnet-service-name`을 선택한 서비스 이름으로 바꿉니다.
+ 다음은 Linux의 예제입니다.
```
export INSTALL_DIR=OpenTelemetryDistribution
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}
export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4316
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://127.0.0.1:4316/v1/metrics
export OTEL_METRICS_EXPORTER=none
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
export OTEL_TRACES_SAMPLER=xray
export OTEL_TRACES_SAMPLER_ARG=http://127.0.0.1:2000
```
+ 다음은 Windows Server용 예제입니다.
```
$env:INSTALL_DIR = "OpenTelemetryDistribution"
$env:CORECLR_ENABLE_PROFILING = 1
$env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
$env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll"
$env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps"
$env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store"
$env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
$env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR
$env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=dotnet-service-name"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4316"
$env:OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT = "http://127.0.0.1:4316/v1/metrics"
$env:OTEL_METRICS_EXPORTER = "none"
$env:OTEL_AWS_APPLICATION_SIGNALS_ENABLED = "true"
$env:OTEL_TRACES_SAMPLER = "xray"
$env:OTEL_TRACES_SAMPLER_ARG = "http://127.0.0.1:2000"
```
1. 이전 단계에 나열된 환경 변수를 사용하여 애플리케이션을 시작합니다.
(선택 사항) 또는 제공된 설치 스크립트를 사용하여 AWS Distro for OpenTelemetry .NET 자동 계측 패키지의 설치 및 설정을 지원할 수 있습니다.
Linux의 경우 GitHub 릴리스 페이지에서 Bash 설치 스크립트를 다운로드하여 설치합니다.
```
# Download and Install
curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
chmod +x ./aws-otel-dotnet-install.sh
./aws-otel-dotnet-install.sh
# Instrument
. $HOME/.otel-dotnet-auto/instrument.sh
export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
```
Windows Server의 경우 GitHub 릴리스 페이지에서 PowerShell 설치 스크립트를 다운로드하여 설치하세요.
```
# Download and Install
$module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
Install-OpenTelemetryCore
# Instrument
Import-Module $download_path
Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
Register-OpenTelemetryForIIS
```
[공식 NuGet 리포지토리](https://www.nuget.org/packages/AWS.Distro.OpenTelemetry.AutoInstrumentation)에서 AWS Distro for OpenTelemetry .NET 자동 계측 패키지의 NuGet 패키지를 찾을 수 있습니다. [README 파일](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/blob/main/src/AWS.Distro.OpenTelemetry.AutoInstrumentation/nuget-readme.md)에서 지침을 확인해야 합니다.
------
#### [ Node.js ]
**참고**
ESM을 사용하는 Node.js 애플리케이션용 Application Signals를 활성화하는 경우 이들 단계를 시작하기 전에 [Setting up a Node.js application with the ESM module format](#EC2-NodeJs-ESM)을(를) 참조합니다.
**Amazon EC2 인스턴스에서 Application Signals 활성화의 일환으로 Node.js 애플리케이션을 계측하려면 다음을 수행하세요.**
1. Node.js용 AWS Distro for OpenTelemetry JavaScript 자동 계측 에이전트의 최신 버전을 다운로드합니다. 다음 명령을 실행하여 인증서를 설치합니다.
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
```
[AWS Distro for OpenTelemetry JavaScript 계측](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)에서 모든 릴리스된 버전의 정보를 볼 수 있습니다.
1. Application Signals의 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다. 이 정보는 Application Signals 대시보드에 표시됩니다.
1. `OTEL_RESOURCE_ATTRIBUTES` 변수에 대해 다음 정보를 키-값 페어로 지정합니다.
+ `service.name`은 서비스 이름을 설정합니다. Application Signals 대시보드에 애플리케이션의 서비스 이름으로 표시됩니다. 이 키에 대한 값을 제공하지 않으면 기본값인 `UnknownService`가 사용됩니다.
+ `deployment.environment`는 애플리케이션이 실행되는 환경을 설정합니다. 이는 Application Signals 대시보드에서 애플리케이션의 **호스팅 위치** 환경으로 표시됩니다. 이를 지정하지 않으면 다음 기본값 중 하나가 사용됩니다.
+ Auto Scaling 그룹의 일부인 인스턴스인 경우 `ec2:name-of-Auto-Scaling-group`으로 설정됩니다.
+ Auto Scaling 그룹의 일부인 Amazon EC2 인스턴스인 경우 `ec2:default`로 설정됩니다.
+ 온프레미스 호스트인 경우 `generic:default`로 설정됩니다.
이 속성 키는 Application Signals에서만 사용되며 X-Ray 트레이스 주석 및 CloudWatch 지표 측정기준으로 변환됩니다.
1. `OTEL_EXPORTER_OTLP_PROTOCOL` 변수의 경우 `http/protobuf`를 지정하여 HTTP를 통해 다음 단계에 나열된 CloudWatch 에이전트 엔드포인트로 원격 분석 데이터를 내보냅니다.
1. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 변수에 대해 트레이스를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`로 설정해야 합니다.
1. `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 변수에 대해 지표를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`로 설정해야 합니다.
1. `OTEL_METRICS_EXPORTER` 변수에 대해 값을 `none`으로 설정하는 것이 좋습니다. 이렇게 하면 다른 지표 내보내기가 비활성화되어 Application Signals 내보내기만 사용됩니다.
1. 컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 변수를 `true`로 설정합니다.
1. 이전 단계에서 설명한 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.
+ `$SVC_NAME`을 애플리케이션 이름으로 바꿉니다. Application Signals 대시보드에 애플리케이션 이름으로 표시됩니다.
```
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
```
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) 섹션을 참조하세요.
다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.
```
export OTEL_METRICS_EXPORTER=none \
export OTEL_LOGS_EXPORTER=none \
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
export OTEL_TRACES_SAMPLER=xray \
export OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:2000 \
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
```
**ESM 모듈 형식으로 Node.js 애플리케이션 설정**
ESM 모듈 형식의 Node.js 애플리케이션을 제한적으로 지원합니다. 자세한 내용은 [ESM 사용 Node.js에 대해 알려진 제한 사항](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)을 참조하세요.
ESM을 사용하는 Node.js 애플리케이션에 Application Signals를 활성화하려면 이전 절차의 단계를 수정해야 합니다.
먼저 Node.js 애플리케이션에 `@opentelemetry/instrumentation`을(를) 설치합니다.
```
npm install @opentelemetry/instrumentation@0.54.0
```
이어서 이전 절차의 3단계와 4단계에서 다음의 노드 옵션을 변경합니다.
```
--require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register'
```
다음의 옵션으로 변경합니다.
```
--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs
```
------
## Model Context Protocol(MCP)을 사용하여 Amazon EC2에서 Application Signals 활성화
CloudWatch Application Signals Model Context Protocol(MCP) 서버를 사용하면 대화형 AI 상호 작용을 통해 Amazon EC2 인스턴스에서 Application Signals를 활성화할 수 있습니다. 이렇게 하면 Application Signals 모니터링을 설정하기 위한 자연어 인터페이스가 제공됩니다.
MCP 서버는 사용자의 요구 사항을 파악하고 적합한 구성을 생성하여 활성화 프로세스를 자동화합니다. 사용자는 설정 단계를 수동으로 따르는 대신, 활성화하려는 항목을 설명하기만 하면 됩니다.
### 사전 조건
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 서버를 구성하면 자연어 프롬프트를 사용하여 활성화 지침을 요청할 수 있습니다. 코딩 어시스턴트가 프로젝트 구조에서 컨텍스트를 추론할 수 있긴 하지만, 프롬프트에 구체적인 세부 정보를 제공하면 더 정확하고 연관성 높은 가이드를 받을 수 있습니다. 애플리케이션 언어, 인스턴스 세부 정보, 인프라 및 애플리케이션 코드의 절대 경로 등과 같은 정보를 포함하세요.
**모범 사례 프롬프트(구체적이고 완전함):**
```
"Enable Application Signals for my Python service running on EC2.
My app code is in /home/ec2-user/flask-api and IaC is in /home/ec2-user/flask-api/terraform"
"I want to add observability to my Java application on EC2.
The application code is at /opt/apps/checkout-service and
the infrastructure code is at /opt/apps/checkout-service/cloudformation"
"Help me instrument my Node.js application on EC2 with Application Signals.
Application directory: /home/ubuntu/payment-api
Terraform code: /home/ubuntu/payment-api/terraform"
```
**효과가 떨어지는 프롬프트:**
```
"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 EC2 service at /home/user/myapp"
→ Missing: programming language
```
**빠른 템플릿:**
```
"Enable Application Signals for my [LANGUAGE] service on EC2.
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)를 참조하세요.
## (선택 사항) 애플리케이션 상태 모니터링
Amazon EC2에서 애플리케이션을 활성화하면 애플리케이션 상태를 모니터링할 수 있습니다. 자세한 내용은 [Application Signals를 사용하여 애플리케이션의 운영 상태 모니터링](Services.md) 섹션을 참조하세요.