서비스 맵에서 누락된 X-Ray 추적, 세그먼트 또는 서비스를 해결하려면 어떻게 해야 하나요?

간략한 설명

추적 누락으로 인해 서비스 맵에서 서비스가 누락됩니다. 추적 누락으로 이어지는 원인은 다음과 같습니다.

• 잘못된 계측
• X-Ray SDK가 대몬(daemon) 주소 또는 포트 번호를 통해 X-Ray 대몬(daemon)에 도달할 수 없습니다.
• X-Ray 대몬(daemon)이 X-Ray 서비스 엔드포인트에 도달할 수 없습니다.
• 추적이 개별 서비스 수준에서 구성되지 않았습니다.
• AWS Identity and Access Management(IAM) 권한 누락
• 샘플링 규칙 구성
• OpenTelemetry Collector에 구성 누락

하위 세그먼트에 열린 상위 세그먼트가 없으면 세그먼트가 누락될 수 있습니다. 자세한 내용을 보려면 AWS X-Ray 문제 해결을 참조하세요.

해결 방법

잘못된 계측

X-Ray SDK 사용 시 잘못된 계측

애플리케이션 코드가 지원되는 라이브러리 및 프레임워크를 패치하기 위해 X-Ray SDK에 올바르게 계측되지 않은 경우, 추적 누락이 발생할 수 있습니다. 다운스트림 서비스에 전달되지 않은 추적 ID도 추적 누락의 원인이 될 수 있습니다.

이 문제를 해결하려면 SDK에서 디버그 수준 로깅을 켜서 애플리케이션 로그 파일에 좀 더 자세한 로그를 출력하세요. 이를 통해 계측과 관련된 문제를 추가로 분리하고 애플리케이션 전체에서 추적 ID의 흐름을 추적할 수 있습니다. 또한 로그에는 추적이 샘플링되지 않아서 누락되었는지 또는 계측기 구성이 잘못되어 누락되었는지도 표시됩니다. 자세한 내용을 보려면 Java, Node.js, Python, .NET 또는 Ruby에 대한 X-Ray SDK에서 디버그 로깅을 확인하세요.

참고: 애플리케이션이 Java용 자동 계측 에이전트를 사용하는 경우 비동기 요청에 대한 추적을 캡처하지 않고 추적을 누락합니다. 누락된 추적이 있는 경우 수동 계측을 사용하세요. X-Ray SDK에 일부 기능이 누락되었거나 문제가 있는 경우, Java용 자동 계측 에이전트에 대한 OpenTelemetry SDK를 확인하세요.

OpenTelemetry SDK 사용 시 잘못된 계측

OpenTelemetry SDK를 사용하고 애플리케이션 코드가 지원되는 라이브러리 및 프레임워크를 패치하도록 올바르게 계측되지 않은 경우 코드에 추적이 누락될 수 있습니다. 다운스트림 서비스에 전달되지 않은 추적 ID로 인해 세그먼트 누락의 원인이 될 수 있습니다.

이 오류를 해결하려면 다음 작업을 수행하세요.

• SDK에서 디버그 수준 로깅을 켜서 애플리케이션 로그 파일에 좀 더 자세한 로그를 전송합니다. 이를 통해 계측과 관련된 문제를 추가로 분리하고 애플리케이션 전체에서 추적 ID의 흐름을 추적할 수 있습니다. 로그는 추적이 샘플링되지 않아서 누락되었는지 또는 계측기 구성이 잘못되어 누락되었는지를 나타냅니다. 자세한 내용을 보려면 Java, Node.js, Python, .NET 또는 Ruby에 대한 X-Ray SDK에서 디버그 로깅을 확인하세요.
• 계측이 꺼져 있지 않은지 확인하세요. 자세한 내용을 보려면 OpenTelemetry 웹 사이트에서 특정 자동 계측 기능 사용 안 함을 참조하세요.

참고: AWS 인프라 정보로 추적을 강화하려면, OpenTelemetry SDK에서 AWS 리소스 탐지기가 AWS 서비스에 대해 지원되는지 확인하세요. 자세한 내용을 보려면 AWS 리소스 탐지기 사용을 참조하세요.

X-Ray SDK가 대몬(daemon) 주소 또는 포트 번호를 통해 X-Ray 대몬(daemon)에 도달할 수 없습니다.

