AWS X-Ray 세그먼트 문서

필수 세그먼트 필드

• 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진수로 표시됩니다. 1480615200 58406520

  • 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개입니다.

선택형 세그먼트 필드

• 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 객체의 배열입니다.

필수 하위 세그먼트 필드

• 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진수로 표시됩니다. 1480615200 58406520

  • 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

모든 필드는 선택 사항입니다.

• 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 – 응답 본문의 길이를 바이트로 표시하는 숫자입니다.

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 (하위 세그먼트)

모든 필드는 선택 사항입니다.

• operation— or 리소스에 대해 호출된 API 작업의 이름. AWS 서비스

• account_id— 애플리케이션이 다른 계정의 리소스에 액세스하거나 세그먼트를 다른 계정으로 전송하는 경우 애플리케이션이 액세스한 AWS 리소스를 소유한 계정의 ID를 기록해 두십시오.

• region – 리소스가 애플리케이션과 다른 리전에 있다면, 리전을 기록합니다. 예를 들어 us-west-2입니다.

• request_id – 요청에 대한 고유 식별자입니다.

• queue_url – 대기열 작업에서 대기열의 URL을 의미합니다.

• table_name – DynamoDB 테이블의 작업에서 테이블의 이름을 의미합니다.

오류 유형

다음 필드 중 하나 이상을 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

모든 필드는 선택 사항입니다.

• path – 파일의 상대 경로입니다.

• line – 파일의 라인입니다.

• label – 함수 또는 메서드 이름입니다.

sql

모든 필드는 선택 사항입니다.

• connection_string – URL 연결 문자열을 사용하지 않는 SQL 서버나 다른 데이터베이스 연결의 경우에는 암호를 제외한 연결 문자열을 기록합니다.

• url – URL 연결 문자열을 사용하는 데이터베이스 연결의 경우에는 암호를 제외한 URL을 기록합니다.

• sanitized_query – 사용자가 값을 제거하거나 자리 표시자로 대체한 데이터베이스 쿼리입니다.

• database_type – 데이터베이스 엔진의 이름입니다.

• database_version – 데이터베이스 엔진의 버전 번호입니다.

• driver_version – 애플리케이션이 사용하는 데이터베이스 엔진 드라이버의 이름과 버전 번호입니다.

• user – 데이터베이스 사용자 이름입니다.

• preparation – 쿼리가 PreparedCall을 사용한다면 call이고, 쿼리가 PreparedStatement를 사용한다면 statement입니다.