1. 목적
본 문서는 YouRouter 데이터 추적 기능의 규범적 동작과 사용 요구사항을 정의합니다. 목표는 Tencent Cloud Application Performance Management(APM)의 분산 추적 데이터를 조회해 단일 요청을 중심으로 감사, 대조 및 문제 해결을 할 수 있게 하는 것입니다.2. 용어
본 문서의 MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL은 RFC 2119에서 정의한 요구 수준을 나타냅니다.- Trace ID: Tencent Cloud APM에서 분산 추적을 검색하는 데 사용되는 고유 식별자입니다.
- APM: Tencent Cloud Application Performance Management입니다.
- Client: 서비스, SDK, 스크립트 등 YouRouter API를 호출하는 모든 클라이언트입니다.
- Trace Retention Window: APM에서 Trace를 검색할 수 있는 시간 창입니다. 본 문서에서는 72시간(3일)입니다.
3. 프로토콜
HTTP 응답 헤더를 통해 Trace ID를 전달해야 한다는 요구 외에, 본 문서는 하위 전송 구현의 세부 사항을 강제하지 않습니다.4. Trace ID 응답 요구사항
4.1 헤더 정의
YouRouter는 모든 성공적인 API 응답에 다음 응답 헤더를 반드시(MUST) 포함해야 합니다.- 헤더 이름:
X-Yourouter-Trace-Id - 헤더 값:
<trace_id>— 해당 요청의 추적 레코드를 식별하는 비어 있지 않은 문자열
4.2 누락 처리
- YouRouter가 통제할 수 없는 요인으로 Trace를 생성하거나 반환할 수 없는 경우, YouRouter는 해당 응답 헤더를 생략할 수 있습니다(MAY).
X-Yourouter-Trace-Id가 없는 경우, Client는 해당 요청을 추적 불가로 간주해야 하며(MUST), Tencent Cloud APM에서 해당 요청에 대한 추적 기반 검증에 의존해서는 안 됩니다(MUST NOT).
5. 보존 기간
5.1 보존 창
Tencent Cloud APM의 Trace 데이터는 72시간(3일) 동안 보존되며 검색할 수 있습니다. 이 시간 창을 초과한 Trace는 검색 불가 또는 사용 불가로 간주해야 합니다(SHALL).5.2 시간 제한 요구사항
APM Trace 데이터에 의존하는 모든 감사, 대조, 증거 수집 또는 문제 해결은 요청 발생 후 72시간 이내에 완료되어야 합니다(MUST). 72시간 후 Trace를 찾을 수 없는 경우, 사용자는 이를 시스템 장애 또는 데이터 불일치의 증거로 간주해서는 안 됩니다(MUST NOT).6. Client 지속성 요구사항
6.1 즉시 지속화(필수)
Client는 응답을 받은 후X-Yourouter-Trace-Id 값을 즉시 추출하여 지속화해야 합니다(MUST).
지속화 대상에는 애플리케이션 로그, 구조화된 로그 파이프라인, 데이터베이스, 티켓 시스템, 알림 메시지 본문 또는 관측 가능성 플랫폼의 사용자 정의 필드 등이 포함될 수 있습니다(MAY).
6.2 최소 연관 필드 집합
후속 연관 및 문제 해결을 위해 Client는 Trace ID와 함께 다음 필드를 함께 지속화하는 것이 좋습니다(SHOULD).- 내부 request id 등 클라이언트 요청 식별자
- 최소 초 단위까지의 요청 타임스탬프
- YouRouter API 경로 또는 작업 이름
- HTTP 상태 코드 또는 동등한 성공·실패 표시
7. APM 조회 절차
7.1 필수 절차
보존 창 내에서 사용자는 다음 단계에 따라 Trace를 검색해야 합니다(MUST).- 응답 헤더에서
X-Yourouter-Trace-Id값을 가져옵니다. - Tencent Cloud APM 콘솔을 엽니다.
- Trace Search / Distributed Tracing 페이지로 이동합니다. 메뉴 이름은 APM 버전에 따라 다를 수 있습니다.
- Trace ID로 검색하여 해당 Trace 상세를 엽니다.
- 종단 간 지연, 의존성 그래프, 오류 또는 재시도 정보, YouRouter의 상위 서비스 호출을 확인합니다.
7.2 조회 실패 처리
72시간 이내에 해당 Trace를 찾을 수 없는 경우, 사용자는 먼저 다음을 확인하는 것이 좋습니다(SHOULD).- Trace ID가 잘리거나 불필요한 공백 없이 정확히 복사되었는지
- APM 샘플링 설정으로 인해 일부 요청에 Trace가 생성되지 않았는지
- 현재 시간 범위가 요청 발생 시각을 포함하는지
8. 귀속 및 검증
8.1 귀속 원칙
Trace 상세 페이지에서 사용자는 YouRouter가 상위 서비스로 보낸 아웃바운드 호출을 주요 검증 증거로 삼아야 합니다(SHALL). 여기에는 다음이 포함됩니다.- 실제 라우팅 대상을 확인하기 위한 대상 Host, Endpoint 또는 URL
- 요청 결과와 동작을 확인하기 위한 지연, 상태 코드 및 오류 정보
8.2 대상이 아닌 콘텐츠
본 문서는 고정된 span 태그 이름, 속성 키 이름 또는 내부 라벨 규약을 요구하거나 가정해서는 안 됩니다(MUST NOT). 구현과 문서는 이러한 내부 필드를 공개 인터페이스로 의존해서는 안 됩니다(SHOULD NOT).9. 보안 및 개인정보
Client는 프롬프트나 개인 데이터 등 민감한 요청 콘텐츠의 기록을 피하는 것이 좋습니다(SHOULD). Client는 Trace ID와 감사·문제 해결에 필요한 최소한의 연관 정보만 저장하는 것이 좋습니다(SHOULD).10. 일관성 요구사항
다음 조건이 충족되면 본 규격을 준수한 것으로 간주할 수 있습니다.- YouRouter가 성공 응답에
X-Yourouter-Trace-Id를 반환함(제4.1절) - 문서에 72시간 Trace 보존 창이 명시되고 이행됨(제5절)
- 문서에 Client의 Trace ID 즉시 지속화 및 필요한 조회 절차가 명시됨(제6절 및 제7절)