API 추적

OpenAPI | gRPC

Extensible Service Proxy (ESP) 또는 Extensible Service Proxy V2 (ESPv2)와 API의 백엔드 코드를 배포한 후 프록시는 모든 요청을 가로채고 필요한 검사를 수행한 후 요청을 API 백엔드로 전달합니다. 백엔드가 응답하면 프록시는 원격 분석을 수집하고 보고합니다. 프록시가 캡쳐하는 프록시 중 하나는 Cloud Trace를 사용하여 추적하는 것입니다.

이 페이지에서는 다음 방법을 설명합니다.

• Google Cloud Console에서 trace를 확인합니다.
• Trace에 대한 비용을 예상합니다.
• 프록시에서 trace 샘플링을 사용하지 않도록 구성합니다.

추적 보기

trace는 API에 대한 수신 요청과 다양한 이벤트 (예: RPC 호출 또는 코드의 계측 섹션)를 각 이벤트의 정확한 타이밍과 함께 추적합니다. 이러한 이벤트는 추적에서 스팬으로 표시됩니다.

프로젝트의 추적을 보려면 Google Cloud Console의 Cloud Trace 페이지로 이동합니다.

Trace로 이동

Trace 탐색기 페이지에서는 드릴다운하여 개별 trace를 보고 trace에서 ESP가 생성하는 스팬을 확인할 수 있습니다. 필터를 사용하여 단일 API 또는 작업의 trace를 볼 수 있습니다.

API용으로 생성된 trace와 스팬은 API에서 ESPv2를 사용하는지 또는 ESP를 사용하는지에 따라 달라집니다. 각 구현의 trace 형식 요약은 다음과 같습니다.

Trace 탐색기 페이지에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

ESPv2에서 생성되는 스팬

ESPv2는 다음 형식의 trace를 만듭니다.

최소한 ESPv2는 trace당 2개의 스팬을 만듭니다.

• 전체 요청 및 응답에 대한 ingress OPERATION_NAME 스팬입니다.
• ESPv2가 백엔드가 요청을 처리하고 다시 응답할 때까지 대기하는 시간의 router BACKEND egress 스팬입니다. 여기에는 ESPv2와 백엔드 사이의 네트워크 홉이 포함됩니다.

API 구성에 따라 ESPv2는 스팬을 추가로 만들 수 있습니다.

• API에 인증이 필요한 경우, ESPv2는 인증에 필요한 공개 키를 5분 동안 캐시합니다. 공개 키가 캐시에 없으면 ESPv2가 공개 키를 검색하여 캐시에 저장하고 JWT Remote PubKey Fetch 스팬을 만듭니다.
• API에 API 키가 필요한 경우 ESPv2는 API 키 검증에 필요한 정보를 캐시합니다. 정보가 캐시에 없으면 ESPv2가 Service Control을 호출하고 Service Control remote call: Check 스팬을 만듭니다.

일반적으로 ESPv2는 들어오는 요청을 차단하는 네트워크 호출의 스팬만 만듭니다. 차단하지 않는 요청은 추적되지 않습니다. 모든 로컬 처리는 스팬 대신 시간 이벤트를 만듭니다. 예를 들면 다음과 같습니다.

• 할당량 적용에는 원격 호출이 필요하지만 호출은 API 요청 경로에서 발생하지 않으며 trace에서 해당 호출과 연결된 스팬은 포함되지 않습니다.
• API 키는 단기간 동안 ESPv2에서 캐시됩니다. 캐시를 사용하는 모든 요청에는 trace에 연결된 시간 이벤트가 있습니다.

ESP에서 생성되는 스팬

경고: ESP는 스팬에 대한 자세한 정보를 제공하지 않습니다. 또한 의미가 없는 스팬을 추가로 생성합니다. ESPv2로 마이그레이션하여 추적 권장사항을 따르는 자세한 trace를 확인하세요.

ESP는 다음 형식으로 trace를 만듭니다.

최소한 ESP는 추적당 4개의 스팬을 만듭니다.

• 전체 요청 및 응답에 대한 스팬
• API 구성을 가져오기 위해 Service Control services.check 메서드를 호출하는 CheckServiceControl 스팬
• API에 구성된 할당량이 있는지 확인하기 위한 QuotaControl 스팬
• API의 백엔드 코드에서 소비된 시간을 추적하는 Backend 스팬

API의 구성에 따라 ESP는 스팬을 추가로 만듭니다.

