기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
X-Ray API 사용
X-Ray SDK가 프로그래밍 언어를 지원하지 않는 경우, X-Ray API를 직접 사용하거나 AWS Command Line Interface (AWS CLI) 를 사용하여 X-Ray API 명령을 호출할 수 있습니다. 다음 지침을 사용하여 API와 상호 작용하는 방법을 선택하십시오.
-
미리 형식이 AWS CLI 지정된 명령을 사용하거나 요청 내 옵션과 함께 사용하여 더 간단한 구문을 사용하십시오.
-
X-Ray API를 직접 사용하여 X-Ray에 보내는 요청에 대한 유연성을 극대화하고 사용자 지정할 수 있습니다.
대신 X-Ray API를 직접 사용하는 경우 요청을 올바른 데이터 형식으로 매개변수화해야 하며 인증 및 오류 처리를 구성해야 할 수도 있습니다. AWS CLI
다음 다이어그램은 X-Ray API와 상호 작용하는 방법을 선택하기 위한 지침을 보여줍니다.
X-Ray API를 사용하여 트레이스 데이터를 X-Ray에 직접 전송할 수 있습니다. X-Ray API는 다음과 같은 일반적인 작업을 포함하여 X-Ray SDK에서 사용할 수 있는 모든 기능을 지원합니다.
-
PutTraceSegments— 세그먼트 문서를 X-Ray에 업로드합니다.
-
BatchGetTraces— 추적 ID 목록에서 추적 목록을 검색합니다. 검색된 각 트레이스는 단일 요청으로 이루어진 세그먼트 문서 모음입니다.
-
GetTraceSummaries— 트레이스의 ID 및 주석을 검색합니다. a를
FilterExpression지정하여 추적 요약의 하위 집합을 검색할 수 있습니다. -
GetTraceGraph— 특정 추적 ID에 대한 서비스 그래프를 검색합니다.
-
GetServiceGraph— 들어오는 요청을 처리하고 다운스트림 요청을 호출하는 서비스를 설명하는 JSON 서식이 지정된 문서를 검색합니다.
또한 애플리케이션 코드 내의 AWS Command Line Interface (AWS CLI) 를 사용하여 프로그래밍 방식으로 X-Ray와 상호 작용할 수 있습니다. 는 다른 AWS 서비스기능을 포함하여 X-Ray SDK에서 사용할 수 있는 모든 기능을 AWS CLI 지원합니다. 다음 함수는 앞서 나열한 API 작업의 간단한 형식 버전입니다.
-
put-trace-segments
— 세그먼트 문서를 X-Ray에 업로드합니다. -
batch-get-traces
— 추적 ID 목록에서 추적 목록을 검색합니다. 검색된 각 트레이스는 단일 요청으로 이루어진 세그먼트 문서 모음입니다. -
get-trace-summaries
— 트레이스의 ID 및 주석을 검색합니다. a를 FilterExpression지정하여 추적 요약의 하위 집합을 검색할 수 있습니다. -
get-trace-graph
— 특정 추적 ID에 대한 서비스 그래프를 검색합니다. -
get-service-graph
— 들어오는 요청을 처리하고 다운스트림 요청을 호출하는 서비스를 설명하는 JSON서식이 지정된 문서를 검색합니다.
시작하려면 운영 체제에 맞게 AWS CLI를 설치해야 합니다. AWS 지원 Linux macOS 및 Windows 운영 체제. X-Ray 명령 목록에 대한 자세한 내용은 X-Ray용AWS CLI 명령 참조 안내서를
X-Ray API 살펴보기
X-Ray API는 AWS SDK를 통해 또는 HTTPS를 통해 직접 모든 X-Ray 기능에 액세스할 수 있도록 합니다. AWS Command Line InterfaceX-Ray API Reference에는 API 작업의 입력 파라미터, 그리고 해당 입력 파라미터가 반환하는 필드 및 데이터 형식이 설명되어 있습니다.
AWS SDK를 사용하여 X-Ray API를 사용하는 프로그램을 개발할 수 있습니다. X-Ray 콘솔과 X-Ray 데몬은 모두 AWS SDK를 사용하여 X-Ray와 통신합니다. 각 언어의 AWS SDK에는 X-Ray API 작업 및 유형에 매핑되는 클래스 및 메서드에 대한 참조 문서가 있습니다.
AWS SDK 레퍼런스
-
Java – AWS SDK for Java
-
JavaScript – AWS SDK for JavaScript
-
.NET – AWS SDK for .NET
-
Ruby – AWS SDK for Ruby
-
Go – AWS Go용 SDK
-
PHP – AWS SDK for PHP
-
Python – AWS SDK for Python (Boto)
AWS Command Line Interface 는 Python용 SDK를 사용하여 AWS API를 호출하는 명령줄 도구입니다. AWS API를 처음 학습할 때는 사용 가능한 매개변수를 탐색하고 JSON 또는 텍스트 형식으로 서비스 출력을 볼 수 있는 쉬운 방법을 AWS CLI 제공합니다.
aws xray하위 명령에 대한 자세한 내용은 AWS CLI 명령 참조를 참조하십시오.
AWS CLI를 사용하면 X-Ray 서비스에 직접 액세스하고 X-Ray 콘솔이 서비스 그래프 및 원시 추적 데이터를 검색하는 데 사용하는 것과 동일한 API를 사용할 수 있습니다. 샘플 애플리케이션에는 AWS CLI에서 이러한 API를 사용하는 방법을 보여주는 스크립트가 포함되어 있습니다.
필수 조건
이 튜토리얼에서는 Scorekeep 샘플 애플리케이션과 포함된 스크립트를 사용하여 트레이스 데이터와 서비스 맵을 생성합니다. 샘플 애플리케이션 자습서의 지침에 따라 애플리케이션을 시작하십시오.
이 자습서에서는 AWS CLI 를 사용하여 X-Ray API의 기본 사용법을 보여줍니다. 윈도우, 리눅스, OS-X에서 사용할 수 있는 AWS CLI는 누구나 퍼블릭 API에 대한 명령줄 액세스를 제공합니다. AWS 서비스
참고
샘플 애플리케이션이 생성된 지역과 동일한 지역으로 AWS CLI 구성되었는지 확인해야 합니다.
샘플 애플리케이션 테스트용으로 포함된 스크립트는 cURL을 사용하여 API 및 jq로 트래픽을 보내 출력을 구문 분석합니다. jq 실행 파일은 stedolan.github.iocurl 실행 파일은 https://curl.haxx.se/download.html
데이터 추적 생성
웹 앱은 게임이 진행되는 동안 몇 초마다 계속해서 API로 가는 트래픽을 생성하지만 생성되는 요청은 한 가지 유형뿐입니다. API를 테스트하는 동안 test-api.sh 스크립트를 사용하여 종단 간 시나리오를 실행하고 보다 다양한 트레이스 데이터를 생성합니다.
test-api.sh 스크립트를 사용하려면
Elastic Beanstalk 콘솔
을 엽니다. 사용 중인 환경의 관리 콘솔로 이동합니다.
-
페이지 헤더에서 환경 URL을 복사합니다.
-
bin/test-api.sh를 열고 API 값을 환경 URL로 바꿉니다.#!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api -
API로 가는 트래픽을 생성하는 스크립트를 실행합니다.
~/debugger-tutorial$./bin/test-api.shCreating users, session, game, configuring game, playing game, ending game, game complete. {"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
X-Ray API 사용
AWS CLI는 및 을 포함하여 GetServiceGraphX-Ray가 제공하는 모든 API 작업에 대한 명령을 제공합니다. GetTraceSummaries 지원되는 모든 작업과 각 작업에서 사용되는 데이터 형식에 대한 자세한 내용은 AWS X-Ray API 참조를 참조하십시오.
예 bin/service-graph.sh
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH이 스크립트는 마지막 10분간의 서비스 그래프를 가져옵니다.
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...예 bin/trace-urls.sh
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'이 스크립트는 1분 전과 2분 전 사이에 생성된 트레이의 URL을 가져옵니다.
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]예 bin/full-traces.sh
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'이 스크립트는 1분 전과 2분 전 사이에 생성된 모든 트레이를 가져옵니다.
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
정리
Elastic Beanstalk 환경을 종료하여 Amazon EC2 인스턴스, DynamoDB 테이블 및 기타 리소스를 종료합니다.
Elastic Beanstalk 환경을 종료하려면
Elastic Beanstalk 콘솔
을 엽니다. 사용 중인 환경의 관리 콘솔로 이동합니다.
-
작업을 선택합니다.
-
[Terminate Environment]를 선택합니다.
-
종료를 선택합니다.
트레이스 데이터는 30일 후에 X-Ray에서 자동으로 삭제됩니다.
트레이스 데이터를 세그먼트 문서 형식으로 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”
}세그먼트와 하위 세그먼트에 포함할 수 있는 필드 및 값에 대한 자세한 내용은 X-Ray 세그먼트 문서 단원을 참조하십시오.
데이터를 X-Ray로 보내려면 각 요청에 대해 고유한 추적 ID를 생성해야 합니다.
X-Ray 트레이스 ID 형식
X-Ray trace_id는 하이픈으로 구분된 3개의 숫자로 구성됩니다. 예를 들어 1-58406520-a006649127e371903a2de979입니다. 여기에는 다음이 포함됩니다.
-
버전 번호, 즉
1. -
원래 요청 시간을 Unix 시대 시간으로 나타낸 8자리 16진수
예를 들어, 2016년 12월 1일 오전 10시 (PST) 기준 에포크 타임은 초 또는 16진수로 표시됩니다.
148061520058406520 -
24자리 16진수 트레이스를 위한 전 세계적으로 고유한 96비트 식별자입니다.
참고
이제 X-Ray는 W3C Trace Context 사양을 준수하는 기타 프레임워크를 사용하여 OpenTelemetry 만든 추적1-4efaaf4d-1e8720b39541901950019ee5 때와 같은 형식으로 4efaaf4d1e8720b39541901950019ee5 지정해야 합니다. X-Ray Trace 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 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는 JSON 문자열에서 따옴표를 인용하거나 이스케이프하는 데 필요한 요구 PowerShell 사항이 다릅니다. 자세한 내용은 AWS CLI 사용 설명서의 문자열 인용을 참조하십시오.
출력에는 처리를 실패한 세그먼트가 모두 나열됩니다. 예를 들어 트레이스 ID의 날짜가 너무 먼 과거일 경우 다음과 같은 오류가 반환됩니다.
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}여러 세그먼트 문서를 공백으로 구분하여 동시에 전달할 수 있습니다.
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"세그먼트 문서를 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)X-Ray는 전송하는 추적 데이터를 처리하여 JSON으로 전체 추적, 추적 요약 및 서비스 그래프를 생성합니다. AWS CLI를 사용하여 API에서 직접 생성된 데이터를 검색할 수 있습니다.
GetServiceGraph API를 사용하여 JSON 서비스 그래프를 검색할 수 있습니다. API는 시작 시간과 종료 시간을 필요로 합니다. 이 시간은 Linux에서 date 명령을 사용하여 계산할 수 있습니다.
$ date +%s
1499394617date +%s는 날짜를 초 단위로 출력합니다. 이 숫자를 종료 시간으로 사용하고, 여기에서 시간을 차감하여 시작 시간을 구합니다.
예 마지막 10분간의 서비스 그래프를 가져오기 위한 스크립트
EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
다음 예제는 클라이언트 노드, EC2 인스턴스, DynamoDB 테이블 및 Amazon SNS 주제를 포함한 4개의 노드가 있는 서비스 그래프를 보여줍니다.
예 GetServiceGraph 출력
{ "Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Type": "client", "State": "unknown", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 2, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "Aliases": [] } ] }, { "ReferenceId": 1, "Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA", "Names": [ "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA" ], "Type": "AWS::DynamoDB::Table", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "DurationHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ] }, { "ReferenceId": 2, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Root": true, "Type": "AWS::EC2::Instance", "State": "active", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 1, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "Aliases": [] }, { "ReferenceId": 3, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "Aliases": [] } ], "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "DurationHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ] }, { "ReferenceId": 3, "Name": "SNS", "Names": [ "SNS" ], "Type": "AWS::SNS", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "DurationHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ] } ] }
그룹의 콘텐츠에 기반한 서비스 그래프를 호출하려면 groupName 또는 groupARN를 포함합니다. 다음의 예는 Example1이라는 그룹에 서비스 그래프를 호출하는 방법을 보여줍니다.
예 그룹 Example1의 이름으로 서비스 그래프를 검색하기 위한 스크립트
aws xray get-service-graph --group-name "Example1"
GetTraceSummaries API를 사용하여 트레이스 요약의 목록을 가져올 수 있습니다. 트레이스 요약에는 주석, 요청/응답 정보 및 ID를 포함한 전체 트레이스를 다운로드하려는 트레이스를 식별하는 데 사용할 수 있는 정보가 포함됩니다.
aws xray
get-trace-summaries를 호출할 때 사용할 수 있는 두 가지 TimeRangeType 플래그가 있습니다.
-
TraceId— 기본
GetTraceSummaries검색에서는 TraceID 시간을 사용하고 계산된 범위 내에서 시작된 트레이스를 반환합니다.[start_time, end_time)이 타임스탬프 범위는 내의 타임스탬프 인코딩을 기반으로 계산되거나 수동으로 정의할 수 있습니다. TraceId -
이벤트 시간 — 시간 경과에 따라 발생하는 이벤트를 검색하기 위해 AWS X-Ray에서는 이벤트 타임스탬프를 사용하여 트레이스를 검색할 수 있습니다. Event 시간은 트레이스가 시작된 시간에 관계없이
[start_time, end_time)범위 동안 활성 트레이스를 반환합니다.
aws xray get-trace-summaries 명령을 사용하여 트레이스 요약의 목록을 가져옵니다. 다음 명령은 기본 시간을 사용하여 과거 1~2분 사이의 추적 요약 목록을 가져옵니다. TraceId
예 트레이스 요약을 획득하는 스크립트
EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
예 GetTraceSummaries 출력
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}BatchGetTraces API를 사용하여 출력 내 트레이스 ID로 전체 트레이스를 검색합니다.
예 BatchGetTraces 명령
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b예 BatchGetTraces 출력
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}전체 트레이스에는 동일한 트레이스 ID로 수신된 모든 세그먼트 문서로부터 컴파일된 각 세그먼트의 문서가 포함됩니다. 데이터는 애플리케이션에서 X-Ray로 전송되므로 이러한 문서는 데이터를 나타내지 않습니다. 그 대신 X-Ray; 서비스에 의해 생성된 처리된 문서를 나타냅니다. X-Ray는 애플리케이션이 전송한 세그먼트 문서를 컴파일하고 세그먼트 문서 스키마를 준수하지 않는 데이터를 제거하여 전체 트레이스 문서를 생성합니다. 자세한 정보는 X-Ray 세그먼트 문서을 참조하세요.
또한 X-Ray는 세그먼트를 직접 전송하지 않는 서비스에 대한 다운스트림 호출을 위해 추정된 세그먼트를 생성합니다. 예를 들어, 계측되는 클라이언트를 사용하여 DynamoDB를 직접 호출하는 경우, X-Ray SDK가 자신의 관점에서 직접 호출에 대한 세부 정보를 하위 세그먼트에 기록합니다. 하지만 DynamoDB는 해당 세그먼트를 전송하지 않습니다. X-Ray는 하위 세그먼트의 정보를 사용하여 추적 맵의 DynamoDB 리소스를 나타내는 추론된 세그먼트를 만들고 추적 문서에 추가합니다.
API에서 여러 트레이스를 가져오려면 AWS CLI 쿼리를 통해 get-trace-summaries 출력에서 추출할 수 있는 트레이스 ID 목록이 필요합니다. 특정 기간에 대해 전체 트레이스를 가져오려면 목록을 batch-get-traces의 입력으로 리디렉션합니다.
예 1분간의 전체 트레이스를 가져오기 위한 스크립트
EPOCH=$(date +%s) TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text) aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
GetTraceSummaries API로 추적 요약을 생성하면 부분 추적 요약을 JSON 형식으로 재사용하여 근본 원인을 기반으로 정제된 필터 표현식을 생성할 수 있습니다. 구체화 단계에 대한 연습은 아래 예제를 참조하십시오.
예제 GetTraceSummaries 출력 - 응답 시간 근본 원인 섹션
{ "Services": [ { "Name": "GetWeatherData", "Names": ["GetWeatherData"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetWeatherData", "Coverage": 1.0, 'Remote": false }, { "Name": "get_temperature", "Coverage": 0.8, "Remote": false } ] }, { "Name": "GetTemperature", "Names": ["GetTemperature"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetTemperature", "Coverage": 0.7, "Remote": false } ] } ] }
위 출력을 편집하여 생략하면 일치하는 근본 원인 개체마다 이 JSON을 필터로 사용할 수 있습니다. JSON의 필드는 모든 후보 일치가 정확해야 합니다. 그렇지 않으면 트레이스가 반환되지 않습니다. 제거된 필드는 필터 표현식 쿼리 구조와 호환되는 형식인 와일드카드 값이 됩니다.
예 변경된 응답 시간 근본 원인
{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [ { "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }
이 JSON은 rootcause.json = #[{}] 호출을 통해 필터 표현식의 일부로 사용됩니다. 필터 식을 사용한 쿼리에 대한 자세한 내용은 Explore the X-Ray 콘솔의 필터 표현식 사용 섹션을 참조하십시오.
예 JSON 필터 예제
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
X-Ray는 샘플링 규칙, 그룹 규칙 및 암호화 설정을 구성하기 위한 API를 제공합니다.
암호화 설정
암호화에 사용할 AWS Key Management Service (AWS KMS) 키를 지정하는 PutEncryptionConfig데 사용합니다.
참고
X-Ray는 비대칭 KMS 키를 지원하지 않습니다.
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}키 ID로는 예제에 나온 것처럼 별칭이나 키 ID, 또는 Amazon 리소스 이름(ARN)을 사용할 수 있습니다.
GetEncryptionConfig를 사용하여 현재 구성을 가져옵니다. X-Ray가 설정 적용을 마치면 상태는 UPDATING에서 ACTIVE로 바뀝니다.
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}KMS 키 사용을 중단하고 기본 암호화를 사용하려면 암호화 유형을 NONE으로 설정합니다.
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}X-Ray API로 계정의 샘플링 규칙을 관리할 수 있습니다. 샘플링에 대한 자세한 내용은 을 참조하십시오샘플링 규칙을 구성합니다.. 태그 추가 및 관리에 대한 자세한 내용은 X-Ray 샘플링 규칙 및 그룹 태그 지정하기 섹션을 참조하세요.
GetSamplingRules로 모든 샘플링 규칙을 가져옵니다.
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}기본 규칙은 다른 규칙과 일치하지 않는 모든 요청에 적용됩니다. 우선 순위가 가장 낮은 규칙으로 삭제할 수 없습니다. 그러나 UpdateSamplingRule로 비율과 리저버 크기를 변경할 수 있습니다.
예 UpdateSamplingRule에 대한 API 입력 – 10000-default.json
{ "SamplingRuleUpdate": { "RuleName": "Default", "FixedRate": 0.01, "ReservoirSize": 0 } }
다음 예제에서는 이전 파일을 입력으로 사용하여 기본 규칙을 리저버가 없는 1퍼센트로 변경합니다. 태그는 선택 사항입니다. 태그를 추가하는 경우 태그 키가 필요하며 태그 값은 선택 사항입니다. 샘플링 규칙에서 기존 태그를 제거하려면 를 사용하십시오 UntagResource.
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
CreateSamplingRule로 추가 샘플링 규칙을 만듭니다. 규칙을 만들 때 대부분의 규칙 필드는 필수입니다. 다음 예제에서는 규칙 두 개를 만듭니다. 이 첫 번째 규칙은 Scorekeep 샘플 애플리케이션의 기본 비율을 설정하며, 우선 순위가 더 높은 규칙과 일치하지 않는 API에서 처리하는 모든 요청과 일치합니다.
예 UpdateSamplingRule에 대한 API 입력 – 9000-base-scorekeep.json
{ "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 } }
두 번째 규칙은 Scorekeep에도 적용되지만, 우선 순위가 더 높고 구체적입니다. 이 규칙은 폴링 요청에 대해 매우 낮은 샘플링 비율을 설정합니다. 게임 상태에 변경 사항이 있는지 확인하기 위해 클라이언트가 몇 초마다 수행하는 GET 요청입니다.
예 UpdateSamplingRule에 대한 API 입력 – 5000-polling-scorekeep.json
{ "SamplingRule": { "RuleName": "polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1 } }
태그는 선택 사항입니다. 태그를 추가하는 경우 태그 키가 필요하며 태그 값은 선택 사항입니다.
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}샘플링 규칙을 삭제하려면 DeleteSamplingRule을 사용합니다.
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}X-Ray API를 이용해 계정의 그룹을 관리할 수 있습니다. 그룹은 필터 표현식으로 정의한 추적 모음입니다. 그룹을 사용하여 추가 서비스 그래프를 생성하고 Amazon CloudWatch 지표를 제공할 수 있습니다. X-Ray API를 통한 서비스 그래프 및 지표 작업에 대한 자세한 내용은 X-Ray에서 데이터 가져오기 항목을 참조하십시오. 그룹에 대한 자세한 정보는 그룹 구성 섹션을 참조하세요. 태그 추가 및 관리에 대한 자세한 내용은 X-Ray 샘플링 규칙 및 그룹 태그 지정하기 섹션을 참조하세요.
CreateGroup이(가) 있는 그룹 생성 태그는 선택 사항입니다. 태그를 추가하는 경우 태그 키가 필요하며 태그 값은 선택 사항입니다.
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
GetGroups로 기존 그룹을 모두 가져옵니다.
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}UpdateGroup이(가) 있는 그룹 업데이트 태그는 선택 사항입니다. 태그를 추가하는 경우 태그 키가 필요하며 태그 값은 선택 사항입니다. 그룹에서 기존 태그를 제거하려면 를 사용하십시오 UntagResource.
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
DeleteGroup이(가) 있는 그룹 삭제
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
X-Ray SDK는 X-Ray API를 사용하여 샘플링 규칙을 가져오고, 샘플링 결과를 보고하고, 할당량을 가져옵니다. 이러한 API를 사용하여 샘플링 규칙의 작동 방식을 더 잘 이해하거나, X-Ray SDK가 지원하지 않는 언어로 샘플링을 구현할 수 있습니다.
먼저 GetSamplingRules로 모든 샘플링 규칙을 가져옵니다.
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
출력에는 기본 규칙과 사용자 지정 규칙이 포함됩니다. 아직 샘플링 규칙을 만들지 않은 경우 X-Ray API를 사용하여 샘플링, 그룹 및 암호화 설정 구성을 참조하십시오.
우선 순위의 오름차순에 따라 수신 요청과 비교하여 규칙을 평가합니다. 규칙이 일치하면 고정 비율과 리저버 크기를 사용하여 샘플링 결정을 내립니다. 샘플링된 요청을 기록하고 샘플링되지 않은 요청을 무시합니다(추적 목적). 샘플링 결정을 내릴 때 규칙 평가를 중지합니다.
규칙 리저버 크기는 고정 비율을 적용하기 전에 초당 기록할 목표 트레이스 수입니다. 리저버는 모든 서비스에 누적 적용되므로 직접 사용할 수 없습니다. 하지만 0이 아닌 경우 X-Ray가 할당량을 할당할 때까지 리저버에서 초당 트레이스 하나를 빌릴 수 있습니다. 할당량을 수신하기 전에 매초 첫 번째 요청을 기록하고, 추가 요청에 고정 비율을 적용합니다. 고정 비율은 0~1.00(100%)의 십진수입니다.
다음 예제에서는 지난 10초간 내린 샘플링 결정에 대한 세부 정보가 포함된 GetSamplingTargets에 대한 호출을 보여 줍니다.
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
X-Ray의 응답에는 리저버에서 빌리는 대신에 사용할 할당량이 포함됩니다. 이 예제에서 서비스는 10초간 리저버에서 트레이스 10개를 빌렸고, 다른 100개 요청에 고정 비율 10%를 적용했으며, 그 결과 샘플링된 요청은 총 20개입니다. 할당량은 5분 (유효 시간으로 표시) 동안 또는 새 할당량이 할당될 때까지 유효합니다. X-Ray는 기본값보다 긴 보고 간격을 할당할 수 있지만 여기서는 그렇지 않습니다.
참고
X-Ray의 응답에는 처음 직접 호출할 때의 할당량이 포함되지 않을 수 있습니다. 할당량이 할당될 때까지 리저버에서 계속 빌리십시오.
응답의 다른 두 필드는 입력과 관련된 문제를 나타낼 수 있습니다. GetSamplingRules를 마지막으로 호출한 시간과 비교하여 LastRuleModification을 확인합니다. 더 최신인 경우 규칙의 새 사본을 가져옵니다. UnprocessedStatistics에는 규칙이 삭제되었거나, 입력의 통계 문서가 너무 오래되었음을 나타내는 오류 또는 권한 오류가 포함될 수 있습니다.
트레이스 세그먼트는 애플리케이션이 처리하는 요청의 JSON 표현입니다. 트레이스 세그먼트는 원 요청에 관한 정보, 애플리케이션이 로컬로 처리하는 작업 정보를 기록하며, 애플리케이션이 AWS 리소스, HTTP API와 SQL 데이터베이스에 대해 적용하는 다운스트림 호출에 대한 정보가 있는 하위 세그먼트 정보도 기록합니다.
세그먼트 문서는 세그먼트 정보를 X-Ray에 전달합니다. 세그먼트 문서는 최대 64kB 까지 가능하며, 하위 세그먼트와 요청이 진행 중임을 표시하는 세그먼트 조각 또는 별도로 전송된 단일 하위 세그먼트를 포함한 전체 세그먼트가 있습니다. PutTraceSegments API를 사용하여 X-Ray에 세그먼트 문서를 직접 보낼 수 있습니다.
X-Ray는 세그먼트 문서를 컴파일하고 처리해 각각 GetTraceSummaries 및 BatchGetTraces API로 액세스할 수 있는 쿼리 가능한 트레이스 요약과 전체 트레이스를 생성합니다. X-Ray로 전송할 수 있는 세그먼트와 하위 세그먼트 외에도, 이 서비스는 하위 세그먼트의 정보를 이용해 추론 세그먼트를 생성하고 전체 트레이스에 추가합니다. 추론된 세그먼트는 추적 맵의 다운스트림 서비스와 리소스를 나타냅니다.
X-Ray는 세그먼트 문서를 위한 JSON 스키마를 제공합니다. 스키마는 1.0.0에서 다운로드할 수 있습니다. xray-segmentdocument-schema-v 스키마에 나열된 필드와 객체는 다음 단원에서 더 자세히 설명합니다.
세그먼트 필드의 서브셋은 필터 표현식에 사용할 수 있도록 X-Ray로 인덱스됩니다. 예를 들어 세그먼트의 user 필드를 고유 식별자로 설정하면, X-Ray 콘솔에서 또는 GetTraceSummaries API를 사용하여 특정 사용자와 관련된 세그먼트를 검색할 수 있습니다. 자세한 정보는 필터 표현식 사용을 참조하세요.
X-Ray SDK로 애플리케이션을 구성하면, SDK는 사용자를 위한 세그먼트 문서를 생성합니다. 세그먼트 문서를 X-Ray에 직접 전송하는 대신, SDK는 로컬 UDP 포트를 이용해 X-Ray 대몬(daemon)에 전송합니다. 자세한 정보는 세그먼트 문서를 X 대몬(daemon)으로 전송을 참조하세요.
세그먼트는 애플리케이션이 처리하는 요청에 대한 트레이싱 정보를 기록합니다. 세그먼트는 기본적으로 이름, ID, 시작 시간 및 트레이스 ID, 요청 종료 시간을 기록합니다.
예 최소 완료 세그먼트
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}다음은 세그먼트에 필수적이거나 조건부 필수인 필드입니다.
참고
특별한 언급이 없는 한 값은 문자열(최대 250자)이어야 합니다.
필수 세그먼트 필드
-
name– 요청을 처리한 서비스의 논리명으로, 200자까지 가능합니다. 예를 들자면 애플리케이션 이름이나 도메인 이름이 있습니다. 이름에는 유니코드 문자, 숫자, 공백 및 다음 기호를 포함할 수 있습니다:_,.,:,/,%,&,#,=,+,\,-,@ -
id– 동일한 트레이스 내 세그먼트에서 고유한 64비트 식별자 (16자리 16진수). -
trace_id– 단일 클라이언트 요청에서 생성된 모든 세그먼트 및 하위 세그먼트를 연결하는 고유한 식별자.X-Ray 트레이스 ID 형식
X-Ray
trace_id는 하이픈으로 구분된 3개의 숫자로 구성됩니다. 예를 들어1-58406520-a006649127e371903a2de979입니다. 여기에는 다음이 포함됩니다.-
버전 번호, 즉
1. -
원래 요청 시간을 Unix 시대 시간으로 나타낸 8자리 16진수
예를 들어, 2016년 12월 1일 오전 10시 (PST) 기준 에포크 타임은 초 또는 16진수로 표시됩니다.
148061520058406520 -
24자리 16진수 트레이스를 위한 전 세계적으로 고유한 96비트 식별자입니다.
참고
이제 X-Ray는 W3C Trace Context 사양을 준수하는 기타 프레임워크를 사용하여 OpenTelemetry 만든 추적
ID를 지원합니다. W3C 추적 ID는 X-Ray로 전송할 때 X-Ray 추적 ID 형식으로 지정해야 합니다. 예를 들어, W3C 추적 ID는 X-Ray로 전송할 1-4efaaf4d-1e8720b39541901950019ee5때와 같은 형식으로4efaaf4d1e8720b39541901950019ee5지정해야 합니다. X-Ray Trace ID에는 Unix 에포크 타임의 원래 요청 타임스탬프가 포함되지만 W3C 추적 ID를 X-Ray 형식으로 전송할 때는 필요하지 않습니다.트레이스 ID 보안
트레이스 ID는 응답 헤더에 표시됩니다. 공격이 향후의 트레이스 ID를 계산하여 해당 ID로 애플리케이션에 요청을 보낼 수 없도록 보안 무작위 알고리즘을 사용하여 트레이스 ID를 생성합니다.
-
-
start_time– 세그먼트가 생성된 시간을 에포크 시간으로 부동 소수점으로 표시한 숫자입니다. 예:1480615200.010또는1.480615200010E9. 소수점 자리는 필요한 만큼 사용하십시오. 가능하다면 마이크로초 해상도를 권장합니다. -
end_time– 세그먼트를 닫은 시간을 표시한 숫자입니다. 예:1480615200.090또는1.480615200090E9.end_time또는in_progress를 지정합니다. -
in_progress– 세그먼트가 시작되었지만 완료되지 않았음을 기록하고자end_time을 지정하는 대신true로 설정한 부울입니다. 애플리케이션이 처리하는 데 오래 걸리는 요청을 수신할 경우 처리 중 세그먼트를 전송하여 요청 수신을 트레이스합니다. 응답이 전송되면 완료 세그먼트를 전송하여 처리 중 세그먼트를 덮어씁니다. 요청 당 완성된 세그먼트 하나만 전송하며, 진행 중인 세그먼트는 1개 또는 0개입니다.
서비스 이름
세그먼트의 name은 해당 세그먼트를 생성한 서비스의 도메인 이름 또는 논리적 이름과 일치해야 합니다. 하지만 이것이 적용되지는 않습니다. PutTraceSegments 허가를 받은 애플리케이션은 어떠한 이름을 사용하여도 세그먼트를 전송할 수 있습니다.
다음은 세그먼트의 선택 사항인 필드입니다.
선택형 세그먼트 필드
-
service– 애플리케이션 정보가 있는 객체입니다.-
version– 요청을 처리한 애플리케이션 버전을 표시하는 문자열입니다.
-
-
user– 요청을 보낸 사용자를 식별하는 문자열입니다. -
origin— 애플리케이션을 실행하는 AWS 리소스 유형.지원되는 값
-
AWS::EC2::Instance– Amazon EC2 인스턴스 -
AWS::ECS::Container– 아마존 ECS 컨테이너 -
AWS::ElasticBeanstalk::Environment– Elastic Beanstalk 환경
애플리케이션에 여러 값을 적용할 수 있는 경우, 가장 구체적인 값을 사용하십시오. 예를 들어 Multicontainer Docker Elastic Beanstalk 환경은 Amazon ECS 컨테이너에서 애플리케이션을 실행하고, 이 컨테이너는 Amazon EC2 인스턴스에서 실행됩니다. 이 경우 환경이 다른 두 리소스의 상위 항목이므로
AWS::ElasticBeanstalk::Environment로 오리진을 설정합니다. -
-
parent_id– 요청이 구성한 애플리케이션에서 나오지 않았을 경우 사용자가 지정한 하위 세그먼트 ID입니다. X-Ray SDK는 다운스트림 HTTP 호출을 위해 상위 하위 세그먼트 ID를 트레이싱 헤더에 추가합니다. 중첩된 하위 세그먼트의 경우, 하나의 하위 세그먼트는 하나의 세그먼트를 포함하거나 상위 세그먼트로서 하위 세그먼트를 포함할 수 있습니다. -
http– 기존 HTTP 요청에 대한 정보가 있는 http 객체입니다. -
aws— 애플리케이션이 요청을 처리한 AWS 리소스에 대한 정보가 포함된 aws객체입니다. -
error,throttle,fault, 및cause– 오류가 발생했음을 표시하며 오류를 유발한 예외 사항에 대한 정보가 담긴 오류 필드입니다. -
annotations– X-Ray가 검색용으로 인덱스할 키-값 페어가 있는 annotations 객체입니다. -
metadata– 세그먼트에 저장할 추가 데이터가 있는 metadata 객체입니다. -
subsegments– subsegment 객체의 배열입니다.
하위 세그먼트를 만들어 AWS SDK로 AWS 서비스 호출한 리소스, 내부 또는 외부 HTTP 웹 API에 대한 호출 또는 SQL 데이터베이스 쿼리를 기록할 수 있습니다. 또한 디버그할 하위 세그먼트를 만들거나 애플리케이션의 코드 블록에 주석을 달 수도 있습니다. 하위 세그먼트는 다른 하위 세그먼트를 포함할 수 있기 때문에, 내부 함수 호출에 대한 메타데이터를 기록한 사용자 지정 하위 세그먼트는 다른 사용자 지정 하위 세그먼트와 다운스트림 호출을 위한 하위 세그먼트를 포함할 수 있습니다.
하위 세그먼트는 다운스트림 직접 호출을 생성한 서비스의 관점에서 해당 호출을 기록합니다. X-Ray는 하위 세그먼트를 사용하여 세그먼트를 전송하지 않고 서비스 그래프에 세그먼트에 대한 항목을 생성하지 않는 다운스트림 서비스를 식별합니다.
하위 세그먼트는 전체 세그먼트 문서에 임베드되거나 독립적으로 전송될 수 있습니다. 하위 세그먼트를 개별적으로 전송하여 장시간 실행되는 요청에 대한 다운스트림 호출을 비동기식으로 트레이스하거나 최대 세그먼트 문서 크기를 초과하지 않도록 합니다.
예 임베디드 하위 세그먼트가 있는 세그먼트
독립 하위 세그먼트는 type의 subsegment과 상위 세그먼트를 식별하는 parent_id를 갖습니다.
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}장기 실행 요청이라면, 진행 중인 세그먼트를 전송하여 요청이 수신되었음을 X-Ray에 알린 후, 하위 세그먼트를 개별적으로 전송해 트레이스할 수 있게 한 다음 원래 요청을 완료해야 합니다.
예 진행 중인 세그먼트
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}예 독립 하위 세그먼트
독립 하위 세그먼트는 type의 subsegment, trace_id와 상위 세그먼트를 식별하는 parent_id를 갖습니다.
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}요청이 완료되면, end_time과 함께 다시 전송해 세그먼트를 닫으십시오. 완료된 세그먼트는 진행 중인 세그먼트를 덮어씁니다.
비동기 워크플로를 유발한 완료 요청에 하위 세그먼트를 개별적으로 전송할 수도 있습니다. 예를 들어 웹 API는 사용자가 요청한 작업을 시작하기 직전에 OK 200 응답을 반환하기도 합니다. 응답이 전송되는 즉시 전체 세그먼트를 X-Ray에 전송하고, 나중에 완료한 작업용 하위 세그먼트를 전송해도 됩니다. 세그먼트의 경우, 하위 세그먼트 조각을 하위 세그먼트가 시작된 기록으로 전송한 다음 다운스트림 호출이 완료되는 즉시 전체 하위 세그먼트로 덮어써도 됩니다.
다음은 하위 세그먼트에 필수적이거나 조건부 필수인 필드입니다.
참고
특별한 언급이 없는 한 값은 최대 250자인 문자열이어야 합니다.
필수 하위 세그먼트 필드
-
id– 동일한 트레이스 내 세그먼트에서 고유한 하위 세그먼트의 64비트 식별자입니다(16자리 16진수). -
name– 하위 세그먼트의 논리명입니다. 다운스트림 직접 호출의 경우에는 리소스나 서비스를 호출한 후 하위 세그먼트의 이름을 지정하십시오. 사용자 지정 하위 세그먼트의 경우에는 이를 구성한 코드 이름(예: 함수 이름)을 정한 후에 하위 세그먼트 이름을 지정하십시오. -
start_time– 하위 세그먼트가 생성된 시간을 에포크 시간으로 밀리초까지 부동 소수점으로 표시한 숫자입니다. 예:1480615200.010또는1.480615200010E9. -
end_time– 하위 세그먼트를 닫은 시간을 표시한 숫자입니다. 예:1480615200.090또는1.480615200090E9.end_time또는in_progress를 지정합니다. -
in_progress– 하위 세그먼트가 시작되었지만 완료되지 않았음을 기록하고자end_time을 지정하는 대신true로 설정한 부울입니다. 다운스트림 요청 당 완성된 하위 세그먼트 하나만 전송하며, 진행 중인 하위 세그먼트는 1개 또는 0개입니다. -
trace_id– 하위 세그먼트의 상위 세그먼트 트레이스 ID입니다. 하위 세그먼트를 개별적으로 전송할 때만 필요합니다.X-Ray 트레이스 ID 형식
X-Ray
trace_id는 하이픈으로 구분된 3개의 숫자로 구성됩니다. 예를 들어1-58406520-a006649127e371903a2de979입니다. 여기에는 다음이 포함됩니다.-
버전 번호, 즉
1. -
원래 요청 시간을 Unix 시대 시간으로 나타낸 8자리 16진수
예를 들어, 2016년 12월 1일 오전 10시 (PST) 기준 에포크 타임은 초 또는 16진수로 표시됩니다.
148061520058406520 -
24자리 16진수 트레이스를 위한 전 세계적으로 고유한 96비트 식별자입니다.
참고
이제 X-Ray는 W3C Trace Context 사양을 준수하는 기타 프레임워크를 사용하여 OpenTelemetry 만든 추적
ID를 지원합니다. W3C 추적 ID는 X-Ray로 전송할 때 X-Ray 추적 ID 형식으로 지정해야 합니다. 예를 들어, W3C 추적 ID는 X-Ray로 전송할 1-4efaaf4d-1e8720b39541901950019ee5때와 같은 형식으로4efaaf4d1e8720b39541901950019ee5지정해야 합니다. X-Ray Trace ID에는 Unix 에포크 타임의 원래 요청 타임스탬프가 포함되지만 W3C 추적 ID를 X-Ray 형식으로 전송할 때는 필요하지 않습니다. -
-
parent_id– 하위 세그먼트의 상위 세그먼트에 적용된 세그먼트 ID입니다. 하위 세그먼트를 개별적으로 전송할 때만 필요합니다. 중첩된 하위 세그먼트의 경우, 하나의 하위 세그먼트는 하나의 세그먼트를 포함하거나 상위 세그먼트로서 하위 세그먼트를 포함할 수 있습니다. -
type–subsegment. 하위 세그먼트를 개별적으로 전송할 때만 필요합니다.
다음은 하위 세그먼트의 선택 사항인 필드입니다.
선택형 하위 세그먼트 필드
-
namespace– AWS SDK 호출의 경우aws이며, 다른 다운스트림 호출의 경우remote입니다. -
http– 발신 HTTP 호출에 대한 정보가 있는 http 객체입니다. -
aws— 애플리케이션에서 호출한 다운스트림 AWS 리소스에 대한 정보가 포함된 aws객체입니다. -
error,throttle,fault, 및cause– 오류가 발생했음을 표시하며 오류를 유발한 예외 사항에 대한 정보가 담긴 오류 필드입니다. -
annotations– X-Ray가 검색용으로 인덱스할 키-값 페어가 있는 annotations 객체입니다. -
metadata– 세그먼트에 저장할 추가 데이터가 있는 metadata 객체입니다. -
subsegments– subsegment 객체의 배열입니다. -
precursor_ids– 이 하위 세그먼트 이전에 완료한 상위 세그먼트를 식별하는 하위 세그먼트 ID 배열입니다.
HTTP 블록을 이용해 애플리케이션이 처리한 HTTP 요청 정보를 (세그먼트에) 기록하거나 애플리케이션이 다운스트림 HTTP API에 적용한 HTTP 요청 정보를 (하위 세그먼트에) 기록합니다. 이 객체에 있는 필드 대부분은 HTTP 요청 및 응답에 있는 정보에 매핑됩니다.
http
모든 필드는 선택 사항입니다.
-
request– 요청에 대한 정보입니다.-
method– 요청 메서드입니다. 예를 들어GET입니다. -
url– 프로토콜, 호스트 이름과 요청 경로에서 컴파일한 요청의 전체 URL입니다. -
user_agent– 요청자의 클라이언트에 있는 사용자 에이전트 문자열입니다. -
client_ip– 요청자의 IP 주소입니다. IP 패킷의Source Address에서, 또는 전달된 요청인 경우X-Forwarded-For헤더에서 찾을 수 있습니다. -
x_forwarded_for– (세그먼트 전용)client_ip를X-Forwarded-For헤더에서 읽었으며 위조 염려가 있어 신뢰할 수 없음을 표시하는 부울입니다. -
traced– (하위 세그먼트 전용) 다운스트림 직접 호출이 다른 트레이스된 서비스를 대상으로 함을 표시하는 부울입니다. 이 필드가true로 설정되면, X-Ray는 다운스트림 서비스가 이 블록을 포함한 하위 세그먼트의id와 일치하는parent_id가 있는 세그먼트를 업로드할 때까지는 트레이스가 깨진 것으로 간주합니다.
-
-
response– 응답에 대한 정보입니다.-
status– 응답의 HTTP 상태를 표시하는 숫자입니다. -
content_length– 응답 본문의 길이를 바이트로 표시하는 숫자입니다.
-
다운스트림 웹 API에 대한 직접 호출을 계측할 때 HTTP 요청 및 응답에 대한 정보를 사용하여 하위 세그먼트를 기록합니다. X-Ray는 하위 세그먼트를 사용하여 원격 API에 대해 추정된 세그먼트를 생성합니다.
예 Amazon EC2에서 실행 중인 애플리케이션이 처리하는 HTTP 호출용 세그먼트
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}예 다운스트림 HTTP 호출에 대한 하위 세그먼트
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}예 다운스트림 HTTP 호출에 대한 추정된 세그먼트
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}세그먼트와 하위 세그먼트는 X-Ray가 필터 표현식용으로 인덱스하는 필드가 하나 이상 있는 annotations 객체를 포함할 수 있습니다. 필드는 문자열, 숫자 또는 부울 값을 가질 수 있습니다(객체 또는 스토리지는 불가). X-Ray가 트레이스당 최대 50개의 주석까지 인덱싱합니다.
예 주석이 있는 HTTP 호출용 세그먼트
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}필터에서 사용하려면 키가 영숫자여야 합니다. 밑줄은 허용됩니다. 다른 기호와 공백은 허용되지 않습니다.
세그먼트와 하위 세그먼트는 객체와 어레이를 포함한 모든 종류의 값을 가진 필드가 하나 이상 있는 metadata 객체를 포함할 수 있습니다. X-Ray는 메타데이터를 인덱싱하지 않으며, 세그먼트 문서가 최대 크기(64kB)를 초과하지 않는 이상 값은 크기가 제한되지 않습니다. 메타데이터는 BatchGetTraces API가 반환하는 전체 세그먼트 문서에서 확인할 수 있습니다. 로 시작하는 필드 키 (다음 예시) 는 AWS제공된 SDK 및 debug 클라이언트에서 사용하도록 AWS. 예약되어 있습니다.
예 메타데이터가 포함된 사용자 지정 하위 세그먼트
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}세그먼트의 경우 aws 객체에는 애플리케이션을 실행하는 리소스에 대한 정보가 포함됩니다. 여러 필드를 단일 리소스를 적용할 수 있습니다. 예를 들어 Elastic BeanStalk의 멀티컨테이너 Docker 환경에서 실행하는 애플리케이션은 Amazon EC2 인스턴스, 인스턴스를 실행하는 Amazon ECS 컨테이너와 Elastic Beanstalk 환경 자체에 대한 정보를 포함할 수 있습니다.
aws (세그먼트)
모든 필드는 선택 사항입니다.
-
account_id– 애플리케이션이 세그먼트를 다른 AWS 계정에 전송한다면, 애플리케이션을 실행하는 계정 ID를 기록합니다. -
cloudwatch_logs— 단일 CloudWatch 로그 그룹을 설명하는 개체 배열.-
log_group— CloudWatch 로그 그룹 이름. -
arn— CloudWatch 로그 그룹 ARN.
-
-
ec2– EC2 인스턴스에 대한 정보.-
instance_id– EC2 인스턴스의 인스턴스 ID. -
instance_size– EC2 인스턴스 유형. -
ami_id– Amazon Machine Image ID. -
availability_zone– 인스턴스가 실행 중인 가용 영역.
-
-
ecs– Amazon ECS 컨테이너 관련 정보.-
container– 컨테이너의 호스트 이름. -
container_id– 컨테이너의 전체 컨테이너 ID. -
container_arn– ECS 컨테이너 인스턴스의 ARN.
-
-
eks– Amazon EKS 클러스터에 대한 정보.-
pod— EKS 포드의 호스트 이름. -
cluster_name– EKS 클러스터 이름. -
container_id– 컨테이너의 전체 컨테이너 ID.
-
-
elastic_beanstalk– Elastic Beanstalk 환경에 대한 정보 이 정보는 최신 Elastic Beanstalk 플랫폼의/var/elasticbeanstalk/xray/environment.conf파일에서 확인할 수 있습니다.-
environment_name– 환경의 이름입니다. -
version_label– 요청을 처리한 인스턴스에 현재 배포된 애플리케이션 버전 이름. -
deployment_id– 요청을 처리한 인스턴스에 대해 마지막으로 성공한 배포의 ID를 표시하는 숫자.
-
-
xray– 사용된 계측기의 유형 및 버전에 대한 메타데이터.-
auto_instrumentation– 자동 계측 사용 여부를 나타내는 부울 (예: Java 에이전트). -
sdk_version– 사용 중인 SDK 또는 에이전트의 버전. -
sdk– SDK의 유형입니다.
-
예 AWS 플러그인으로 차단
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
서브세그먼트의 경우 애플리케이션이 액세스하는 AWS 서비스 및 리소스에 대한 정보를 기록하세요. X-Ray는 이 정보를 사용하여 서비스 맵에 있는 다운스트림 서비스를 나타내는 추론 세그먼트를 생성합니다.
aws (하위 세그먼트)
모든 필드는 선택 사항입니다.
-
operation– AWS 서비스 나 리소스를 상대로 호출한 API 작업의 이름입니다. -
account_id— 애플리케이션이 다른 계정의 리소스에 액세스하거나 세그먼트를 다른 계정으로 전송하는 경우 애플리케이션이 액세스한 AWS 리소스를 소유한 계정의 ID를 기록하십시오. -
region– 리소스가 애플리케이션과 다른 리전에 있다면, 리전을 기록합니다. 예를 들어us-west-2입니다. -
request_id– 요청에 대한 고유 식별자입니다. -
queue_url– 대기열 작업에서 대기열의 URL을 의미합니다. -
table_name– DynamoDB 테이블의 작업에서 테이블의 이름을 의미합니다.
예 항목을 저장하기 위한 DynamoDB 직접 호출에 대한 하위 세그먼트
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}오류가 발생하는 경우, 사용자는 해당 오류와 오류를 일으킨 예외에 대한 정보를 기록할 수 있습니다. 애플리케이션이 사용자에게 오류를 반환하면 세그먼트에, 다운스트림 호출이 오류를 반환하면 하위 세그먼트에 오류를 기록합니다.
오류 유형
다음 필드 중 하나 이상을 true로 설정해 오류가 발생했음을 표시합니다. 복합 오류의 경우 여러 유형을 적용할 수 있습니다. 예를 들어 다운스트림 호출에서 발생한 429 Too Many
Requests 오류는 애플리케이션이 500 Internal Server Error를 반환하게 만들기도 하며, 이 경우 3가지 유형이 모두 적용됩니다.
-
error– 클라이언트 오류가 발생했음을 나타내는 부울입니다(응답 상태 코드가 4XX 클라이언트 오류임). -
throttle– 요청이 제한되었음을 나타내는 부울입니다(응답 상태 코드가 429 요청 과다임). -
fault– 서버 오류가 발생했음을 나타내는 부울입니다(응답 상태 코드가 5XX 서버 오류임).
세그먼트나 하위 세그먼트에 원인 오브젝트를 포함해 오류의 원인을 표시합니다.
cause
원인은 16자 예외 ID나, 다음 필드를 포함한 객체가 될 수 있습니다.
-
working_directory– 예외 발생 시의 작업 디렉터리 전체 경로입니다. -
paths– 예외 발생 시 사용 중인 라이브러리나 모듈의 경로 배열입니다. -
exceptions– 예외 객체 배열입니다.
하나 이상의 예외 객체에 있는 오류에 대한 세부 정보를 포함합니다.
exception
모든 필드는 선택 사항입니다.
-
id– 동일한 트레이스 내 세그먼트에서 고유한 예외의 64비트 식별자입니다(16자리 16진수). -
message– 예외 메시지입니다. -
type– 예외 유형입니다. -
remote– 다운스트림 서비스가 반환한 오류 때문에 예외가 발생했음을 나타내는 부울입니다. -
truncated–stack에서 제외된 스택 숫자를 나타내는 정수입니다. -
skipped– 이 예외와 그 하위 항목, 즉 해당 예외가 유발한 예외 간에 건너 뛴 예외 숫자를 표시하는 정수입니다. -
cause– 예외의 상위 항목, 즉 해당 예외를 유발한 예외의 ID입니다. -
stack– stackFrame 객체 배열입니다.
가능하다면, stackFrame 객체의 호출 스택에 대한 정보를 기록합니다.
stackFrame
모든 필드는 선택 사항입니다.
-
path– 파일의 상대 경로입니다. -
line– 파일의 라인입니다. -
label– 함수 또는 메서드 이름입니다.
애플리케이션이 SQL 데이터베이스에 만드는 쿼리에 대한 하위 세그먼트를 만들 수 있습니다.
sql
모든 필드는 선택 사항입니다.
-
connection_string– URL 연결 문자열을 사용하지 않는 SQL 서버나 다른 데이터베이스 연결의 경우에는 암호를 제외한 연결 문자열을 기록합니다. -
url– URL 연결 문자열을 사용하는 데이터베이스 연결의 경우에는 암호를 제외한 URL을 기록합니다. -
sanitized_query– 사용자가 값을 제거하거나 자리 표시자로 대체한 데이터베이스 쿼리입니다. -
database_type– 데이터베이스 엔진의 이름입니다. -
database_version– 데이터베이스 엔진의 버전 번호입니다. -
driver_version– 애플리케이션이 사용하는 데이터베이스 엔진 드라이버의 이름과 버전 번호입니다. -
user– 데이터베이스 사용자 이름입니다. -
preparation– 쿼리가PreparedCall을 사용한다면call이고, 쿼리가PreparedStatement를 사용한다면statement입니다.
예 SQL 쿼리가 있는 하위 세그먼트
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}