AWS X-Ray는 마이크로서비스 또는 서버리스 아키텍처에서 요청이 각 서비스를 거치는 흐름을 추적(Tracing)하고 시각화하는 분산 트레이싱 서비스입니다. 단일 HTTP 요청이 API Gateway → Lambda → DynamoDB → 외부 API까지 이동하는 경로를 시각적으로 확인하고, 어느 구간에서 지연이 발생하거나 오류가 났는지 정확히 파악할 수 있습니다. CloudWatch Logs만으로는 식별하기 어려운 성능 병목과 오류 원인을 빠르게 진단하는 데 활용됩니다.
분산 트레이싱(Distributed Tracing): 여러 서비스에 걸친 단일 요청의 흐름을 고유 ID로 연결하여 전체 경로를 추적하는 기법.
Trace는 하나의 요청이 시스템을 통과하는 전체 여정을 나타냅니다. 최초 요청이 들어올 때 고유한 Trace ID가 생성되고, 이 ID가 요청과 함께 각 서비스로 전파됩니다. 하나의 Trace는 여러 Segment로 구성됩니다.
Segment는 Trace를 구성하는 개별 서비스 단위의 처리 기록입니다. 각 서비스(Lambda, EC2, DynamoDB 등)는 요청을 처리할 때 자신의 Segment를 생성하여 X-Ray로 전송합니다. Segment에는 시작 시간, 종료 시간, 오류 여부, HTTP 상태 코드 등이 기록됩니다.
Subsegment는 Segment 내에서 세부 작업(DynamoDB 쿼리, 외부 HTTP 호출 등)을 추가로 추적할 때 사용합니다.
Trace (Trace ID: 1-abc-123...)
|
+--- Segment: API Gateway
| 시작: 0ms / 종료: 250ms
|
+--- Segment: Lambda (my-function)
| 시작: 5ms / 종료: 240ms
| |
| +--- Subsegment: DynamoDB GetItem
| | 시작: 10ms / 종료: 50ms
| |
| +--- Subsegment: External HTTP Call
| 시작: 60ms / 종료: 200ms
|
+--- 최종 응답 반환
Service Map은 X-Ray가 수집한 Trace 데이터를 기반으로 서비스 간 의존 관계를 자동으로 그려주는 시각화 기능입니다. 각 서비스 노드의 응답 시간, 요청 수, 오류율을 함께 표시하므로 전체 아키텍처에서 문제가 되는 서비스를 한눈에 파악할 수 있습니다.
Service Map 예시
[Client]
|
v
[API Gateway] ──> [Lambda: auth-fn] ──> [DynamoDB: users]
|
v
[Lambda: api-fn]
|
+──> [DynamoDB: orders]
|
+──> [S3: assets]
|
+──> [External: payment-api] <-- 오류율 높음 (빨간색 표시)
Lambda에서 X-Ray를 활성화하려면 함수 설정에서 "Active Tracing"을 켜면 됩니다. Lambda 런타임이 자동으로 Segment를 생성하고 X-Ray로 전송합니다. 추가로 AWS X-Ray SDK를 사용하면 Lambda 함수 내부의 DynamoDB 호출, 외부 HTTP 요청 등을 Subsegment로 세밀하게 추적할 수 있습니다.
import AWSXRay from 'aws-xray-sdk-core';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
// SDK 클라이언트를 X-Ray로 감싸면 자동으로 Subsegment 생성
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({}));
API Gateway에서도 X-Ray 트레이싱을 Stage 설정에서 활성화할 수 있습니다. API Gateway가 요청을 받을 때 Trace ID를 생성하고, Lambda로 전달되는 헤더에 포함시킵니다. Lambda에서 이 Trace ID를 이어받아 Segment를 이어나가므로, API Gateway부터 Lambda까지의 전체 흐름이 하나의 Trace로 연결됩니다.
ECS에서는 X-Ray 데몬(Daemon)을 사이드카 컨테이너로 태스크에 추가합니다. 애플리케이션 컨테이너가 X-Ray SDK로 생성한 Segment 데이터를 사이드카 데몬에 UDP로 전송하면, 데몬이 이를 X-Ray 서비스로 전달합니다.
사이드카(Sidecar): 메인 애플리케이션 컨테이너와 함께 실행되어 보조 기능(로깅, 트레이싱 등)을 담당하는 보조 컨테이너.
ECS Task
+-------------------+ UDP +-------------------+
| App Container | ──────────> | X-Ray Daemon |
| (비즈니스 로직) | Segments | (사이드카) |
+-------------------+ +-------------------+
|
| HTTPS
v
AWS X-Ray Service
X-Ray는 단순한 로그 수집을 넘어 요청의 흐름 전체를 맥락과 함께 파악할 수 있게 해 줍니다. 특히 서버리스나 마이크로서비스처럼 서비스가 여러 개로 분산된 아키텍처에서 장애 원인을 신속하게 진단하는 데 강력한 도구입니다.