• API에 인증이 필요한 경우, ESP는 모든 trace에 CheckAuth 스팬을 만듭니다. 요청을 인증하기 위해 ESP는 인증에 필요한 공개 키를 5분 동안 캐시에 저장합니다. 공개 키가 캐시에 없으면 ESP가 공개 키를 검색하여 캐시에 저장하고 HttpFetch 스팬을 만듭니다.
• API에 API 키가 필요한 경우 ESP는 모든 trace에 CheckServiceControlCache 스팬을 만듭니다. ESP는 API 키 검증에 필요한 정보를 캐시에 저장합니다. 정보가 캐시에 없으면 ESP가 Service Control을 호출하고 Call ServiceControl server 스팬을 만듭니다.
• API에 할당량이 설정되어 있으면 ESP는 모든 trace에 QuotaServiceControlCache 스팬을 만듭니다. ESP가 할당량을 확인하는 데 필요한 정보를 캐시에 저장합니다. 정보가 캐시에 없으면 ESP가 Service Control을 호출하고 Call ServiceControl server 스팬을 만듭니다.

Trace 샘플링 레이트

ESP는 추적 데이터를 가져오기 위해 API에 대한 소량의 요청을 샘플링합니다. 샘플링 레이트를 제어하기 위해 ESP는 요청 카운터 및 타이머를 사용합니다. API에 대한 초당 요청 수에 따라 샘플링 레이트가 결정됩니다. 1초 내에 요청이 없으면 ESP가 추적을 전송하지 않습니다.

1초 내의 요청 수가

• 999개 이하이면 ESP가 추적을 1개 전송합니다.
• 1000~1999개이면 ESP가 추적을 2개 전송합니다.
• 2000~2999개이면 ESP가 추적을 3개 전송합니다.
• 그 밖에도 많은 사례가 있습니다.

요약하면 ceiling 함수(예: ceiling(requests per second/1000))을 사용하여 샘플링 레이트를 예상할 수 있습니다.

Trace 비용 예상

Trace 비용을 예상하기 위해서는 ESP가 1개월 동안 Trace에 전송하는 스팬 수를 예상해야 합니다.

1개월당 스팬 수를 예상하려면 다음 안내를 따르세요.

1. API에 대한 초당 요청 수를 예상합니다. 이를 예상하려면 Endpoints > 서비스 페이지나 Cloud Logging에서 요청 그래프를 사용합니다. 자세한 내용은 API 모니터링을 참조하세요.
2. ESP가 초당 Trace에 보내는 trace 수를 계산합니다. ceiling(requests per second/1000)
3. 추적에 있는 스팬 수를 예상합니다. ESP에서 생성되는 스팬을 참조하거나 Trace 목록 페이지에서 API의 trace를 확인하여 예상할 수 있습니다.
4. API가 트래픽을 가져오는 월별 시간(초)을 예상합니다. 예를 들어 일부 API는 하루 중 특정 시간에만 요청을 가져오고, 다른 API는 산발적으로 요청을 가져옵니다.
5. 월별 시간(초)에 스팬 수를 곱합니다.

예를 들면 다음과 같습니다.

1. API의 초당 최대 요청 수가 5라고 가정합니다.
2. 추적 샘플링 레이트는 ceiling (5/1000) = 1입니다.
3. API는 구성된 할당량이 없고, API 키가 필요하지 않으며, 인증이 필요하지 않습니다. 따라서 ESP가 추적당 생성하는 스팬 수는 4입니다.
4. 이 API는 월요일부터 금요일까지 업무 시간 중에만 요청을 가져옵니다. 한 달 동안 API가 트래픽을 이용하는 시간(초)은 약 3600 X 8 X 20 = 576,000입니다.
5. 월간 스팬 수는 약 576,000 x 4 = 2,304,000입니다.

대략적인 월간 스팬 수를 확인한 후에는 Trace 가격 책정 페이지에서 자세한 가격 정보를 확인하세요.

추적 샘플링 사용 중지

샘플링 요청 및 trace 전송에서 ESP를 중지하려는 경우 ESP 시작 옵션을 설정하고 ESP를 다시 시작할 수 있습니다. ESP가 Cloud Trace에 전송하는 trace는 Endpoints > 서비스 페이지에 표시된 그래프와 관계가 없습니다. trace 샘플링을 중지해도 그래프를 계속 사용할 수 있습니다.

다음 섹션에서는 API와 ESP가 이미 배포되었거나 사용자가 배포 프로세스에 익숙하다고 가정합니다. 자세한 내용은 API 백엔드 배포를 참조하세요.

App Engine

App Engine 가변형 환경에서 ESP trace 샘플링을 사용 중지하려면 다음 안내를 따르세요.

1. app.yaml 파일을 수정합니다. endpoints_api_service 섹션에서 trace_sampling 옵션을 추가하고 값을 false로 설정합니다. 예를 들면 다음과 같습니다.

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   애플리케이션이 마이크로서비스를 기반으로 하는 경우 모든 app.yaml 파일에 trace_sampling: false를 포함해야 합니다.

2. Google Cloud CLI를 최근에 업데이트하지 않은 경우 다음 명령어를 실행합니다.

   gcloud components update

