Cloud Logging에서 Apigee 로그 누락 문제 해결

Apigee 및 Apigee Hybrid 문서입니다.
이 주제에 해당하는 Apigee Edge 문서가 없습니다.

증상

Apigee API 로그를 Cloud Logging으로 전송하는 것이 일반적인 사용 사례입니다. 이는 일반적으로 MessageLogging 정책 또는 ServiceCallout 정책을 통해 수행됩니다. 두 경우 모두 Apigee는 Cloud Logging API를 사용하여 로그를 작성합니다.

경우에 따라 Cloud Logging에 Apigee API 로그가 표시되지 않을 수 있습니다.

오류 메시지

오류 메시지가 표시되지 않습니다.

가능한 원인

원인	설명	다음에 관한 문제 해결 안내
Cloud Logging API가 사용 설정되지 않음	Apigee 조직의 Google Cloud 프로젝트에서 Cloud Logging API를 사용 설정했는지 확인합니다.	Apigee 및 Apigee Hybrid
잘못 구성된 프록시 서비스 계정	배포 시(Apigee) 또는 런타임 구성(Apigee Hybrid)에 사용되는 서비스 계정이 삭제/잘못 구성되었을 수 있습니다.	Apigee 및 Apigee Hybrid
정책 구성의 프로젝트 이름이 잘못됨	정책 구성의 프로젝트 이름이 Apigee 조직과 연결된 이름과 동일하지 않습니다.	Apigee 및 Apigee Hybrid
런타임 서비스 계정의 역할/권한 누락	Apigee Hybrid의 경우 런타임 서비스 계정에 서비스 계정 토큰 생성자 역할이 있는지 확인합니다. Google 인증을 사용하기 위해 필요합니다.	Apigee Hybrid
허용된 Cloud Logging 한도를 초과하는 로그 항목 크기	Cloud Logging에는 변경할 수 없는 256KB 항목 크기 제한이 있습니다.	Apigee 및 Apigee Hybrid
Cloud Logging API의 분당 쓰기 요청 할당량 소진	Google Cloud 프로젝트에서 Cloud Logging API의 분당 쓰기 요청 할당량 값을 초과하지 않아야 합니다.	Apigee 및 Apigee Hybrid

원인: Cloud Logging API가 사용 설정되지 않음

진단

Cloud Logging API가 사용 설정되어 있는지 확인합니다. Google Cloud 콘솔에서 사용 설정된 API 및 서비스를 나열하는 방법에 대한 안내는 사용 설정된 서비스 나열을 참조하세요.

해결 방법

Cloud Logging API가 사용 설정되지 않은 경우 서비스 사용 설정의 단계에 따라 사용 설정하세요. API를 사용 설정하는 데 몇 분 정도 걸릴 수 있습니다.

Cloud Logging API가 사용 설정되지 않아 Cloud Logging에 로그가 표시되지 않는 문제를 해결할 수 없는 경우 진단 정보 수집 필요를 참조하세요.

원인: 잘못 구성된 프록시 서비스 계정

진단

Apigee

서비스 계정 이름을 찾습니다.

Apigee UI 사용:
1. 개발 > API 프록시를 클릭한 후 프록시 이름을 클릭합니다. 예: TurboBooks
2. 배포 아래에 서비스 계정 이름이 표시됩니다.

Apigee API 사용:

다음 Apigee API 호출 실행:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/PROXY_NAME/revisions/REVISION_NUMBER/deployments"

다음을 바꿉니다.

ORG_NAME: 조직 이름. 예를 들면 apigee-example-org입니다.
ENV_NAME: 환경의 이름입니다. 예를 들면 myenv입니다.
PROXY_NAME: 프록시의 이름 예를 들면 TurboBooks입니다.
REVISION_NUMBER: 버전 번호. 예를 들면 4입니다.

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

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/apigee-example-org/environments/myenv/apis/TurboBooks/revisions/4/deployments"

다음과 비슷한 결과가 반환됩니다.

