기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 로 추적 데이터 전송 AWS X-Ray
트레이스 데이터를 세그먼트 문서 형식으로 X-Ray로 전송할 수 있습니다. 세그먼트 문서는 애플리케이션이 요청을 처리하기 위해 수행하는 작업에 대한 정보를 포함하는 JSON 형식 문자열입니다. 애플리케이션은 스스로 수행하는 작업에 대한 데이터를 세그먼트에 기록하거나 다운스트림 서비스 및 리소스를 사용하는 작업을 하위 세그먼트에 기록할 수 있습니다.
세그먼트는 애플리케이션이 수행하는 작업에 대한 정보를 기록합니다. 세그먼트는 적어도 작업에 소비된 시간, 이름 및 두 개의 ID를 기록합니다. 트레이스 ID는 서비스 간에 이동하는 요청을 트레이스합니다. 세그먼트 ID는 단일 서비스의 요청에 대해 완료된 작업을 트레이스합니다.
**Example 최소 완료 세그먼트**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
요청이 수신되면 요청이 완료될 때까지 진행률 세그먼트를 자리 표시자로 전송할 수 있습니다.
**Example 진행 중인 세그먼트**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
세그먼트를 직접, [`PutTraceSegments`](#xray-api-segments), 또는 [X-Ray 대몬(daemon)을 통해](#xray-api-daemon) X-Ray로 보낼 수 있습니다.
대부분의 애플리케이션은 AWS SDK를 사용하여 다른 서비스를 호출하거나 리소스에 액세스합니다. 다운스트림 호출에 대한 정보를 *하위 세그먼트*에 기록합니다. X-Ray는 하위 세그먼트를 사용하여 세그먼트를 전송하지 않고 서비스 그래프에 세그먼트에 대한 항목을 생성하지 않는 다운스트림 서비스를 식별합니다.
하위 세그먼트는 전체 세그먼트 문서에 임베드되거나 개별적으로 전송될 수 있습니다. 하위 세그먼트를 개별적으로 전송하여 장시간 실행되는 요청에 대한 다운스트림 호출을 비동기식으로 트레이스하거나 최대 세그먼트 문서 크기(64 kB)를 초과하지 않도록 합니다.
**Example 하위 세그먼트**
하위 세그먼트는 `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 세그먼트 문서](xray-api-segmentdocuments.md) 단원을 참조하십시오.
**Topics**
+ [추적 ID 생성](#xray-api-traceids)
+ [PutTraceSegments 사용](#xray-api-segments)
+ [세그먼트 문서를 X 대몬(daemon)으로 전송](#xray-api-daemon)
## 추적 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 트레이스 컨텍스트 사양](https://www.w3.org/TR/trace-context/)을 준수하는 기타 프레임워크를 사용하여 생성된 트레이스 ID를 지원합니다. X-Ray로 전송할 때 W3C 트레이스 ID는 X-Ray 트레이스 ID 형식이어야 합니다. 예를 들어, W3C 트레이스 ID `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 – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## PutTraceSegments 사용
[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) 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 사용 설명서의 [문자열 인용](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)을 참조하십시오.
출력에는 처리를 실패한 세그먼트가 모두 나열됩니다. 예를 들어 트레이스 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) 실행하기](xray-daemon-local.md) 섹션을 참조하세요.
데몬 헤더 `{"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
```
**Example 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) 로그](xray-daemon.md#xray-daemon-logging)를 통해 세그먼트가 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)
```