진단 수집기 사용

진단 수집기는 필요에 따라 Apigee Hybrid 인스턴스의 Kubernetes 구성요소에서 진단 데이터를 캡처하고 이를 Google Cloud Storage 버킷에 저장하는 도구입니다. apigeectl diagnostic 명령어로 진단 수집기를 호출합니다.

어떤 시스템 데이터가 캡처되나요?

진단 수집기는 다음 유형의 데이터를 캡처합니다.

  • 변경 로그 수준
  • Jstack
  • 포드 구성 yaml
  • PS -ef 출력
  • TCP 덤프
  • TOP 출력

데이터는 어떻게 되나요?

진단 수집기가 데이터를 캡처하면 Google Cloud 프로젝트의 스토리지 버킷에 업로드됩니다. Google Cloud Platform: Cloud Storage 브라우저에서 저장된 데이터를 볼 수 있습니다.

선택적으로 지원 티켓을 만들 때 Google Apigee 지원에 이 데이터를 공유하도록 선택할 수 있습니다.

진단 수집기 실행을 위한 기본 요건

진단 수집기를 사용하려면 먼저 다음 기본 요건을 완료해야 합니다.

Google Cloud Storage 버킷

Google Cloud 프로젝트에서 고유 이름으로 Google Cloud Storage 버킷을 만듭니다. gsutil 명령어를 사용하거나 Google Cloud Platform: Cloud Storage 브라우저에서 버킷을 만들고 관리할 수 있습니다.

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

gsutil mb gs://apigee_diagnostic_data
Creating gs://apigee_diagnostic_data/...

자세한 내용은 스토리지 버킷 만들기를 참조하세요.

서비스 계정

프로젝트에서 스토리지 관리자 역할(roles/storage.admin)로 서비스 계정을 만들고 서비스 계정 .json 키 파일을 다운로드합니다.

서비스 계정에는 모든 고유 이름을 사용할 수 있습니다. 이 가이드에서는 서비스 계정 이름으로 'apigee-diagnostic'을 사용합니다.

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

gcloud config set project ${PROJECT_ID}
gcloud iam service-accounts create apigee-diagnostic
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/storage.admin"
gcloud iam service-accounts keys create ${PROJECT_ID}-apigee-diagnostic.json \
    --iam-account=apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com

다음을 참조하세요.

진단 수집기 사용

진단 수집기 사용 순서는 다음과 같습니다.

  1. 데이터를 진단할 정보 유형, Apigee 컨테이너, 개별 포드 유형을 선택하여 overrides.yaml 파일에서 진단 스탠자를 구성합니다. 진단 수집기의 overrides.yaml 구성을 참조하세요.
  2. 다음 apigeectl 명령어로 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE

    여기서 OVERRIDES_FILEoverrides.yaml 파일의 경로입니다.

  3. 로그를 확인합니다.
    1. apigee-diagnostic 네임스페이스에서 포드를 가져옵니다.
      kubectl get pods -n apigee-diagnostic
    2. 이름에 diagnostic-collector가 포함된 포드를 기록해 둡니다.
    3. 다음 명령어로 로그를 확인합니다.
      kubectl -n apigee-diagnostic logs -f POD_NAME

      여기에서 POD_NAME은 진단 수집기 포드의 이름입니다.

      또한 Google Cloud Platform: Cloud Storage 브라우저에서 수집된 로그를 확인할 수 있습니다.

  4. 데이터를 수집한 후 진단 수집기를 삭제합니다. 삭제할 때까지는 다시 실행할 수 없습니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE

진단 수집기의 overrides.yaml 구성

진단 수집기를 실행하려면 먼저 overrides.yaml 파일에서 이를 구성해야 합니다.

diagnostic 구성 속성을 전체 참조하려면 구성 속성 참조: diagnostic을 참조하세요.

필수 속성

