Amazon EC2에서 Application Signals 활성화 - Amazon CloudWatch
1단계: 계정에서 Application Signals 활성화2단계: CloudWatch 에이전트 다운로드 및 시작3단계: 애플리케이션 계측 후 시작

Amazon EC2에서 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 설치 또는 업데이트를 참조하세요.

중요

Application Signals에 대해 활성화하려는 애플리케이션과 함께 이미 OpenTelemetry를 사용하고 있다면 Application Signals를 활성화하기 전에 OpenTelemetry 호환성 고려 사항 섹션을 참조하세요.

1단계: 계정에서 Application Signals 활성화

이 계정에서 아직 Application Signals를 활성화하지 않은 경우 서비스를 검색하는 데 필요한 권한을 Application Signals에 부여해야 합니다. 그렇게 하려면 다음을 수행합니다. 계정에 대해 한 번만 수행하면 됩니다.

애플리케이션에 대해 Application Signals 활성화

  1. https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.

  2. 탐색 창에서 서비스를 선택합니다.

  3. 서비스 검색 시작을 선택합니다.

  4. 확인란을 선택하고 서비스 검색 시작을 선택합니다.

    계정에서 처음으로 이 단계를 완료하면 Application Signals가 AWSServiceRoleForCloudWatchApplicationSignals 서비스 연결 역할을 생성합니다. 이 역할은 Application Signals에 다음 권한을 부여합니다.

    • xray:GetServiceGraph

    • logs:StartQuery

    • logs:GetQueryResults

    • cloudwatch:GetMetricData

    • cloudwatch:ListMetrics

    • tag:GetResources

    이에 대한 자세한 내용은 CloudWatch Application Signals에 대한 서비스 연결 역할 권한 섹션을 참조하세요.

2단계: CloudWatch 에이전트 다운로드 및 시작

