진단 수집기 사용

현재 Apigee Hybrid 문서의 1.11 버전을 보고 있습니다. 자세한 내용은 지원되는 버전을 참조하세요.

Version 1.11 

지원되는 버전:

• v1.12(최신 버전)                        
• v1.11                         
• v1.10                                        
• 지원되는 버전 목록

지원되지 않는 버전:

• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

진단 수집기는 필요에 따라 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/...

버킷 이름은 조직 외부의 버킷 이름을 포함하여 모든 Google Cloud 프로젝트 간에 전역으로 고유해야 합니다.

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

서비스 계정

프로젝트에서 스토리지 관리자 역할(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

다음을 참조하세요.

• 서비스 계정 만들기 및 관리
• 서비스 계정 키 만들기 및 관리
• 역할 이해: Cloud Storage 역할

진단 수집기 사용

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

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

   apigeectl diagnostic -f OVERRIDES_FILE

   여기서 OVERRIDES_FILE은 overrides.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.loggingDetails.logDuration
  • diagnostic.loggingDetails.loggerNames
  • diagnostic.loggingDetails.logLevel
• diagnostic.bucket: 진단 데이터를 저장할 Google Cloud Storage 버킷의 이름입니다. 이 버킷은 기본 요건에서 만든 버킷입니다.
• diagnostic.container: 데이터를 캡처할 포드 유형을 지정합니다. 값은 다음 중 하나일 수 있습니다.

  container 값	Apigee 구성요소	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.operation이 LOGGING인 진단 수집기를 실행할 때만 필요합니다.

• 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