진단 수집기를 실행하려면 다음 속성이 필요합니다.

  • diagnostic.serviceAccountPath: 기본 요건에서 스토리지 관리자 역할이 있는 서비스 계정의 서비스 계정 키 파일의 경로입니다.
  • diagnostic.operation: 모든 통계 또는 로그만 수집할지 여부를 지정합니다.

    값은 "ALL" 또는 "LOGGING"입니다.

    diagnostic.operation"LOGGING"으로 설정하면 다음 속성이 필요합니다.

  • diagnostic.bucket: 진단 데이터를 저장할 Google Cloud Storage 버킷의 이름입니다. 이 버킷은 기본 요건에서 만든 버킷입니다.
  • diagnostic.container: 데이터를 캡처할 포드 유형을 지정합니다. 값은 다음 중 하나일 수 있습니다.
    containerApigee 구성요소Kubernetes 네임스페이스이 컨테이너의 예시 포드 이름
    apigee-cassandra Cassandra apigee apigee-cassandra-default-0
    istio-proxy Istio 인그레스 istio-system istio-ingressgateway-696879cdf8-9zzzf
    apigee-mart-server MART apigee apigee-mart-hybrid-example-d89fed1-151-jj2ux-l7nlb
    apigee-runtime 메시지 프로세서 apigee apigee-runtime-hybrid-example-3b2ebf3-151-s64bh-g9qmv
    apigee-synchronizer 동기화 담당자 apigee apigee-synchronizer-hybrid-example-3b2ebf3-151-xx4z6cg78
    apigee-udca UDCA apigee apigee-udca-hybrid-example-3b2ebf3-151-q4g2c-vnzg9
    apigee-watcher 감시자 apigee apigee-watcher-hybrid-example-d89fed1-151-cpu3s-sxxdf
  • diagnostic.namespace: 데이터를 수집 중인 포드가 있는 Kubernetes 네임스페이스입니다. 네임스페이스는 diagnostic.container로 지정하는 컨테이너에 올바른 것이어야 합니다.
  • diagnostic.podNames: 진단 데이터를 수집하려는 개별 포드의 이름입니다. 예를 들면 다음과 같습니다.
    diagnostic:
     …
     podNames:
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

작업이 LOGGING으로 설정된 경우에만 필요한 속성

다음 속성은 diagnostic.operationLOGGING인 진단 수집기를 실행할 때만 필요합니다.

  • diagnostic.loggerNames: 데이터를 수집할 로거의 이름을 지정합니다. Apigee Hybrid 버전 1.6.0의 경우 ALL만 지원되어, 모든 로거가 사용됩니다. 예를 들면 다음과 같습니다.
    diagnostic:
     …
     loggingDetails:
       loggerNames:
       - ALL
  • diagnostic.logLevel: 수집할 로깅 데이터의 세분성을 지정합니다. Apigee Hybrid 1.6에서는 FINE만 지원됩니다.
  • diagnostic.logDuration: 수집된 로그 데이터의 기간(밀리초)입니다. 일반적인 값은 30000입니다.

선택 속성

다음 속성은 선택사항입니다.

  • diagnostic.tcpDumpDetails.maxMsgs: 수집할 tcpDump 메시지의 최대 개수를 설정합니다. Apigee에서는 최댓값을 1000보다 크지 않게 하는 것이 좋습니다.
  • diagnostic.tcpDumpDetails.timeoutInSeconds: tcpDump가 메시지를 반환할 때까지 기다리는 시간(초)을 설정합니다.
  • diagnostic.threadDumpDetails.delayInSeconds: 각 스레드 덤프를 수집할 때의 지연 시간(초)입니다. diagnostic.threadDumpDetails.iterations와 함께 사용해야 합니다.
  • diagnostic.threadDumpDetails.iterations: 수집할 jstack 스레드 덤프 반복 수입니다. diagnostic.threadDumpDetails.delayInSeconds와 함께 사용해야 합니다.

일반 예시

다음은 모든 가능한 항목을 보여주는 예시 diagnostic 스탠자입니다.

diagnostic:
  # required properties:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "apigee-runtime"
  namespace: "apigee"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  # required if operation is Logging
  loggingDetails:
    loggerNames:
    - ALL
    logLevel: FINE
    logDuration: 30000

  # optional properties:
  tcpDumpDetails:
    maxMsgs: 10
    timeoutInSeconds: 100

  threadDumpDetails:
    iterations: 5
    delayInSeconds: 2

일반 사용 사례

다음 예시에서는 몇 가지 일반적인 상황에서 진단 수집기를 구성하고 사용하는 방법을 보여줍니다.

