Jaeger APM 트레이스 탐색

기본 접근성

기본 접근성은 설정된 Jaeger Query API의 서비스 조회로 확인하며 메트릭 소스나 빈 서비스 목록에 의존하지 않습니다. 잘못된 설정은 미확인, 확인된 API 접근 실패는 접근 불가로 표시합니다. 트레이스와 워크로드 상태는 도메인 증거입니다.

TLS

TLS 필드는 보안 > TLS 구역에서 설정합니다. 연결 주소와 인증 자격 증명의 기존 필드·저장 값·기본값·민감 정보 처리·검증 방식은 유지합니다.

사설 CA로 서명한 Jaeger 엔드포인트를 검증하려면 tls_ca_cert에 PEM 인증서를 입력합니다. 기존에 저장한 ca_certificate 값도 계속 사용됩니다. tls_server_name은 인증서의 DNS 이름을 지정하며, 상호 TLS가 필요하면 tls_client_cert와 tls_client_key를 함께 입력합니다. tls_insecure_skip_verify는 서버 인증서 검증을 생략하며 기본값은 꺼짐입니다.

Jaeger Enterprise 플러그인은 Konduo 리소스 하나를 Jaeger Query HTTP 엔드포인트 하나에 연결한다. 운영자는 관찰된 서비스에서 오퍼레이션과 제한된 트레이스 검색으로 이동하고, 개별 트레이스를 스팬 타임라인으로 확인할 수 있다. 기준 호환 대상은 Jaeger v2.20.0 Query API v3이다.

이 화면은 애플리케이션 트레이스 근거를 보여 준다. Prometheus 메트릭 수집, 서비스 단위 백분위수나 전체 오류율 계산, 샘플링 관리는 제공하지 않으며 기존 메트릭 대시보드와 경고 흐름을 바꾸지 않는다.

리소스 매니저 계약에 필요한 표준 Prometheus 연결 메타데이터는 manifest에 유지한다. 이는 호환성 메타데이터이며 Prometheus가 APM 조회 의존성이 된다는 뜻이 아니다. 트레이스 화면은 설정한 Jaeger 엔드포인트만 호출하며 SPM, 메트릭 임곗값 또는 이상 규칙을 추가하지 않는다.

빠른 시작

1. Konduo 플러그인 프로세스에서 Jaeger Query HTTP 서비스에 연결할 수 있는지 확인한다. Jaeger all-in-one의 일반적인 HTTP 포트는 16686이다.
2. Jaeger 리소스를 추가하고 query_endpoint에 Query 서비스 기본 URL을 입력한다.
3. 인증 방식으로 none, bearer, basic 중 하나를 선택한다. 자격 증명을 전송할 때는 HTTPS를 사용하고, 사설 CA가 필요하면 PEM을 ca_certificate에 입력한다.
4. 리소스를 저장하고 연결 검사를 실행한다.
5. 서비스에서 관찰된 애플리케이션 서비스를 고른 뒤 오퍼레이션 또는 트레이스 검색으로 이동한다. 트레이스 행을 선택하면 타임라인이 열린다.

연결 검사 성공은 설정한 Query API가 응답했다는 뜻이다. 애플리케이션이 정상이거나 현재 스팬을 전송하고 보관 중이라는 뜻은 아니다.

설정

설정	기본값과 제한	설명
query_endpoint	http://localhost:16686	필수 Query 서비스 기본 URL이다. 개발 기본값을 플러그인 런타임에서 도달 가능한 주소로 바꾼다.
auth_type	none	none, bearer, basic 중 하나다.
bearer_token	비어 있음	민감한 Bearer 자격 증명이다.
username	비어 있음	Basic 인증 사용자 이름이다.
password	비어 있음	민감한 Basic 인증 비밀번호다.
ca_certificate	비어 있음	사설 HTTPS 엔드포인트를 검증할 PEM CA다.
timeout_seconds	10, 1~60	Query API 요청 하나의 제한 시간이다.

저장된 리소스 설정이 연결 정보의 기준이다. 검색 요청으로 대상 엔드포인트나 자격 증명을 바꿀 수 없다. 실패 응답은 정제된 오류만 제공하며 토큰과 비밀번호를 포함하지 않는다.

트레이스 탐색

서비스는 Jaeger의 보관된 트레이스 인덱스에 있는 서비스 이름을 표시한다. 서비스를 선택하면 다음 화면의 범위를 좁힐 수 있다. 애플리케이션이 목록에 없다는 사실만으로 애플리케이션 중단을 판단하면 안 된다. 보관된 샘플 스팬에 해당 service.name이 없을 수 있다.

오퍼레이션은 선택한 서비스에 대해 Jaeger가 반환한 오퍼레이션 이름과 스팬 종류를 표시한다. 더 구체적인 결과가 필요하면 오퍼레이션에서 트레이스 검색으로 이동한다.

트레이스 검색은 다음 필터를 지원한다.

• 서비스와 선택형 오퍼레이션
• 기본 60분, 최대 10,080분의 조회 기간
• 또는 함께 입력하며 같은 최대 7일 범위를 적용하는 RFC 3339 시작·종료 시각
• 밀리초 단위 최소·최대 지속 시간
• 기본 50, 최대 200의 결과 제한
• 최대 16 KiB, 32개 항목의 문자열 키·값 평면 JSON 속성 객체
• 오류만 보기