Amazon EC2 인스턴스 또는 온프레미스 호스트에서 Application Signals 활성화의 일환으로 CloudWatch 에이전트를 설치하려면 다음을 수행하세요.

  1. 최신 버전의 CloudWatch 에이전트를 인스턴스에 다운로드합니다. 인스턴스에 CloudWatch 에이전트가 이미 설치되어 있는 경우 업데이트해야 할 수 있습니다. 2023년 11월 30일 이후에 릴리스된 에이전트 버전만 CloudWatch Application Signals를 지원합니다.

    CloudWatch 에이전트 다운로드에 대한 자세한 내용은 CloudWatch 에이전트 패키지 다운로드 섹션을 참조하세요.

  2. 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": {}
    }
  }
}

  3. Amazon EC2 인스턴스의 IAM 역할에 CloudWatchAgentServerPolicy IAM 정책을 연결합니다. 온프레미스 호스트에 대한 권한은 온프레미스 서버에 대한 권한 섹션을 참조하세요.

    1. AWS Management Console에 로그인하여 https://console.aws.amazon.com/iam/ 에서 IAM 콘솔을 엽니다.

    2. 역할을 선택하고 Amazon EC2 인스턴스에서 사용하는 역할을 찾습니다. 그런 다음, 해당 역할의 이름을 선택합니다.

    3. 권한 탭에서 권한 추가, 정책 연결을 선택합니다.

    4. CloudWatchAgentServerPolicy를 찾습니다. 필요한 경우 검색 상자를 사용합니다. 그런 다음 해당 정책의 확인란을 선택하고 권한 추가를 선택합니다.

  4. 다음 명령을 입력하여 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. https://console.aws.amazon.com/iam/에서 IAM 콘솔을 엽니다.

    2. 사용자, 사용자 생성을 선택합니다.

    3. 사용자 세부 정보의 사용자 이름에 새 IAM 사용자의 이름을 입력합니다. 이는 호스트를 인증하는 데 사용되는 AWS의 로그인 이름입니다. 그런 다음 [Next]를 선택합니다

    4. 권한 설정 페이지의 권한 옵션 아래에서 정책 직접 연결을 선택합니다.

    5. 권한 정책 목록에서 사용자에게 추가할 CloudWatchAgentServerPolicy 정책을 선택합니다. 다음을 선택합니다.

    6. 검토 및 생성 페이지에서 사용자 이름이 만족스러운지, CloudWatchAgentServerPolicy 정책이 권한 요약에 있는지 확인합니다.

    7. 사용자 생성을 선택합니다.

  2. AWS 액세스 키와 비밀 키를 생성하고 검색합니다.

    1. IAM 콘솔의 탐색 창에서 사용자를 선택한 다음 이전 단계에서 생성한 사용자의 이름을 선택합니다.

    2. 사용자의 페이지에서 보안 자격 증명 탭을 선택합니다. 액세스 키 섹션에서 액세스 키 생성을 선택합니다.

    3. 액세스 키 생성 1단계에서 명령줄 인터페이스(CLI)를 선택합니다.

    4. 액세스 키 만들기 2단계에서 필요에 따라 태그를 입력하고 다음을 선택합니다.

    5. 액세스 키 생성 3단계에서 .csv 파일 다운로드를 선택하여 IAM 사용자의 액세스 키 및 비밀 액세스 키와 함께 .csv 파일을 저장합니다. 다음 단계에 이 정보가 필요합니다.

    6. 완료를 선택합니다.

  3. 다음 명령을 입력하여 온프레미스 호스트에서 AWS 자격 증명을 구성합니다. ACCESS_KEY_ID와 SECRET_ACCESS_ID를 이전 단계에서 다운로드한 .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 자동 계측 에이전트를 다운로드합니다. 이 링크를 사용하여 최신 버전을 다운로드할 수 있습니다. aws-otel-java-instrumentation 릴리스에서 모든 릴리스 버전에 대한 정보를 볼 수 있습니다.

  2. 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 지표가 생성됩니다.

  3. 이전 단계에 나열된 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

    참고

    다음 구성은 Java용 AWS Distro for OpenTelemetry 자동 계측 에이전트 버전 1.32.2 이상만 지원합니다.

    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="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar

  4. (선택 사항) 로그 상관 관계를 활성화하려면 OTEL_RESOURCE_ATTRIBUTES에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 aws.log.group.names를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 $YOUR_APPLICATION_LOG_GROUP을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(&)를 사용하여 로그 그룹을 구분할 수 있습니다. aws.log.group.names=log-group-1&log-group-2 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 로그 상관 관계에 대한 지표 활성화 단원을 참조하십시오. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 로그 상관 관계에 대한 추적 활성화 단원을 참조하십시오.

    다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.

    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 데이터 없음 섹션을 참조하여 Application Signals 작동 정보를 확인하세요.

Amazon EC2 인스턴스에서 Application Signals 활성화의 일환으로 Python 애플리케이션 계측

  1. 최신 버전의 AWS Distro for OpenTelemetry Python 자동 계측 에이전트를 다운로드합니다. 다음 명령을 실행하여 인증서를 설치합니다.

    pip install aws-opentelemetry-distro

    AWS Distro for OpenTelemetry Python 계측에서 모든 릴리스된 버전의 정보를 볼 수 있습니다.

  2. 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 지표 측정기준으로 변환됩니다.

    2. OTEL_EXPORTER_OTLP_PROTOCOL 변수의 경우 http/protobuf를 지정하여 HTTP를 통해 다음 단계에 나열된 CloudWatch 에이전트 엔드포인트로 원격 분석 데이터를 내보냅니다.

    3. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 변수에 대해 트레이스를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces로 설정해야 합니다.

    4. 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로 설정해야 합니다.

    5. OTEL_METRICS_EXPORTER 변수에 대해 값을 none으로 설정하는 것이 좋습니다. 이렇게 하면 다른 지표 내보내기가 비활성화되어 Application Signals 내보내기만 사용됩니다.

    6. 컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 OTEL_AWS_APPLICATION_SIGNALS_ENABLED 변수를 true로 설정합니다.

  3. 이전 단계에서 설명한 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

    • $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를 참조하세요.

    • Django 애플리케이션의 경우 추가 필수 구성이 있으며, OpenTelemetry Python 설명서에서 설명합니다.

      • --noreload 플래그를 사용하여 자동 재로드를 방지합니다.

      • DJANGO_SETTINGS_MODULE 환경 변수를 Django 애플리케이션 settings.py 파일의 위치로 설정합니다. 이렇게 하면 OpenTelemetry가 올바르게 액세스하여 Django 설정에 통합할 수 있습니다.

  4. (선택 사항) 로그 상관 관계를 활성화하려면 OTEL_RESOURCE_ATTRIBUTES에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 aws.log.group.names를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 $YOUR_APPLICATION_LOG_GROUP을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(&)를 사용하여 로그 그룹을 구분할 수 있습니다. aws.log.group.names=log-group-1&log-group-2 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 로그 상관 관계에 대한 지표 활성화 단원을 참조하십시오. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 로그 상관 관계에 대한 추적 활성화 단원을 참조하십시오.

    다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.

    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 릴리스에서 최신 버전을 다운로드할 수 있습니다.

  2. Application Signals을 활성화하려면 애플리케이션을 시작하기 전에 다음과 같은 환경 변수를 설정하여 추가 정보를 제공합니다. .NET 애플리케이션을 시작하기 전에.NET 계측용 시작 후크를 설정하는 데 이러한 변수가 필요합니다.

    • 다음은 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=aws-otel-integ-test
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=aws-otel-integ-test"
$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"

  3. 이전 단계에 나열된 환경 변수를 사용하여 애플리케이션을 시작합니다.

    (선택 사항) 또는 제공된 설치 스크립트를 사용하여 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"

    공식 NuGet 리포지토리에서 AWS Distro for OpenTelemetry .NET 자동 계측 패키지의 NuGet 패키지를 찾을 수 있습니다. README 파일에서 지침을 확인해야 합니다.

