이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Trace 도구 사용

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

Trace 도구란 무엇인가요?

Trace는 Apigee Edge에서 실행되는 API 프록시의 문제를 해결하고 모니터링하는 도구입니다. Trace를 사용하면 API 프록시 흐름을 통해 각 단계의 세부정보를 프로브할 수 있습니다.

Trace 도구에 대해 소개하는 이 동영상을 시청하세요.

Trace 사용 방법

Trace는 사용이 간편합니다. 트레이스 세션을 시작한 다음 Edge 플랫폼에 API를 호출하고 결과를 읽습니다.

아래 설명에 따라 API 프록시 페이지에 액세스합니다.
에지

Edge UI를 사용하여 API 프록시 페이지에 액세스하려면 다음 안내를 따르세요.
1. apigee.com/edge에 로그인합니다.
2. 왼쪽 탐색 메뉴에서 개발 > API 프록시를 선택합니다.
Classic Edge (Private Cloud)

참고: Classic Edge UI는 Private Cloud용 Edge에서만 사용할 수 있습니다.

기본 Edge UI를 사용하여 API 프록시 페이지에 액세스하려면 다음 안내를 따르세요.
1. http://ms-ip:9000에 로그인합니다. 여기서 ms-ip은 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.
2. 상단 탐색 메뉴에서 API > API 프록시를 선택합니다.
API 프록시 페이지에서 API 프록시를 선택합니다.
추적할 API가 배포되었는지 확인하세요.
Trace를 클릭하여 Trace 도구 뷰로 이동합니다.
추적에 배포 드롭다운 메뉴를 사용하여 추적할 배포 환경 및 프록시 버전을 선택합니다.
추적 세션 시작을 클릭합니다. Trace 세션이 활성화되면 API 프록시가 처리 파이프라인의 각 단계에 대한 세부정보를 기록합니다. Trace 세션이 실행되는 동안 실시간 트래픽에서 메시지와 문맥 데이터가 캡처됩니다.
프록시를 통해 전달되는 실시간 트래픽이 없으면 API에 요청을 보내기만 하면 됩니다. curl, Postman 또는 익숙한 도구와 같이 요청을 전송하려는 모든 도구를 사용할 수 있습니다. 또는 Trace 도구 자체에서 직접 요청을 보낼 수도 있습니다. URL을 입력하고 보내기를 클릭하면 됩니다. 참고: Trace 도구에서 GET 요청만 보낼 수 있으며 POST 요청은 보낼 수 없습니다.

참고: Trace 세션 1개는 선택한 API 프록시를 통해 메시지 프로세서당 요청/응답 트랜잭션을 10개까지 지원할 수 있습니다. Edge 클라우드에서는 2개의 메시지 프로세서가 트래픽을 처리하고 20개의 요청/응답 트랜잭션이 지원됩니다. 트레이스 세션을 수동으로 중지하지 않으면 10분 후에 자동으로 중지됩니다.
충분한 수의 요청을 캡처했으면 Stop Trace Session을 클릭합니다.
캡처된 요청/응답 트랜잭션 목록이 왼쪽 메뉴에 표시됩니다. 원하는 거래를 클릭하여 자세한 결과를 확인합니다.

trace를 읽는 방법

trace 도구에는 트랜잭션 맵과 단계 세부정보라는 2가지 주요 부분이 있습니다.

트랜잭션 지도는 아이콘을 사용하여 정책 실행, 조건부 단계, 전환을 포함하여 API 프록시 트랜잭션 중에 발생하는 각 주요 단계를 표시합니다. 아이콘 위로 마우스를 가져가면 요약 정보가 표시됩니다. 요청 흐름 단계는 트랜잭션 지도 상단에 표시되고 응답 흐름 단계는 하단에 표시됩니다.
도구의 단계 세부정보 섹션에는 설정되거나 읽은 변수, 요청 및 응답 헤더 등 프록시의 내부 처리에 대한 정보가 표시됩니다. 아이콘을 클릭하면 해당 단계의 단계 세부정보가 표시됩니다.

다음은 주요 프록시 처리 세그먼트 라벨이 지정된 샘플 trace 도구 맵입니다.

Trace 도구의 트랜잭션 지도

트랜잭션 지도 범례