기본 또는 구성된 대몬(daemon) 포트 번호 및 주소를 통해 X-Ray SDK가 X-Ray 대몬(daemon)에 연결할 수 없는 경우, SDK에서 추적이 누락됩니다. X-Ray 대몬(daemon) 주소는 AWS_XRAY_DAEMON_ADDRESS 환경 변수와 함께 SDK에 전달됩니다. 기본적으로 X-ray 대몬(daemon)은 포트 2000 UDP에서 수신 대기합니다. 명령줄 옵션과 X-Ray 대몬(daemon)에 전달된 구성 파일을 통해 이 포트를 변경할 수 있습니다. 자세한 내용을 보려면 구성 파일 사용을 참조하세요.

디버그 로그와 함께 X-Ray 대몬(daemon)을 실행하는 경우 다음 명령을 실행하여 X-Ray 대몬(daemon)에 구성된 UDP 포트를 식별합니다:

./xray -l debug

참고: 다음 예에서는3000을 포트 번호로 식별합니다.

출력 예시:

2023-03-28T15:15:43-07:00 \[Debug\] Listening on UDP 127.0.0.1:3000

X-Ray 대몬(daemon) 로그에 액세스 거부 오류가 표시되면 IAM 권한을 확인하세요. 자세한 내용을 보려면 구성 파일 사용을 참조하세요.

참고: X-Ray 대몬(daemon)이 애플리케이션 및 X-Ray SDK와 동일한 시스템에서 실행되지 않는 경우 인바운드 및 수신 규칙을 확인하세요. 보안 그룹 인바운드 규칙 및 네트워크 액세스 제어 목록(네트워크 ACL) 수신 규칙이 트래픽을 허용하는지 확인합니다. X-Ray 대몬(daemon)의 리스너 포트를 통해 X-Ray SDK에 트래픽을 허용해야 합니다.

X-Ray 대몬(daemon)이 X-Ray 서비스 엔드포인트에 도달할 수 없습니다.

X-Ray 대몬(daemon)이 X-Ray 서비스 엔드포인트에 도달할 수 없는 경우 다음 작업을 수행하세요.

• 소스 엔드에서 프록시를 구성한 경우 프록시가 트래픽에서 X-Ray 서비스 엔드포인트에 도달하는 것을 허용하지 않는지 확인하세요.
• com.amazonaws.region.xray X-Ray Amazon Virtual Private Cloud(VPC) 엔드포인트를 사용하여 X-Ray 서비스에 연결하는 경우, 첨부된 보안 그룹을 확인합니다. 보안 그룹에 HTTPS 트래픽이 X-Ray 서비스 API로 데이터를 푸시할 수 있는 아웃바운드 트래픽이 있는지 확인합니다. 또한 보안 그룹이 포트 443에서 인바운드 트래픽을 허용하여 X-Ray 대몬(daemon)을 허용하는지 확인합니다.
• 연결된 네트워크 ACL 및 X-Ray Amazon VPC 엔드포인트에 모든 위치 0.0.0.0/0에 대해 포트 443에서 트래픽을 허용하는 송신 규칙이 있는지 확인합니다. X-Ray 대몬(daemon)은 X-Ray 서비스 엔드포인트로 데이터를 전송해야 합니다. 또한 네트워크 ACL 수신 규칙이 X-Ray 대몬(daemon)에서 Amazon VPC 엔드포인트로의 트래픽을 허용하는지 확인합니다.

추적이 개별 서비스 수준에서 구성되지 않았습니다.

특정 AWS 서비스에 대해 X-Ray 구성을 켜지 않으면 추적이 누락될 수 있습니다. 다음은 서비스 수준에서 X-Ray 구성을 켜야 하는 AWS 서비스 목록입니다.

• AWS AppSync
• AWS App Runner
• Amazon API Gateway
• Amazon CloudWatch RUM
• AWS Lambda
• Amazon Simple Notification Service(Amazon SNS)
• AWS Step Functions

IAM 권한 누락

필요한 IAM 권한이 있는지 확인합니다.

