플랫폼 로그를 사용하여 Cloud Storage 가져오기 문제 해결하기

이 가이드에서는 Cloud Storage 가져오기 주제를 사용하여 데이터를 처리할 때 Google Cloud Platform 로그를 사용하여 문제를 해결하는 방법을 설명합니다.

Cloud Storage 가져오기 주제의 처리 실패 정보

Cloud Storage 가져오기 주제에 데이터를 성공적으로 처리하지 못하는 문제가 발생할 수 있습니다. 예를 들어 Cloud Storage 가져오기 주제를 사용할 때 Cloud Storage 객체 또는 객체의 일부를 처리하는 데 문제가 발생할 수 있습니다.

다음 목록에서는 플랫폼 로그를 생성하는 Cloud Storage 가져오기 주제의 처리 실패 이유를 설명합니다.

  • 메일 크기

    • 개별 메일은 10MB 이하여야 합니다. 이 경우 전체 메시지가 건너뜁니다.

    • Avro 또는 Pub/Sub Avro 형식을 사용하는 경우 메시지 블록은 16MB를 초과할 수 없습니다. 더 큰 메시지 블록은 건너뜁니다.

  • 메시지 속성

    • 메시지에는 최대 100개의 속성이 있을 수 있습니다. 추가 속성은 메시지가 처리될 때 삭제됩니다.

    • 속성 키는 256바이트보다 클 수 없으며 값은 1,024바이트보다 클 수 없습니다. 더 큰 키 또는 값은 메시지가 처리될 때 메시지에서 삭제됩니다.

      메시지 키 및 속성 사용 가이드라인에 관한 자세한 내용은 속성을 사용하여 메시지 게시를 참고하세요.

  • Avro 형식 지정

    • Avro 객체의 형식이 올바른지 확인합니다. 형식이 잘못되면 메시지가 처리되지 않습니다.

  • 데이터 형식

    • 지원되는 Avro 버전을 사용하고 있는지 확인합니다. 지원되지 않는 형식은 처리되지 않습니다.

플랫폼 로그 정보

지원되는 Google Cloud 서비스는 자체 플랫폼 로그 집합을 생성하여 해당 서비스의 작동과 관련된 이벤트 및 활동을 캡처합니다. 이러한 플랫폼 로그에는 성공적인 작업, 오류, 경고, 기타 주목할 만한 이벤트를 비롯하여 서비스 내에서 발생하는 상황에 관한 세부정보가 포함됩니다.

플랫폼 로그는 Cloud Logging의 일부이며 동일한 기능을 공유합니다. 예를 들어 다음은 플랫폼 로그의 중요한 기능 목록입니다.

  • 로그는 일반적으로 추가 쿼리 및 필터링을 허용하는 JSON 객체로 구성됩니다.

  • 콘솔의 로깅을 사용하여 플랫폼 로그를 볼 수 있습니다.

  • 플랫폼 로그를 Cloud Monitoring 및 기타 모니터링 도구와 통합하여 대시보드, 알림, 기타 모니터링 메커니즘을 만들 수도 있습니다.

  • 로그 저장소에는 수집된 양과 보관 기간에 따라 비용이 발생합니다.

플랫폼 로그에 대한 자세한 내용은 Google Cloud Platform 로그를 참고하세요.

플랫폼 로그를 사용하기 위한 필수 역할 및 권한

시작하기 전에 Logging에 액세스할 수 있는지 확인합니다. 로그 뷰어 (roles/logging.viewer) Identity and Access Management (IAM) 역할이 필요합니다. Logging 액세스에 대한 자세한 내용은 IAM으로 액세스 제어를 참고하세요.

다음은 IAM 액세스 권한을 확인하고 부여하는 방법에 대한 설명입니다.

플랫폼 로그 사용 설정

플랫폼 로그는 기본적으로 가져오기 주제에 대해 사용 중지되어 있습니다. Cloud Storage 가져오기 주제를 만들거나 업데이트할 때 플랫폼 로그를 사용 설정할 수 있습니다.

플랫폼 로그를 사용 중지하려면 Cloud Storage 가져오기 주제를 업데이트합니다.

Cloud Storage 가져오기 주제를 만드는 동안 플랫폼 로그 사용 설정

Cloud Storage 가져오기 주제를 만들기 위한 기본 요건을 완료했는지 확인합니다.

플랫폼 로그가 사용 설정된 Cloud Storage 가져오기 주제를 만들려면 다음 단계를 따르세요.