높은 프록시 지연 시간

이 경우 Apigee 런타임이 요청 처리에 오래 걸려 고객의 프록시 지연 시간이 길어집니다. Jstack 및 TOP 출력을 수집해야 합니다.

  1. 2개의 런타임 포드를 선택합니다.
  2. 다음 구조로 diagnostic 스탠자를 만듭니다.
    diagnostic:
      serviceAccountPath: "service-accounts/apigee-diagnostics.json"
      operation: "ALL"
      bucket: "diagnostics_data"
      container: "apigee-runtime"
      namespace: "apigee"
      podNames:
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
    
      tcpDumpDetails:
        maxMsgs: 10
    
      threadDumpDetails:
        iterations: 15
        delayInSeconds: 1
  3. diagnostic 스탠자를 구성한 후 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 로그를 수집하고 진단 수집기를 삭제합니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE

네트워크/연결 문제

인그레스 게이트웨이 포드는 물론 apigee 런타임에 대해 진단을 실행할 수 있습니다.

  1. 2개의 런타임 포드를 선택합니다.
  2. 다음 구조로 diagnostic 스탠자를 만듭니다.
    diagnostic:
      serviceAccountPath: "service-accounts/apigee-diagnostics.json"
      operation: "ALL"
      bucket: "diagnostics_data"
      container: "apigee-runtime"
      namespace: "apigee"
      podNames:
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
    
      tcpDumpDetails:
        maxMsgs: 1000
  3. diagnostic 스탠자를 구성한 후 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 로그를 수집하고 진단 수집기를 삭제합니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. Istio 인그레스 게이트웨이에서 2개의 포드를 선택합니다.
  6. Istio 인그레스 포드로 diagnostic 스탠자를 다시 구성합니다.
    diagnostic:
      serviceAccountPath: "service-accounts/apigee-diagnostics.json"
      operation: "ALL"
      bucket: "diagnostics_data"
      container: "istio-proxy"
      namespace: "istio-system"
      podNames:
      - istio-ingressgateway-696879cdf8-9zzzf
      - istio-ingressgateway-696879cdf8-6abc7
    
      tcpDumpDetails:
        maxMsgs: 1000
  7. diagnostic 스탠자를 구성한 후 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE
  8. 로그를 수집하고 진단 수집기를 삭제합니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE

프록시에서 예상치 않은 오류 발생 또는 새로운 계약이 적용되지 않음

이 경우 최소 5분 동안 또는 이 예시에서와 같이 10분 동안 디버그를 위해 로그 수준을 변경해야 합니다. 이렇게 하면 로그 양이 늘어나지만 유용한 정보가 로깅됩니다. Apigee 런타임과 Apigee 동기화 담당자에서 각각 한 번씩 진단 수집기를 두 번 실행합니다.

  1. 2개의 런타임 포드를 선택합니다.
  2. 다음 구조로 diagnostic 스탠자를 만듭니다.
    diagnostic:
      serviceAccountPath: "service-accounts/apigee-diagnostics.json"
      operation: "LOGGING"
      bucket: "diagnostics_data"
      namespace: "apigee"
      container: "apigee-runtime"
      podNames:
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
      - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
    
      loggingDetails:
        loggerNames:
        - ALL
        logLevel: FINE
        logDuration: 60000
    
  3. diagnostic 스탠자를 구성한 후 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE
  4. 로그를 수집하고 진단 수집기를 삭제합니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. 동기화 담당자 포드 2개를 선택합니다.
  6. 다음 구조로 diagnostic 스탠자를 만듭니다.
    diagnostic:
      serviceAccountPath: "service-accounts/apigee-diagnostics.json"
      operation: "LOGGING"
      bucket: "diagnostics_data"
      namespace: "apigee"
      container: "apigee-synchronizer"
      podNames:
      - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-6cg78
      - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-1a2b3
    
      loggingDetails:
        loggerNames:
        - ALL
        logLevel: FINE
        logDuration: 60000
    
  7. diagnostic 스탠자를 구성한 후 진단 수집기를 실행합니다.
    apigeectl diagnostic -f OVERRIDES_FILE
  8. 로그를 수집하고 진단 수집기를 삭제합니다.
    apigeectl diagnostic delete -f OVERRIDES_FILE