{
  "environment": "myenv",
  "apiProxy": "TurboBooks",
  "revision": "4",
  "deployStartTime": "1687408163394",
  "state": "READY",
  "instances": [
    {
      "instance": "apiginstance",
      "deployedRevisions": [
        {
          "revision": "4",
          "percentage": 100
        }
    .
    .
    .
    .
  "serviceAccount": "projects/-/serviceAccounts/envsa-79@apigee-example-org.iam.gserviceaccount.com"
}

여기서 serviceAccount는 API 프록시와 연결된 서비스 계정입니다.

이 프록시 서비스 계정에 대해 다음 사항을 확인하세요.
1. 이 서비스 계정은 Apigee 조직을 만들기 위해 사용한 것과 동일한 Google Cloud 프로젝트에 있어야 합니다. 예를 들면 다음과 같습니다. apigee-example-org.
2. 프록시를 배포하는 사용자는 이 서비스 계정에 대한 iam.serviceAccounts.actAs 권한을 가집니다.
  - 역할 목록은 서비스 계정 역할을 참조하세요.
  - 특정 사용자의 역할을 보는 방법에 대한 안내는 현재 액세스 보기를 참조하세요.
3. 프록시 서비스 계정에는 Cloud Logging 서비스를 호출하는 데 필요한 권한이 있습니다.
  - 역할 목록은 Logging 역할을 참조하세요.
  - 프록시 서비스 계정 권한을 보는 방법에 대한 안내는 현재 액세스 보기를 참조하세요.

Apigee Hybrid

Apigee Hybrid의 경우 Apigee에 나열된 단계 외에도 overrides.yaml 파일을 열고 Google 인증이 필요한 각 환경에 지정된 서비스 계정이 있는지 확인합니다. 예를 들면 다음과 같습니다.

envs:
  - name: "ENVIRONMENT_NAME"
    serviceAccountPaths:
      runtime: "KEY_FILE_PATH"

다음을 바꿉니다.

ENVIRONMENT_NAME: 환경의 이름입니다. 예를 들면 myenv입니다.
KEY_FILE_PATH: 런타임 서비스 계정 키 파일의 경로입니다. 설치 중에 서비스 계정 만들기에서 일반적으로 서비스 계정을 이미 만들었을 것입니다.

해결 방법

이 서비스 계정이 Apigee 조직을 만들기 위해 사용한 것과 동일한 Google Cloud 프로젝트에 없는 경우 동일한 Google Cloud 프로젝트에서 서비스 계정을 만들어 사용해야 합니다. Google 인증 사용에도 설명되어 있습니다.
프록시를 배포하는 사용자에게 이 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 없으면 단일 역할 부여를 참조하세요.
프록시 서비스 계정에 Cloud Logging 서비스를 호출하는 데 필요한 권한이 없으면 단일 역할 부여를 참조하세요.

이 문서의 이 단계에서 프록시 서비스 계정이 Apigee 및 Apigee Hybrid용으로 잘못 구성된 문제를 해결하지 못하면 진단 정보 수집 필요를 참조하세요.

원인: 정책 구성의 프로젝트 이름이 잘못됨

진단

MessageLogging 정책을 사용하여 Cloud Logging에 로그를 전송하는 경우:

Apigee UI에서 개발 > API 프록시 > API 프록시 이름 > 개발 탭을 클릭합니다.
코드 창에서 <CloudLogging> 요소를 찾습니다.
<LogName> 값이 올바른 프로젝트 이름인지 확인합니다.
```
<CloudLogging>
  <LogName>projects/PROJECT_ID/logs/LOG_ID</LogName>
</CloudLogging>
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다. 예를 들면 apigee-example-org입니다.
- LOG_ID: Cloud Logging 로그 ID입니다. 예를 들면 apigee-logs입니다.

해결 방법

<LogName> 요소의 값에 올바른 값이 없으면 올바른 값으로 업데이트합니다.

이 문서의 단계를 수행해도 문제가 해결되지 않으면 진단 정보 수집 필요를 참조하세요.

원인: 런타임 서비스 계정의 역할/권한 누락

진단

런타임이 프록시 서비스 계정을 가장할 수 있는지 확인합니다.

다음 gcloud 명령어를 실행하여 런타임 서비스 계정에 프록시 서비스 계정에 대한 iam.serviceAccountTokenCreator 역할이 있는지 확인합니다.

gcloud iam service-accounts get-iam-policy PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com

다음을 바꿉니다.

PROXY_SA_NAME: 프록시 서비스 계정의 이름입니다. 예를 들면 envsa-79입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다. 예를 들면 apigee-example-org입니다.

다음과 비슷한 결과가 반환됩니다.

- members:
  - serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
  role: roles/iam.serviceAccountTokenCreator

다음을 바꿉니다.

RUNTIME_SA_NAME: 런타임 서비스 계정의 ID입니다. 예를 들면 apigee-runtime입니다.

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

gcloud iam service-accounts get-iam-policy envsa-79@apigee-example-org.iam.gserviceaccount.com
  bindings:
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountAdmin
  - members:
    - serviceAccount:apigee-runtime@apigee-example-org.iam.gserviceaccount.com
    role: roles/iam.serviceAccountTokenCreator
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountUser
  etag: BwX-shcrL3o=
  version: 1

출력에 iam.serviceAccountTokenCreator 역할 및 예상 구성원이 표시되지 않으면 해결의 단계에 따라 올바른 역할을 부여합니다.

해결 방법

다음 gcloud 명령어를 실행하여 런타임 서비스 계정에 프록시 서비스 계정에 대한 iam.serviceAccountTokenCreator 역할을 부여합니다.

gcloud iam service-accounts add-iam-policy-binding \
PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator

다음을 바꿉니다.

PROXY_SA_NAME: 프록시 서비스 계정의 이름입니다. 예를 들면 envsa-79입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다. 예를 들면 apigee-example-org입니다.
RUNTIME_SA_NAME: 런타임 서비스 계정의 ID입니다. 예를 들면 apigee-runtime입니다.

이 문서의 단계를 수행해도 문제가 해결되지 않으면 진단 정보 수집 필요를 참조하세요.

원인: 허용된 로깅 제한을 초과하는 로그 항목 크기

진단

이 문서에 설명된 다른 원인이 문제가 아님을 확인한 후에도 Cloud Logging에 일부 로그가 표시되지 않으면 Apigee에서 전송된 일부 로그 항목의 크기가 Cloud Logging의 로그 크기 항목에 대한 256KB의 엄격한 제한을 초과한 것일 수 있습니다. 자세한 내용은 Logging 사용량 한도를 참조하세요.

해결 방법

이는 Cloud Logging에 설정된 구성 불가능한 한도로, 현재 알려진 유일한 해결 방법은 Apigee에서 전송된 로그 항목 크기를 256KB 미만으로 유지하는 것입니다. 이 한도를 초과할 가능성이 있는 페이로드를 로깅하는 경우 이 페이로드를 로깅하지 않거나 한도에 도달하면 일부 트랜잭션이 로깅되지 않음을 확인하십시오.

이 문서의 단계를 수행해도 문제가 해결되지 않으면 진단 정보 수집 필요를 참조하세요.

원인: Cloud Logging API의 분당 쓰기 요청 할당량 소진

진단

고객이 디버그 세션에서 요청을 볼 수 있지만 부하 분산기 로그에는 요청이 표시되어 있음에도 로그 탐색기에 요청이 로그되지 않는 경우가 있습니다.

관찰된 메시지 손실은 프로젝트 내 할당량 소진으로 인한 것일 수 있습니다. Cloud Logging API는 분당 쓰기 요청 120,000개의 비율 제한을 적용합니다. 이 할당량을 초과하면 메시지가 누락될 수 있습니다. 자세한 내용은 할당량 보기 및 관리를 참조하세요.

이러한 할당량은 Google Cloud 콘솔 내에서 늘릴 수 있으며 할당량 상향 문서에 따라 고객이 직접 수행할 수 있습니다.

해결 방법

할당량을 늘리려면 아래 절차를 따르세요.

할당량 페이지에서 Cloud Logging API 체크박스를 선택한 후 할당량 수정을 클릭합니다. Edit is not allowed for this quota 오류가 발생하면 Google Cloud Customer Care에 문의하여 할당량 변경을 요청할 수 있습니다. 또한 체크박스를 클릭하려면 Google Cloud 프로젝트에서 청구가 사용 설정되어 있어야 합니다.
할당량 변경 패널에서 서비스를 선택하여 뷰를 확장한 후 새 한도 및 요청 설명 필드를 입력합니다. 다음을 클릭합니다.
연락처 세부정보 패널에서 양식을 작성하고 요청 제출을 클릭합니다.

자세한 내용은 이 할당량 및 한도 문서를 참조하세요.

진단 정보 수집 필요

위 안내를 따른 후에도 문제가 지속되면 다음 진단 정보를 수집한 후 Google Cloud Customer Care에 문의하세요.

Apigee 조직
문제가 발생한 환경 및 API 프록시
다운로드한 디버그 세션(위 정보를 모두 제공함)
Cloud Logging에 로그를 전송하는 API 프록시의 특정 정책 이름입니다.
Apigee Hybrid: overrides.yaml 파일