API 추적

Extensible Service Proxy(ESP) 및 API의 백엔드 코드를 배포한 후 ESP는 요청을 API 백엔드로 전달하기 전에 모든 요청을 가로채서 필요한 검사를 수행합니다. 백엔드가 응답할 때 ESP는 텔레메트리를 수집하고 보고합니다. ESP가 캡처하는 텔레메트리 데이터 중 하나는 Cloud Trace를 사용한 trace 데이터입니다.

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

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

API에 대한 추적 보기

API에 대한 추적을 보려면 다음 안내를 따르세요.

  1. 프로젝트의 Endpoints > 서비스 페이지로 이동합니다.

    Endpoints 서비스 페이지로 이동

  2. API가 여러 개인 경우 추적을 보려는 API를 클릭합니다.

  3. 개요 탭이 표시되었는지 확인합니다.

  4. 아래로 스크롤하고 추적 보기를 클릭합니다. Cloud Trace Trace 목록 페이지가 표시됩니다.

추적은 API에 대한 수신 요청과 RPC 호출 또는 발생한 코드의 계측 섹션(정확한 타이밍 포함)과 같은 여러 이벤트를 추적합니다. 이러한 이벤트는 추적에서 스팬으로 표시됩니다.

Trace 목록 페이지에서는 개별 trace를 드릴다운하고 trace에서 ESP가 생성하는 스팬을 확인할 수 있습니다.

스팬을 포함한 trace 예

Trace 목록 페이지에 대한 자세한 정보는 Cloud Console에서 trace 보기를 참조하세요.

ESP에서 생성되는 스팬

최소한 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개 전송합니다.
  • 그 후에도 동일한 규칙에 따라 ESP가 추적을 전송합니다.

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

Trace 비용 예상

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

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

  1. API에 대한 초당 요청 수를 예상합니다. 이를 예상하려면 Endpoints > 서비스 페이지에서 또는 Cloud Logging에서 Requests 그래프를 사용하면 됩니다. 자세한 내용은 API 모니터링을 참조하세요.
  2. ESP가 초당 Trace에 보내는 trace 수를 계산합니다. ceiling(requests per second/1000)
  3. trace에 있는 스팬 수를 예상합니다. 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. Cloud SDK를 최근에 업데이트하지 않은 경우 다음 명령어를 실행합니다.
    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 데이터를 보냅니다.