전제 조건 Amazon EC2에 대한 IAM 권한 설정 온프레미스 호스트에 대한 IAM 권한 설정 ADOT SDK 활성화

AWS Distro for OpenTelemetry(ADOT) SDK를 사용하여 수집기를 사용하지 않는 트레이스 내보내기

ADOT SDK를 사용하면 수집기를 사용하지 않고 트레이스를 OTLP 엔드포인트(트레이스용)로 바로 보낼 수 있습니다.

참고

기본적으로 트랜잭션 검색을 활성화하면 Application Signals가 활성화됩니다. Application Signals는 AWS Distro for OpenTelemetry에서 지원되지 않으며 비활성화해야 합니다.

전제 조건

X-Ray OTLP 엔드포인트로 스팬을 보내려면 트랜잭션 검색이 활성화되어 있어야 합니다. 자세한 내용은 트랜잭션 검색 시작하기를 참조하세요.

Amazon EC2에 대한 IAM 권한 설정

다음과 같은 단계에 따라 Amazon EC2 인스턴스의 IAM 역할에 AWSXrayWriteOnlyPolicy IAM 정책을 연결합니다.

https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.
역할을 선택하고 Amazon EC2 인스턴스에서 사용하는 역할을 선택합니다.
권한 탭에서 권한 추가와 정책 연결을 차례로 선택합니다.
검색 상자를 사용하여 AWSXrayWriteOnlyPolicy 정책을 검색합니다.
AWSXrayWriteOnlyPolicy 정책을 선택하고 권한 추가를 선택합니다.

온프레미스 호스트에 대한 IAM 권한 설정

온프레미스 호스트에 권한을 제공하는 데 사용할 수 있는 IAM 사용자는 다음과 같은 단계에 따라 생성합니다.