다음 표에서는 트랜잭션 지도에 표시되는 아이콘의 인텐트를 설명합니다. 이 아이콘은 프록시 흐름 전반에서 각각의 주요 처리 단계를 표시합니다.

트랜잭션 지도 아이콘

	API 프록시의 ProxyEndpoint로 요청을 전송하는 클라이언트 앱입니다.
	원은 프록시 흐름에서 전환 엔드포인트를 표시합니다. 즉, 클라이언트에서 요청이 수신될 때, 요청이 대상에 도착할 때, 응답이 대상에서 되돌아올 때, 응답이 클라이언트에 다시 반환될 때 이 요청에 포함됩니다.
	큰 막대는 API 프록시 흐름에서 흐름 세그먼트의 시작을 나타냅니다. 흐름 세그먼트는 ProxyEndpoint 요청, TargetEndpoint 요청, TargetEndpoint 응답, ProxyEndpoint 응답입니다. 세그먼트에는 PreFlow, 조건부 흐름, PostFlow가 포함됩니다. 자세한 내용은 흐름 구성을 참조하세요.
	애널리틱스 작업이 백그라운드에서 발생했음을 나타냅니다.
	true로 평가되는 조건부 흐름입니다. 조건부 흐름 소개는 흐름 구성을 참조하세요. 일부 조건은 Edge에서 생성됩니다. 예를 들어 다음은 Edge가 ProxyEndpoint에서 오류가 발생했는지 확인하는 데 사용하는 표현식입니다. `((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))`
	false로 평가되는 조건부 흐름입니다. 조건부 흐름 소개는 흐름 구성을 참조하세요. 일부 조건은 Edge에서 생성됩니다. 예를 들어 다음은 Edge가 TargetEndpoint에서 오류가 발생했는지 확인하는 데 사용하는 표현식입니다. `(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))`
	정책 각 정책 유형에는 고유한 아이콘이 있습니다. 이는 AssignMessage 정책용입니다. 이 아이콘을 통해 정책이 올바른 순서로 실행되었는지 여부와 정책의 성공 여부를 확인할 수 있습니다. 정책 아이콘을 클릭하여 실행 결과 및 예상 결과를 확인할 수 있습니다. 예를 들어 메시지가 제대로 변환되었는지 또는 캐시되고 있는지 확인할 수 있습니다. 정책이 올바르게 실행되면 체크표시로 명확하게 표시됩니다. 오류가 발생하면 아이콘에 빨간색 느낌표가 표시됩니다. 팁:도움말 또는 시간 행에 주의하여 정책이 예상보다 오래 걸리는지 확인하세요.
	백엔드 대상이 Node.js 애플리케이션인 경우 표시됩니다. Apigee Edge의 Node.js 개요를 참조하세요.
	API 프록시에서 호출하는 백엔드 대상입니다.
	시간 행은 처리를 완료하는 데 걸리는 시간(밀리초)을 나타냅니다. 경과된 시간 세그먼트를 비교하면 API 호출 속도를 저하시키는, 가장 오래 걸리는 정책을 격리하는 데 도움이 됩니다.
	Epsilon은 1밀리초보다 작은 시간 범위를 나타냅니다.
	사용 중지되었습니다. 정책이 사용 중지되면 정책 아이콘에 표시됩니다. 정책은 공개 API로 사용 중지할 수 있습니다. API 프록시 구성 참조를 확인하세요.
	오류가 발생했습니다. 정책 단계 조건이 false로 평가될 때(흐름 변수 및 조건 참조) 정책 아이콘에 표시되거나 RaiseFault 정책이 실행될 때 RaiseFault 정책 아이콘에 표시됩니다.
	건너뛰었습니다. 단계 조건이 false로 평가되어 정책이 실행되지 않은 경우 정책 아이콘에 표시됩니다. 자세한 내용은 흐름 변수 및 조건을 참조하세요.

단계 세부정보 이해하기

도구의 단계 세부정보 부분은 각 처리 단계에서 프록시 상태에 대해 많은 정보를 제공합니다. 단계 세부정보에서 제공하는 정보는 다음과 같습니다. trace 도구의 아이콘을 클릭하여 선택한 단계의 세부정보를 확인하거나, 다음/뒤로 버튼을 사용하여 한 단계에서 다른 단계로 이동합니다.

