트레이스 데이터를 세그먼트 문서 형식으로 X-Ray로 전송할 수 있습니다. 세그먼트 문서는 애플리케이션이 요청을 처리하기 위해 수행하는 작업에 대한 정보를 포함하는 JSON 형식 문자열입니다. 애플리케이션은 스스로 수행하는 작업에 대한 데이터를 세그먼트에 기록하거나 다운스트림 서비스 및 리소스를 사용하는 작업을 하위 세그먼트에 기록할 수 있습니다.
세그먼트는 애플리케이션이 수행하는 작업에 대한 정보를 기록합니다. 세그먼트는 적어도 작업에 소비된 시간, 이름 및 두 개의 ID를 기록합니다. 트레이스 ID는 서비스 간에 이동하는 요청을 트레이스합니다. 세그먼트 ID는 단일 서비스의 요청에 대해 완료된 작업을 트레이스합니다.
예 최소 완료 세그먼트
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
요청이 수신되면 요청이 완료될 때까지 진행률 세그먼트를 자리 표시자로 전송할 수 있습니다.
예 진행 중인 세그먼트
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
세그먼트를 직접, PutTraceSegments, 또는 X-Ray 대몬(daemon)을 통해 X-Ray로 보낼 수 있습니다.
대부분의 애플리케이션은 AWS SDK를 사용하여 다른 서비스를 호출하거나 리소스에 액세스합니다. 다운스트림 호출에 대한 정보를 하위 세그먼트에 기록합니다. X-Ray는 하위 세그먼트를 사용하여 세그먼트를 전송하지 않고 서비스 그래프에 세그먼트에 대한 항목을 생성하지 않는 다운스트림 서비스를 식별합니다.
하위 세그먼트는 전체 세그먼트 문서에 임베드되거나 개별적으로 전송될 수 있습니다. 하위 세그먼트를 개별적으로 전송하여 장시간 실행되는 요청에 대한 다운스트림 호출을 비동기식으로 트레이스하거나 최대 세그먼트 문서 크기(64 kB)를 초과하지 않도록 합니다.
예 하위 세그먼트
하위 세그먼트는 subsegment
의 type
과 상위 세그먼트를 식별하는 parent_id
를 갖습니다.
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
세그먼트와 하위 세그먼트에 포함할 수 있는 필드 및 값에 대한 자세한 내용은 AWS X-Ray 세그먼트 문서 단원을 참조하십시오.
추적 ID 생성
데이터를 X-Ray로 전송하려면 각 요청에 대해 고유한 트레이스 ID를 생성해야 합니다.
X-Ray 트레이스 ID 형식
X-Ray trace_id
는 하이픈으로 구분된 3개의 숫자로 구성됩니다. 예: 1-58406520-a006649127e371903a2de979
. 여기에는 다음이 포함됩니다.
-
버전 번호(
1
) -
원래 요청의 시간(8자리 16진수를 사용하는 Unix 에포크 시간)
예를 들어, 에포크 시간으로 2016년 12월 1일 오전 10시(PST)는
1480615200
초이며, 16진수로는58406520
입니다. -
트레이스의 96비트 글로벌 고유 식별자(24자리 16진수)
참고
X-Ray는 이제 OpenTelemetry 및 W3C 트레이스 컨텍스트 사양4efaaf4d1e8720b39541901950019ee5
는 X-Ray로 전송할 때 1-4efaaf4d-1e8720b39541901950019ee5
와 같은 형식이어야 합니다. X-Ray 트레이스 ID에는 원래 요청 타임스탬프(Unix 에포크 시간)가 포함되어 있지만, W3C 트레이스 ID를 X-Ray 형식으로 전송할 때는 필요하지 않습니다.
테스트용 엑스레이 트레이스 ID를 생성하는 스크립트를 작성할 수 있습니다. 다음은 두 가지 예입니다.
Python
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
Bash
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
트레이스 ID를 생성하고 세그먼트를 X-Ray 대몬(daemon)으로 보내는 스크립트에 대해 Scorekeep 샘플 애플리케이션을 확인합니다.
-
Python –
xray_start.py
-
Bash –
xray_start.sh
PutTraceSegments 사용
PutTraceSegments
API를 사용하여 세그먼트 문서를 업로드할 수 있습니다. 이 API에는 JSON 세그먼트 문서의 목록을 가져오는 단일 파라미터 TraceSegmentDocuments
가 있습니다.
AWS CLI에서 aws xray put-trace-segments
명령을 사용하여 세그먼트 문서를 X-Ray로 직접 전송합니다.
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
참고
Windows 명령 처리기와 Windows PowerShell은 JSON 문자열에서의 인용 부호 요구 사항이 다릅니다. 자세한 내용은 AWS CLI 사용 설명서의 문자열 인용을 참조하십시오.
출력에는 처리를 실패한 세그먼트가 모두 나열됩니다. 예를 들어 트레이스 ID의 날짜가 너무 먼 과거일 경우 다음과 같은 오류가 반환됩니다.
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
여러 세그먼트 문서를 공백으로 구분하여 동시에 전달할 수 있습니다.
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
세그먼트 문서를 X 대몬(daemon)으로 전송
세그먼트 문서를 API로 전송하는 대신, 세그먼트 및 하위 세그먼트를 X-Ray 대몬(daemon)으로 전송할 수 있습니다. 이 대몬(daemon)은 세그먼트 및 하위 세그먼트를 버퍼링하다가 배치 단위로 X-Ray API로 업로드합니다. X-Ray SDK는 AWS로 직접 호출을 방지하기 위해 세그먼트 문서를 대몬(daemon)으로 전송합니다.
참고
데몬을 실행하는 방법은 로컬에서 X-Ray 대몬(daemon) 실행하기 단원을 참조하십시오.
데몬 헤더 {"format": "json", "version": 1}\n
가 앞에 붙은 JSON 형식 세그먼트를 UDP 포트 2000으로 전송합니다.
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
Linux에서는 세그먼트 문서를 Bash 터미널에서 데몬으로 전송할 수 있습니다. 헤더와 세그먼트 문서를 텍스트 파일로 저장하고 cat
을 사용하여 /dev/udp
로 파일을 파이프합니다.
$ cat segment.txt > /dev/udp/127.0.0.1/2000
예 segment.txt
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
대몬(daemon) 로그를 통해 세그먼트가 X-Ray로 전송되었는지 확인합니다.
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)