https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.
사용자를 선택한 다음에 사용자 생성을 선택합니다.
사용자, 사용자 생성을 선택합니다.
사용자 세부 정보의 사용자 이름에 새 IAM 사용자의 이름을 입력합니다. 이는 호스트를 인증하는 데 사용되는 AWS의 로그인 이름입니다.
다음을 선택합니다.
권한 설정 페이지의 권한 옵션 아래에서 정책 직접 연결을 선택합니다.
권한 정책 목록에서 사용자에게 추가할 AWSXrayWriteOnlyPolicy 정책을 선택합니다.
다음을 선택합니다.
검토 및 생성 페이지에서 사용자 이름이 만족스럽고 AWSXrayWriteOnlyPolicy 정책이 권한 요약에 있는지 확인합니다.
사용자 생성을 선택합니다.
AWS 액세스 키와 비밀 키를 생성하고 검색합니다.
1. IAM 콘솔의 탐색 창에서 사용자를 선택한 다음 이전 단계에서 생성한 사용자의 이름을 선택합니다.
2. 사용자의 페이지에서 보안 자격 증명 탭을 선택합니다.
3. 액세스 키 섹션에서 액세스 키 생성을 선택합니다.
4. 액세스 키 생성 1단계에서 명령줄 인터페이스(CLI)를 선택합니다.
5. 액세스 키 만들기 2단계에서 필요에 따라 태그를 입력하고 다음을 선택합니다.
6. 액세스 키 생성 3단계에서 .csv 파일 다운로드를 선택하여 IAM 사용자의 액세스 키 및 비밀 액세스 키와 함께 .csv 파일을 저장합니다. 다음 단계에 이 정보가 필요합니다.
7. 완료를 선택합니다.
다음 명령을 입력하여 온프레미스 호스트에서 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
```

ADOT SDK 활성화

애플리케이션이 Java, Node.js, Python 및 .Net의 AWS Distro for OpenTelemetry(ADOT) SDK에서 OTLP 엔드포인트로 바로 보내지도록 트레이스를 활성화할 수 있습니다.

Java

최신 버전의 AWS Distro for OpenTelemetry Java 자동 계측 에이전트를 다운로드합니다. 이 명령을 사용하여 최신 버전을 다운로드할 수 있습니다.
```
curl -L -O https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar
```
릴리스된 모든 버전을 보려면 aws-otel-java-instrumentation 릴리스를 참조하세요.
트레이스를 X-Ray OTLP 트레이스 엔드포인트로 바로 보내는 내보내기 도구를 활성화하고 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다.
OTEL_RESOURCE_ATTRIBUTES 변수에 대해 다음 정보를 키-값 페어로 지정합니다.

(선택 사항) service.name은 서비스 이름을 설정합니다. Application Signals 대시보드에 애플리케이션의 서비스 이름으로 표시됩니다. 이 키에 대한 값을 제공하지 않으면 기본값인 UnknownService가 사용됩니다.

(선택 사항) deployment.environment는 애플리케이션이 실행되는 환경을 설정합니다. 이는 애플리케이션의 호스팅 위치 환경으로 표시됩니다. 이를 지정하지 않으면 다음 기본값 중 하나가 사용됩니다.
- 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 변수의 경우 X-Ray OTLP 트레이스 엔드포인트 https://xray.[AWSRegion].amazonaws.com/v1/traces를 지정합니다. 예시:
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```

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 변수의 경우 값을 없음으로 설정하는 것이 좋습니다.
OTEL_LOGS_EXPORTER 변수의 경우 값을 없음으로 설정하는 것이 좋습니다.
OTEL_TRACES_EXPORTER 변수의 경우 otlp의 값을 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임).
OTEL_EXPORTER_OTLP_PROTOCOL 변수의 경우 값을 http/protobuf 로 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임). X-Ray OTLP 엔드포인트에서는 현재 HTTP 프로토콜만 지원됩니다.
이제 애플리케이션이 AWS Distro for OpenTelemetry Java 계측으로 실행되고 있어야 하며 스팬이 생성될 것입니다. 이러한 스팬은 계정의 aws/spans CloudWatch LogsLogGroup에 저장됩니다. CloudWatch 트레이스 및 지표 콘솔에서 스팬과 상관관계가 있는 트레이스와 지표를 볼 수도 있습니다.

설정한 환경 변수로 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

(참고: 다음 구성에서는 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_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar

Node.js

Node.js용 AWS Distro for OpenTelemetry JavaScript 자동 계측 에이전트의 최신 버전을 다운로드합니다. 명령을 사용하여 설치할 수 있습니다.
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
```
릴리스된 모든 버전의 정보를 보려면 AWS Distro for OpenTelemetry JavaScript 계측을 참조하세요.
트레이스를 X-Ray OTLP 엔드포인트로 바로 보내는 내보내기 도구를 활성화하고 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다.
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 변수의 경우 X-Ray OTLP 트레이스 엔드포인트 https://xray.[AWSRegion].amazonaws.com/v1/traces를 지정합니다.

예시:
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```
OTEL_METRICS_EXPORTER 변수의 경우 값을 없음으로 설정하는 것이 좋습니다. Application Signals 지표는 OTLP 엔드포인트에서 생성됩니다.
OTEL_LOGS_EXPORTER 변수의 경우 값을 없음으로 설정하는 것이 좋습니다.
OTEL_TRACES_EXPORTER 변수의 경우 otlp의 값을 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임).
OTEL_EXPORTER_OTLP_PROTOCOL 변수의 경우 값을 http/protobuf 로 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임). X-Ray OTLP 엔드포인트에서는 현재 HTTP 프로토콜만 지원됩니다.
이제 애플리케이션이 AWS Distro for OpenTelemetry Java 계측으로 실행되고 있어야 하며 스팬이 생성될 것입니다. 이러한 스팬은 계정의 aws/spans CloudWatch LogsLogGroup에 저장됩니다. CloudWatch 트레이스 및 지표 콘솔에서 스팬과 상관관계가 있는 트레이스와 지표를 볼 수도 있습니다.