단계 세부정보	설명
프록시 엔드포인트	실행을 위해 선택된 ProxyEndpoint 흐름을 나타냅니다. API 프록시에는 여러 개의 명명된 프록시 엔드포인트가 있을 수 있습니다.
변수	정책에서 읽고 값을 할당한 흐름 변수를 나열합니다. 흐름 변수로 프록시 상태 관리도 참조하세요. 참고: 등호(=)는 변수에 할당된 값을 나타냅니다. 줄이 그어진 등호(≠)는 읽기 전용이거나 정책 실행에 오류가 발생해 변수에 값이 할당되지 않은 것을 나타냅니다. 빈 필드는 변수 값을 읽었음을 나타냅니다.
요청 헤더	HTTP 요청 헤더를 나열합니다.
새로운 콘텐츠 요청하기	HTTP 요청 본문을 표시합니다.
속성	속성은 API 프록시의 내부 상태를 나타냅니다. 기본적으로 표시되지 않습니다.
대상 엔드포인트	실행을 위해 선택된 TargetEndpoint를 나타냅니다.
응답 헤더	HTTP 응답 헤더를 나열합니다.
응답 콘텐츠	HTTP 응답 본문을 표시합니다.
PostClientFlow	요청 클라이언트 앱에 요청이 반환된 후 실행되는 PostClientFlow에 대한 정보를 표시합니다. MessageLogging 정책만 PostClientFlow에 연결할 수 있습니다. PostClientFlow는 주로 현재 응답 메시지의 시작 및 종료 타임스탬프 사이의 시간 간격을 측정하는 데 사용됩니다.

필터를 사용하여 메시지 캡처 세분화

헤더 또는 쿼리 매개변수 값을 지정하여 Trace 도구에 표시되는 요청을 필터링할 수 있습니다. 필터를 사용하면 문제를 일으킬 수 있는 특정 통화를 타겟팅할 수 있습니다. 예를 들어 특정 콘텐츠가 포함된 요청이나 특정 파트너나 앱에서 들어오는 요청에 집중해야 할 수 있습니다. 다음을 기준으로 필터링할 수 있습니다.

HTTP 헤더 - 특정 헤더가 포함된 호출로만 trace를 제한합니다. 이렇게 하면 문제를 해결하는 데 도움이 됩니다. 앱 개발자에게 헤더를 전송하여 문제를 일으키는 호출에 포함하도록 요청할 수 있습니다. 그러면 Apigee Edge가 해당 특정 헤더가 있는 통화만 기록하므로 결과를 살펴볼 수 있습니다.
쿼리 매개변수 - 매개변수의 특정 값이 있는 호출만 기록됩니다.

필터 기능에 관해 알아야 할 사항

필터 필드에 필터 매개변수를 지정한 후에 Trace 세션을 다시 시작해야 합니다.
필터 매개변수는 AND로 연결됩니다. 성공적인 일치를 위해서는 지정된 모든 쿼리 또는 헤더 이름/값 쌍이 요청에 있어야 합니다.
필터 도구에서는 패턴 일치가 지원되지 않습니다.
필터 매개변수 및 값은 대소문자를 구분합니다.

trace 필터를 만드는 방법

트레이스 세션이 실행 중이면 Stop Trace Session(추적 세션 중지)을 클릭하여 중지합니다.
Trace 도구의 왼쪽 상단에 있는 필터를 클릭하여 필터 필드를 펼칩니다.
필터 필드에서 필터링할 쿼리 매개변수 또는 헤더 값을 지정합니다. 이 예에서는 필터링할 쿼리 매개변수 2개를 지정합니다. 성공적인 일치를 위해서는 두 매개변수가 모두 요청에 있어야 합니다.
트레이스 세션을 시작합니다.
API를 호출합니다. 지정된 헤더 또는 쿼리 매개변수를 모두 포함하는 요청만 성공적인 일치를 생성합니다.

거래 아래에는 미리 설정된 2개의 쿼리 매개변수와 일치하는 네 개의 결과가 표시됩니다.

위 예에서 이 API 호출은 Trace에 표시됩니다.

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

하지만 다음과 같은 것은 아닙니다.

http://docs-test.apigee.net/cats?name=Penny

Trace로 디버깅

Trace를 통해 API 프록시에 대한 많은 내부 세부정보를 확인할 수 있습니다. 예를 들면 다음과 같습니다.