표에는 트레이스 ID, 루트 서비스와 오퍼레이션, 시작 시각, 트레이스 지속 시간, 스팬 수, 오류 스팬 수, 부모 누락 스팬 수, 관찰된 서비스가 표시된다. 트레이스 지속 시간은 반환된 트레이스에서 가장 이른 스팬 시작부터 가장 늦은 스팬 종료까지의 구간이다. Jaeger의 지속 시간 검색은 요청한 범위에 맞는 스팬이 하나 이상 있는 트레이스를 찾는다. 서비스 백분위수를 검색하는 기능이 아니다.

결과 제한은 Jaeger의 searchDepth로 전달된다. 일부 저장소는 검색 깊이를 근사 제한으로 처리할 수 있다. 오류만 보기는 Jaeger가 제한된 후보를 반환한 뒤 플러그인이 적용하므로 후보 범위 밖의 오류 트레이스는 검사하지 않는다. 결과 메타데이터에서 제한 도달 여부와 후처리 적용 여부를 확인할 수 있다.

트레이스 상세는 선택한 트레이스를 상대 시작 오프셋 순서의 타임라인으로 표시한다. 각 행에는 부모 깊이, 서비스, 오퍼레이션, 지속 시간, 스팬 종류, OTLP 상태, 오류 또는 부모 누락 표식이 나온다. 속성과 이벤트는 크기를 제한하고 민감한 정보를 가린다. 부모 누락 표식은 반환된 트레이스에 부모 스팬이 없다는 뜻이다. 샘플링, 수집, 보관 또는 불완전한 내보내기가 원인일 수 있다.

트레이스 상세는 스팬이 5,000개를 넘는 트레이스를 거부하고 전체 이벤트를 최대 1,000개까지 유지한다. 스팬당 속성은 최대 64개, 이벤트당 속성은 최대 32개이며 속성 문자열 값은 512바이트로 제한한다. 요약에서 이벤트 잘림 여부를 확인할 수 있다. 워터폴은 기본적으로 정규화한 처음 200개 스팬을 표시하고, 제한된 스팬 표에서 각 행의 세부 정보를 확인할 수 있다.

트레이스 ID를 이미 알고 있으면 트레이스 ID에 16자 또는 32자 16진수 값을 입력해 검색 없이 같은 상세 화면을 연다.

근거 해석

화면의 범위는 현재 필터로 반환된 보관 트레이스다. 샘플링, 수집 손실, Jaeger 보관 기간, 저장소 검색 기능, 조회 제한과 시간 필터 때문에 애플리케이션 트래픽이 제외될 수 있다. 반환 개수를 전체 요청률·오류율로 해석하거나 반환 지속 시간을 전체 지연 시간 분포로 해석하지 않는다.

오류 스팬은 OTLP 상태가 명시적으로 ERROR인 스팬이다. 플러그인은 하위 서비스의 오류를 다른 서비스 스팬으로 전파해 계산하지 않는다. 타임라인과 정제된 이벤트를 보고 어느 계측 컴포넌트가 상태를 설정했는지 확인한다.

Konduo는 리소스 인스턴스와 읽기 경로 단위로 이 화면의 접근을 제어한다. 플러그인 안에는 Jaeger 서비스별 허용 목록이 없다. Jaeger 리소스를 읽을 수 있는 사용자는 설정된 Jaeger 계정이 조회할 수 있는 서비스와 트레이스 근거를 조회할 수 있다. 서비스 단위 분리가 필요하면 Jaeger 엔드포인트나 자격 증명을 분리한다. 애플리케이션 속성에는 민감한 업무 맥락이 있을 수 있으므로 리소스 접근도 제한한다.

문제 해결

증상	확인 사항
연결 검사 실패	저장된 기본 URL, 네트워크 경로, HTTPS 인증서 체인, 인증 방식, 제한 시간을 확인한다. 엔드포인트가 Query API v3를 제공해야 한다.
서비스가 비어 있음	애플리케이션이 OTLP 트레이스를 Jaeger로 전송하는지, 샘플링이 스팬을 보관하는지, 보관 기간이 지나지 않았는지, service.name이 있는지 확인한다.
오퍼레이션이 비어 있음	Jaeger 목록과 정확히 같은 서비스를 선택했는지, 보관된 스팬에 오퍼레이션 이름이 있는지 확인한다.
트레이스 검색 결과가 없음	시간 범위를 넓히고 속성·지속 시간 필터를 제거한 뒤 검색 제한 도달 여부를 확인한다.
트레이스 ID가 거부됨	구분자나 URL 없이 16자 또는 32자 16진수 트레이스 ID만 입력한다.
예상한 오류 트레이스가 없음	오류만 보기를 끄고 필요하면 제한을 늘린 뒤 Jaeger 후보에 트레이스가 포함되는지 확인한다.
부모 누락 표식이 있음	샘플링과 collector/export 완전성을 확인한다. 상세 응답에 없는 부모를 플러그인이 만들어 내지 않는다.
속성이 가려짐	민감한 형태의 키와 값은 의도적으로 가리며 큰 속성·이벤트에는 크기 제한을 적용한다.