• X-Ray 대몬(daemon) 로그에 액세스 거부 오류가 표시되면 IAM 권한을 확인하세요. X-Ray 서비스 엔드포인트로 추적을 전송하려면 X-Ray 대몬(daemon) IAM 역할에 AWSXRAYDaemonWriteAccess 관리 정책의 권한이 필요합니다. IAM 정책에서 태그 기반 조건을 사용하는 경우 IAM 정책이 올바른 태그를 참조하는지 확인하세요. 자세한 내용을 보려면 X-Ray 태그 기반 인증을 참조하세요.
• X-Ray 대몬(daemon)에서 태스크의 사이드카 컨테이너로 Amazon Elastic Container Service(Amazon ECS)에서 실행되는 경우, Amazon ECS 작업 역할을 확인하세요. AWSXRayDaemonWriteAccess 정책이 Amazon ECS 작업 역할에 첨부되어 있는지 확인합니다.
• Amazon Elastic Kubernetes Service(Amazon EKS)에 X-Ray 대몬(daemon)을 배포하는 경우, 포드에서 사이드카 컨테이너를 확인합니다. 컨테이너가 IRSA(서비스 계정에 대한 IAM 역할)을 사용하고 AWSXRayDaemonWriteAccess 정책이 IAM 역할에 첨부되어 있는지 확인합니다.
• Amazon Elastic Compute Cloud(Amazon EC2)에서 X-ray 대몬(daemon)을 구성한 경우, 연결된 인스턴스 프로필을 확인하세요. 해당 EC2 인스턴스와 연결된 인스턴스 프로필 역할에 AWSXRayDaemonWriteAccess 정책이 첨부되어 있는지 확인합니다.
• AWS Lambda에서 X-Ray 대몬(daemon)을 구성한 경우, Lambda 실행 역할을 확인합니다. Lamda 실행 역할에 AWSXRayDaemonWriteAccess 정책이 있는지 확인합니다. 정책이 첨부되었는지 확인하세요.
• Amazon SNS에서 활성 추적을 켰는데도 여전히 추적을 볼 수 없는 경우 X-Ray 에서 리소스 정책을 구성하세요.

참고: X-Ray 권한을 확인하려면 IAM 정책 시뮬레이터를 사용하여 리소스에 연결된 IAM 역할 또는 정책을 테스트하세요. 또한 조직의 SCP(서비스 제어 정책)도 확인하세요. SCP는 계정 수준에서 특정 API 호출에 대한 액세스를 제한합니다.

X-Ray에 대한 IAM 관리 정책 목록은 X-Ray에 대한 IAM 관리 정책을 참조하세요.

샘플링 규칙 구성

샘플링 구성으로 활성 추적을 지원하는 X-Ray SDK 및 AWS 서비스가 추적을 샘플링하지 않으면 추적이 누락됩니다. 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본적으로 X-Ray SDK는 초당 첫 번째 요청과 추가 요청의 5%를 기록합니다. 샘플링 속도를 변경하여 기록되는 트레이스 수를 줄이거나 늘릴 수 있습니다.

예를 들어 리저버는 1로 설정됩니다. 리저버가 1이면 매 초마다 첫 번째 요청이 접수되었음을 나타냅니다. 또는 샘플링 속도가 0.1로 설정됩니다. 샘플링 속도가 0.1이면 매 초마다 10%의 추가 요청이 기록된다는 의미입니다.

X-Ray SDK는 SDK가 기록하는 요청 수를 제한하기 때문에 모든 요청이 추적되지 않을 수 있습니다. 더 많은 추적을 기록하려면 리저버 및 샘플링 속도 설정을 늘리세요. 자세한 내용을 보려면 샘플링 규칙 예제를 참조하세요.

참고: 여러 샘플링 규칙을 구성했는데 샘플링된 트레이스 수가 변동하는 경우 X-Ray SDK가 사용하는 샘플링 규칙을 확인하세요. 자세한 내용을 보려면 샘플링 결과 보기를 참조하세요.

OpenTelemetry Collector에 구성 누락

X-Ray 대몬(daemon) 대신 OpenTelemetry Collector를 사용하는 경우 필요한 수신기 및 내보내기 구성이 누락될 수 있습니다. 구성이 누락된 경우 추적은 X-Ray 서비스 엔드포인트로 전송되지 않습니다. 수신기에 따라 config.yaml 파일에서 수신기 구성을 확인하여 누락된 구성이 없는지 확인합니다.

GitHub 웹 사이트에서 다음 예제 구성을 참조하세요.

• X-Ray 내보내기
• X-Ray 수신기
• ZipKin 수신기

참고: 필요한 IAM 권한이 AWSXRayDaemonWriteAccess 관리형 정책에 있는지 확인합니다.