올바르게 실행되거나 실패하는 정책을 한눈에 확인할 수 있습니다.
애널리틱스 대시보드 중 하나를 통해 API 중 하나에서 비정상적인 성능 저하가 발생하는 것을 알게 되었다면, 이제 Trace를 사용하여 병목 현상을 일으키는 위치를 식별할 수 있습니다. Trace는 각 처리 단계를 완료하는 데 걸리는 시간(밀리초)을 제공합니다. 한 단계가 너무 오래 걸리면 시정 조치를 취할 수 있습니다.
단계 세부정보를 보면 백엔드로 전송되는 헤더를 확인하고 정책에 의해 설정된 변수를 보는 등의 작업을 수행할 수 있습니다.
기본 경로를 확인하면 정책이 올바른 서버로 메시지를 라우팅하는지 확인할 수 있습니다.

보기 옵션 선택

트레이스 세션의 뷰 옵션을 선택합니다.

옵션	설명
사용 중지된 정책 표시	사용 중지된 정책을 표시합니다. 정책은 공개 API로 사용 중지할 수 있습니다. API 프록시 구성 참조를 확인하세요.
건너뛰기한 단계 표시	건너뛴 모든 단계를 표시합니다. 단계 조건이 false로 평가되어 정책이 실행되지 않은 경우 건너뛰는 단계가 발생합니다. 자세한 내용은 흐름 변수 및 조건을 참조하세요.
모든 FlowInfo 표시	흐름 세그먼트 내에서 전환을 나타냅니다.
선택한 단계 자동 비교	선택한 단계를 이전 단계와 비교합니다. 선택한 단계만 보려면 이 기능을 해제합니다.
변수 표시	읽거나 값이 할당된 변수를 표시하거나 숨깁니다.
속성 표시	속성은 API 프록시의 내부 상태를 나타냅니다. (기본적으로 숨겨져 있습니다.)

trace 결과 다운로드

원시 트레이스 결과의 XML 파일을 다운로드하여 텍스트 편집기에서 오프라인으로 보고 검색할 수 있습니다. 파일에는 모든 헤더, 변수, 정책의 콘텐츠를 비롯하여 수신 대기 세션의 전체 세부정보가 표시됩니다.

다운로드하려면 Download Trace Session을 클릭합니다.

요청을 curl로 표시

대상 서버에 대한 API 호출을 추적한 후 요청을 curl 명령어로 볼 수 있습니다. 이 방법은 다음과 같은 이유로 디버깅에 특히 유용합니다.

API 프록시는 요청을 수정할 수 있으므로 프록시에서 대상 서버로의 요청이 원래 요청과 어떻게 다른지 확인하는 것이 좋습니다. curl 명령어는 수정된 요청을 나타냅니다.
큰 메시지 페이로드의 경우 curl을 사용하면 HTTP 헤더와 메시지 콘텐츠를 한곳에서 볼 수 있습니다. (현재 약 1,000자(영문 기준)로 제한됩니다. 한도를 초과하는 방법에 관한 팁은 이 커뮤니티 게시물을 참고하세요.)

보안을 위해 curl 기능은 HTTP 승인 헤더를 마스킹합니다.

Trace에서 API 호출이 수신된 후 요청을 curl로 확인하려면 트랜잭션 맵 다이어그램에서 '대상 서버로 전송된 요청' 단계를 선택한 다음 단계 세부정보 창의 '대상 서버로 전송된 요청' 열에서 curl 표시 버튼을 클릭합니다.

이미지 주석은 'Show Curl'(컬 표시) 버튼과 트랜잭션 맵 다이어그램의 원 중 하나를 가리킵니다.

Apigee Trace 지원 사용

기본적으로 Apigee Edge는 Apigee 지원팀에서 API 프록시에 Trace 도구를 사용하여 지원할 수 있도록 허용합니다. 이 옵션은 언제든지 사용 중지할 수 있습니다. 하지만 이 옵션을 사용 중지하면 Apigee 지원 서비스가 제한될 수 있습니다.

Apigee 지원팀에서 Trace 도구를 사용하지 않도록 설정하려면 다음 안내를 따르세요.

https://apigee.com/edge에 로그인합니다.
왼쪽 탐색 메뉴에서 관리 > 개인 정보 보호 및 보안을 선택합니다.
Trace - Apigee 지원 토글 전환 버튼을 클릭하여 Apigee 지원에서 Trace 도구 사용을 중지합니다.