콘솔

  1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

    주제로 이동

  2. 주제 만들기를 클릭합니다.

    주제 세부정보 페이지가 열립니다.

  3. 주제 ID 필드에 Cloud Storage 가져오기 주제의 ID를 입력합니다.

    주제 이름 지정에 대한 자세한 내용은 이름 지정 가이드라인을 참고하세요.

  4. 기본 구독 추가를 선택합니다.

  5. 수집 사용 설정을 선택합니다.

  6. Cloud Storage 가져오기 주제 만들기의 안내에 따라 처리 옵션을 지정합니다.
  7. 플랫폼 로그 사용 설정을 선택합니다.
  8. 다른 기본 설정은 유지합니다.
  9. 주제 만들기를 클릭합니다.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 플랫폼 로그를 사용 설정하려면 --ingestion-log-severity 플래그가 WARNING 이상으로 설정되어 있는지 확인합니다. gcloud pubsub topics create 명령어를 실행합니다.

    gcloud pubsub topics create TOPIC_ID\
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --ingestion-log-severity=WARNING

    다음을 바꿉니다.

    • TOPIC_ID: 주제의 이름 또는 ID

    • BUCKET_NAME: 기존 버킷의 이름을 지정합니다. 예를 들면 prod_bucket입니다. 버킷 이름에 프로젝트 ID를 포함해서는 안 됩니다. 버킷을 만들려면 버킷 만들기를 참조하세요.

    • INPUT_FORMAT: 처리되는 객체의 형식을 지정합니다. 이 값은 text, avro 또는 pubsub_avro입니다. 이러한 옵션에 관한 자세한 내용은 입력 형식을 참고하세요.

문제가 발생하면 Cloud Storage 가져오기 주제 문제 해결을 참고하세요.

Cloud Storage 가져오기 주제를 업데이트하는 동안 플랫폼 로그 사용 설정

다음 단계를 수행합니다.

콘솔

  1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

    주제로 이동

  2. Cloud Storage 가져오기 주제를 클릭합니다.

  3. 주제 세부정보 페이지에서 수정을 클릭합니다.

  4. 플랫폼 로그 사용 설정을 선택합니다.

  5. 업데이트를 클릭합니다.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 가져오기 주제의 설정이 손실되지 않도록 주제를 업데이트할 때마다 모든 설정을 포함해야 합니다. 누락된 항목이 있으면 Pub/Sub에서 설정을 원래 기본값으로 재설정합니다.

    플랫폼 로그를 사용 설정하려면 ingestion-log-severity가 WARNING로 설정되어 있는지 확인합니다. 다음 샘플에 언급된 모든 플래그를 사용하여 gcloud pubsub topics update 명령어를 실행합니다.

    gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=WARNING

    다음을 바꿉니다.

    • TOPIC_ID는 주제 ID 또는 이름입니다. 이 필드는 업데이트할 수 없습니다.

    • BUCKET_NAME: 기존 버킷의 이름을 지정합니다. 예를 들면 prod_bucket입니다. 버킷 이름에 프로젝트 ID를 포함해서는 안 됩니다.

    • INPUT_FORMAT: 처리되는 객체의 형식을 지정합니다. 이 값은 text, avro 또는 pubsub_avro입니다. 이러한 옵션에 대한 자세한 내용은 입력 형식을 참고하세요.

    • TEXT_DELIMITER: 텍스트 객체를 Pub/Sub 메시지로 분할하는 구분자를 지정합니다. 단일 문자여야 하며 INPUT_FORMAT가 text인 경우에만 설정해야 합니다. 기본값은 줄바꿈 문자 (\n)입니다.

      gcloud CLI를 사용하여 구분자를 지정할 때는 새 줄 \n과 같은 특수 문자의 처리에 각별히 주의하세요. 구분자가 올바르게 해석되도록 '\n' 형식을 사용하세요. 따옴표나 이스케이프 없이 \n를 사용하면 구분자가 "n"이 됩니다.

    • MINIMUM_OBJECT_CREATE_TIME: 객체를 처리하기 위해 객체가 생성된 최소 시간을 지정합니다. UTC 기준 YYYY-MM-DDThh:mm:ssZ 형식이어야 합니다. 예를 들면 2024-10-14T08:30:30Z입니다.

      0001-01-01T00:00:00Z과 9999-12-31T23:59:59Z 사이의 모든 날짜(과거 또는 미래)가 유효합니다.

    • MATCH_GLOB: 객체를 처리하기 위해 일치시킬 glob 패턴을 지정합니다. gcloud CLI를 사용하는 경우 * 문자가 포함된 일치 글러브에는 * 문자가 \*\*.txt 형식으로 이스케이프 처리된 형식이거나 전체 일치 글러브가 따옴표 "**.txt" 또는 '**.txt'로 묶여 있어야 합니다. glob 패턴에 지원되는 문법에 관한 자세한 내용은 Cloud Storage 문서를 참고하세요.