3. app.yaml 파일을 저장합니다.
4. App Engine에 백엔드 코드와 ESP를 배포합니다.

   gcloud app deploy

trace 샘플링을 다시 사용 설정하려면 다음 안내를 따르세요.

1. app.yaml에서 trace_sampling 옵션을 삭제합니다.
2. App Engine에 백엔드 코드와 ESP를 배포합니다.

   gcloud app deploy

Compute Engine

Docker가 있는 Compute Engine에서 ESP 추적 샘플링을 사용 중지하려면 다음 안내를 따르세요.

1. VM 인스턴스에 연결합니다.

   gcloud compute ssh [INSTANCE_NAME]

2. docker run 명령어의 ESP 플래그에서 --disable_cloud_trace_auto_sampling 옵션을 추가합니다.

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. docker run 명령어를 실행하여 ESP를 다시 시작합니다.

trace 샘플링을 다시 사용 설정하려면 다음 안내를 따르세요.

1. --disable_cloud_trace_auto_sampling을 삭제합니다.
2. docker run 명령어를 실행하여 ESP를 다시 시작합니다.

GKE

GKE에서 ESP trace 샘플링을 사용 중지하려면 다음 안내를 따르세요.

1. deployment.yaml이라고 하는 배포 매니페스트 파일을 열고 containers 섹션에 다음을 추가합니다.

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. kubectl create 명령어를 사용하여 Kubernetes 서비스를 시작합니다.

   kubectl create -f deployment.yaml

trace 샘플링을 다시 사용 설정하려면 다음 안내를 따르세요.

1. --disable_cloud_trace_auto_sampling 옵션을 삭제합니다.
2. Kubernetes 서비스를 시작합니다.

   kubectl create -f deployment.yaml

Docker 컨테이너가 없는 Compute Engine VM 인스턴스에서 ESP를 실행하는 경우 --disable_cloud_trace_auto_sampling 옵션의 VM 인스턴스 메타데이터 키-값 쌍에 해당하는 것이 없습니다. trace 샘플링을 사용 중지하려면 컨테이너에서 ESP를 실행해야 합니다.

클라이언트는 요청을 강제로 추적에 설명된 대로 요청에 X-Cloud-Trace-Context 헤더를 추가하여 요청을 강제로 추적할 수 있습니다. 요청에 X-Cloud-Trace-Context 헤더가 포함되어 있는 경우 ESP는 trace 샘플링을 사용하지 않더라도 Trace에 trace 데이터를 보냅니다.

Trace 컨텍스트 전파

분산 추적의 경우 요청 헤더에 추적 ID를 지정하는 trace 컨텍스트가 포함될 수 있습니다. ESPv2가 새 trace 스팬을 만들어 Cloud Trace로 전송하면 추적 ID가 사용됩니다. trace ID는 단일 요청에 대한 모든 trace를 검색하고 스팬을 조인하는 데 사용됩니다. 요청에 추적 컨텍스트를 지정하지 않고 추적을 사용하면 모든 trace 스팬에 대해 무작위 추적 ID가 생성됩니다.

다음 예시에서 Cloud Trace는 단일 요청에 대해 ESPv2 (1)에서 만든 스팬과 백엔드 (2)에서 만든 스팬을 연결합니다. 이렇게 하면 전체 시스템에서 지연 시간 문제를 디버깅하는 데 도움이 됩니다.

자세한 내용은 OpenTelemetry 핵심 개념: 컨텍스트 전파를 참조하세요.

참고: 분산 추적을 사용하려면 클라이언트 및/또는 백엔드에서 추적을 지원해야 합니다. 이 문서에서는 다루지 않습니다. OpenTelemetry를 사용하는 것이 좋습니다.

지원되는 헤더

ESPv2는 다음과 같은 trace 컨텍스트 전파 헤더를 지원합니다.

• traceparent: 표준 W3C trace 컨텍스트 전파 헤더입니다. 대부분의 최신 추적 프레임워크에서 지원합니다.
• x-cloud-trace-context: GCP의 trace 컨텍스트 전파 헤더입니다. 이전 추적 프레임워크 및 Google 라이브러리에서 지원되지만 공급업체마다 다릅니다.
• grpc-trace-bin: OpenCensus 추적 라이브러리를 통해 gRPC 백엔드에서 사용하는 trace 컨텍스트 전파 헤더입니다.

새 애플리케이션을 빌드하는 경우 traceparent trace 컨텍스트 전파를 사용하는 것이 좋습니다. ESPv2는 기본적으로 이 헤더를 추출하고 전파합니다. 기본 동작 변경에 대한 자세한 내용은 ESPv2 추적 시작 옵션을 참조하세요.

참고: ESPv2와 달리 ESP의 trace 컨텍스트 전파는 시작 옵션을 통해 수동으로 사용 설정해야 합니다. ESP는 traceparent 헤더를 지원하지 않습니다.