AWS X-Ray 세그먼트 문서 - AWS X-Ray
세그먼트 필드하위 세그먼트HTTP 요청 데이터주석메타데이터AWS 리소스 데이터오류 및 예외SQL 쿼리

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS X-Ray 세그먼트 문서

트레이스 세그먼트는 애플리케이션이 처리하는 요청의 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진수로 표시됩니다. 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개입니다.

서비스 이름

세그먼트의 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진수로 표시됩니다. 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 요청 데이터

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 리소스 데이터

세그먼트의 경우 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— or 리소스에 대해 호출된 API 작업의 이름. AWS 서비스

  • 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 데이터베이스에 만드는 쿼리에 대한 하위 세그먼트를 만들 수 있습니다.

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=?;"
  }
}