플랫폼 로그 사용 중지

다음 단계를 수행합니다.

콘솔

  1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

    주제로 이동

  2. Cloud Storage 가져오기 주제를 클릭합니다.

  3. 주제 세부정보 페이지에서 수정을 클릭합니다.

  4. 플랫폼 로그 사용 설정을 선택 해제합니다.

  5. 업데이트를 클릭합니다.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 가져오기 주제의 설정이 손실되지 않도록 주제를 업데이트할 때마다 모든 설정을 포함해야 합니다. 누락된 항목이 있으면 Pub/Sub에서 설정을 원래 기본값으로 재설정합니다.

    플랫폼 로그를 사용 중지하려면 ingestion-log-severity가 DISABLED로 설정되어 있는지 확인합니다. 다음 샘플에 언급된 모든 플래그를 사용하여 gcloud pubsub topics update 명령어를 실행합니다.

    gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=DISABLED

    다음을 바꿉니다.

    • TOPIC_ID는 주제 ID 또는 이름입니다. 이 필드는 업데이트할 수 없습니다.

    • BUCKET_NAME: 기존 버킷의 이름을 지정합니다. 예를 들면 prod_bucket입니다. 버킷 이름에 프로젝트 ID를 포함해서는 안 됩니다.

    • INPUT_FORMAT: 처리되는 객체의 형식을 지정합니다. 이 값은 text, avro 또는 pubsub_avro입니다. 이러한 옵션에 대한 자세한 내용은 입력 형식을 참고하세요.

    • TEXT_DELIMITER: 텍스트 객체를 Pub/Sub 메시지로 분할하는 구분자를 지정합니다. 단일 문자여야 하며 INPUT_FORMAT가 text인 경우에만 설정해야 합니다. 기본값은 줄바꿈 문자 (\n)입니다.

      gcloud CLI를 사용하여 구분자를 지정할 때는 새 줄 \n과 같은 특수 문자의 처리에 각별히 주의하세요. 구분자가 올바르게 해석되도록 '\n' 형식을 사용하세요. 따옴표나 이스케이프 없이 \n를 사용하면 구분자가 "n"이 됩니다.

    • MINIMUM_OBJECT_CREATE_TIME: 객체를 처리하기 위해 객체가 생성된 최소 시간을 지정합니다. UTC 기준 YYYY-MM-DDThh:mm:ssZ 형식이어야 합니다. 예를 들면 2024-10-14T08:30:30Z입니다.

      0001-01-01T00:00:00Z과 9999-12-31T23:59:59Z 사이의 모든 날짜(과거 또는 미래)가 유효합니다.

    • MATCH_GLOB: 객체를 처리하기 위해 일치시킬 glob 패턴을 지정합니다. gcloud CLI를 사용하는 경우 * 문자가 포함된 일치 글러브에는 * 문자가 \*\*.txt 형식으로 이스케이프 처리된 형식이거나 전체 일치 글러브가 따옴표 "**.txt" 또는 '**.txt'로 묶여 있어야 합니다. glob 패턴에 지원되는 문법에 관한 자세한 내용은 Cloud Storage 문서를 참고하세요.

플랫폼 로그 보기

Cloud Storage 가져오기 주제의 플랫폼 로그를 보려면 다음 단계를 따르세요.

Google Cloud 콘솔

  1. Google Cloud 콘솔에서 로그 탐색기로 이동합니다.

    로그 탐색기로 이동

  2. Google Cloud 프로젝트를 선택합니다.

  3. 필요한 경우 업그레이드 메뉴에서 기존 로그 뷰어를 로그 탐색기로 전환합니다.

  4. Cloud Storage 가져오기 주제의 항목만 표시되도록 로그를 필터링하려면 쿼리 필드에 resource.type="resource.type=pubsub_topic AND severity=WARNING을 입력하고 쿼리 실행을 클릭합니다.

  5. 쿼리 결과 창에서 시간 수정을 클릭하여 결과를 반환할 기간을 변경합니다.