Node.js (Preview)
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 계측에서 모든 릴리스된 버전의 정보를 볼 수 있습니다.

  2. 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 지표 측정기준으로 변환됩니다.

    2. OTEL_EXPORTER_OTLP_PROTOCOL 변수의 경우 http/protobuf를 지정하여 HTTP를 통해 다음 단계에 나열된 CloudWatch 에이전트 엔드포인트로 원격 분석 데이터를 내보냅니다.

    3. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 변수에 대해 트레이스를 내보낼 기본 엔드포인트 URL을 지정합니다. CloudWatch 에이전트는 4316을 HTTP를 통한 OTLP 포트로 노출합니다. Amazon EC2에서는 애플리케이션이 로컬 CloudWatch 에이전트와 통신하기 때문에 이 값을 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces로 설정해야 합니다.

    4. 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로 설정해야 합니다.

    5. OTEL_METRICS_EXPORTER 변수에 대해 값을 none으로 설정하는 것이 좋습니다. 이렇게 하면 다른 지표 내보내기가 비활성화되어 Application Signals 내보내기만 사용됩니다.

    6. 컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 OTEL_AWS_APPLICATION_SIGNALS_ENABLED 변수를 true로 설정합니다.

  3. 이전 단계에서 설명한 환경 변수를 사용하여 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

    • $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

  4. (선택 사항) 로그 상관 관계를 활성화하려면 OTEL_RESOURCE_ATTRIBUTES에서 애플리케이션의 로그 그룹에 대한 추가 환경 변수 aws.log.group.names를 설정합니다. 이렇게 하면 애플리케이션의 추적과 지표를 로그 그룹의 관련 로그 항목과 상관시킬 수 있습니다. 이 변수의 경우 $YOUR_APPLICATION_LOG_GROUP을 애플리케이션의 로그 그룹 이름으로 바꿉니다. 로그 그룹이 여러 개 있는 경우 다음 예와 같이 앰퍼샌드(&)를 사용하여 로그 그룹을 구분할 수 있습니다. aws.log.group.names=log-group-1&log-group-2 지표와 로그의 상관 관계를 활성화하려면 이 현재 환경 변수를 설정하는 것으로 충분합니다. 자세한 내용은 로그 상관 관계에 대한 지표 활성화 단원을 참조하십시오. 추적과 로그의 상관 관계를 활성화하려면 애플리케이션의 로깅 구성도 변경해야 합니다. 자세한 내용은 로그 상관 관계에 대한 추적 활성화 단원을 참조하십시오.

    다음은 로그 상관 관계를 활성화하는 데 도움이 되는 시작 스크립트의 예입니다.

    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