설정한 환경 변수로 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

(참고: $SVC_NAME을 애플리케이션 이름으로 바꿉니다. 이것이 애플리케이션의 이름으로 표시됩니다.


OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node —require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js

Python

최신 버전의 AWS Distro for OpenTelemetry Python 자동 계측 에이전트를 다운로드합니다. 명령을 사용하여 설치할 수 있습니다.
```
pip install aws-opentelemetry-distro
```
트레이스를 X-Ray OTLP 엔드포인트로 바로 보내는 내보내기 도구를 활성화하고 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 사용하여 추가 정보를 제공합니다.
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 변수의 경우 X-Ray OTLP 트레이스 엔드포인트 https://xray.[AWSRegion].amazonaws.com/v1/traces를 지정합니다.

예시:
```
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"
```
OTEL_METRICS_EXPORTER 변수의 경우 값을 없음으로 설정하는 것이 좋습니다. Application Signals 지표는 OTLP 엔드포인트에서 생성됩니다.
OTEL_LOGS_EXPORTER 변수의 경우 값을 없음으로 설정하는 것이 좋습니다.
OTEL_TRACES_EXPORTER 변수의 경우 otlp의 값을 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임).
OTEL_EXPORTER_OTLP_PROTOCOL 변수의 경우 값을 http/protobuf 로 설정해야 합니다(이 값은 선택 사항이며 이 환경 변수가 설정되지 않은 경우 기본값임). X-Ray OTLP 엔드포인트에서는 현재 HTTP 프로토콜만 지원됩니다.
이제 애플리케이션이 AWS Distro for OpenTelemetry Java 계측으로 실행되고 있어야 하며 스팬이 생성될 것입니다. 이러한 스팬은 계정의 aws/spans CloudWatch LogsLogGroup에 저장됩니다. CloudWatch 트레이스 및 지표 콘솔에서 스팬과 상관관계가 있는 트레이스와 지표를 볼 수도 있습니다.

설정한 환경 변수로 애플리케이션을 시작합니다. 다음은 시작 스크립트의 예입니다.

(참고: $SVC_NAME을 애플리케이션 이름으로 바꾸고 $PYTHON_APP를 애플리케이션의 위치 및 이름으로 바꿉니다.


OTEL_METRICS_EXPORTER=none \ 
OTEL_LOGS_EXPORTER=none \ 
OTEL_PYTHON_DISTRO=aws_distro \
 OTEL_PYTHON_CONFIGURATOR=aws_configurator \ 
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py

.Net

트레이스를 X-Ray OTLP 트레이스 엔드포인트로 바로 보내는 내보내기 도구를 활성화하고 이점을 최적화하려면 애플리케이션을 시작하기 전에 환경 변수를 설정하여 추가 정보를 제공합니다. 이러한 변수는 .NET 계측 설정에도 필요합니다.

OTEL_RESOURCE_ATTRIBUTES 환경 변수의 dotnet-service-name을 선택한 서비스 이름으로 바꿉니다.
OTEL_TRACES_EXPORTER=none을 설정합니다.

OTEL_AWS_SIG_V4_ENABLED=true을 설정합니다.

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_TRACES_EXPORTER=none
export OTEL_AWS_SIG_V4_ENABLED=true

export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

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_TRACES_EXPORTER=none
$env:OTEL_AWS_SIG_V4_ENABLED=true

$env:OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
$env:OTEL_METRICS_EXPORTER=none
$env:OTEL_LOGS_EXPORTER=none
$env:OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

환경 변수로 애플리케이션을 시작합니다.

(선택 사항) 또는 제공된 설치 스크립트를 사용하여 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.shexport 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 리포지토리에서 AWS Distro for OpenTelemetry .NET 자동 계측 패키지의 NuGet 패키지를 찾을 수 있습니다. README 파일에서 지침을 확인합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

사용자 지정 OpenTelemetry Collector 구축

문제 해결