로그 탐색기 사용에 대한 자세한 내용은 로그 탐색기 사용을 참고하세요.

gcloud CLI

gcloud CLI를 사용하여 Cloud Storage 가져오기 주제의 플랫폼 로그를 검색하려면 gcloud logging read 명령어를 사용합니다.

결과를 Cloud Storage 가져오기 주제의 플랫폼 로그로 제한하도록 필터를 지정합니다.

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

Cloud Logging API

entries.list Cloud Logging API 메서드를 사용합니다.

Cloud Storage 가져오기 주제의 플랫폼 로그만 포함되도록 결과를 필터링하려면 filter 필드를 사용합니다. 다음은 샘플 JSON 요청 객체입니다.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

플랫폼 로그 형식 보기 및 이해

다음 섹션에는 샘플 플랫폼 로그가 포함되어 있으며 플랫폼 로그의 필드에 대해 설명합니다.

모든 플랫폼 로그 관련 필드는 jsonPayload 객체 내에 포함되어 있습니다.

Avro 실패 

{
  "insertId": "1xnzx8md4768",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "objectGeneration": "1661148924738910",
      "bucket": "bucket_in_avro_format",
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "avroFailureReason": {}
    },
    "topic": "projects/interpod-p2-management/topics/avro_bucket_topic",
    "errorMessage": "Unable to parse the header of the object. The object won't be ingested."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "project_id": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}
로그 필드 설명
insertId 로그 항목의 고유 식별자입니다.
jsonPayload.@type 이벤트 유형을 식별합니다. 항상 type.googleapis.com/google.pubsub.v1.IngestionFailureEvent입니다.
jsonPayload.cloudStorageFailure.objectGeneration Cloud Storage 객체의 생성 번호입니다.
jsonPayload.cloudStorageFailure.bucket 객체가 포함된 Cloud Storage 버킷입니다.
jsonPayload.cloudStorageFailure.objectName Cloud Storage 객체의 이름입니다.
jsonPayload.cloudStorageFailure.avroFailureReason 더 구체적인 Avro 파싱 오류 세부정보를 포함합니다. 이 필드는 비워 둡니다.
jsonPayload.topic 메시지가 전송될 Pub/Sub 주제입니다.
jsonPayload.errorMessage 사람이 읽을 수 있는 오류 메시지입니다.
resource.type 리소스 유형입니다. 항상 pubsub_topic입니다.
resource.labels.project_id Google Cloud 프로젝트 ID입니다.
resource.labels.topic_id Pub/Sub 주제 ID입니다.
timestamp 로그 항목 생성 타임스탬프입니다.
severity 심각도 수준(WARNING)
logName 로그의 이름입니다.
receiveTimestamp 로그 항목 수신 타임스탬프입니다.

텍스트 실패 

{
  "insertId": "1kc4puoag",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "bucket": "bucket_in_text_format",
      "apiViolationReason": {},
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "objectGeneration": "1727990048026758"
    },
    "topic": "projects/interpod-p2-management/topics/large_text_bucket_topic",
    "errorMessage": "The message has exceeded the maximum allowed size of 10000000 bytes. The message won't be published."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "large_text_bucket_topic",
      "project_id": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}
로그 필드 설명
insertId 로그 항목의 고유 식별자입니다.
jsonPayload.@type 이벤트 유형을 식별합니다. 항상 type.googleapis.com/google.pubsub.v1.IngestionFailureEvent입니다.
jsonPayload.cloudStorageFailure.objectGeneration Cloud Storage 객체의 생성 번호입니다.
jsonPayload.cloudStorageFailure.bucket 객체가 포함된 Cloud Storage 버킷입니다.
jsonPayload.cloudStorageFailure.objectName Cloud Storage 객체의 이름입니다.
jsonPayload.cloudStorageFailure.apiViolationReason API 위반에 대한 세부정보를 포함합니다. 이 필드는 비워 둡니다.
jsonPayload.topic Pub/Sub 주제입니다.
jsonPayload.errorMessage 사람이 읽을 수 있는 메시지입니다.
resource.type 리소스 유형, 항상 pubsub_topic입니다.
resource.labels.project_id Google Cloud 프로젝트 ID입니다.
resource.labels.topic_id Pub/Sub 주제 ID입니다.
timestamp 로그 항목 생성 타임스탬프입니다.
severity 심각도 수준(WARNING)
logName 로그의 이름입니다.
receiveTimestamp Logging에서 로그 항목을 수신한 시간입니다.