지원되는 대상으로 로그 라우팅

이 문서에서는 Google Cloud 프로젝트에서 발생한 로그 항목을 지원되는 대상으로 라우팅하는 싱크를 만들고 관리하는 방법을 설명합니다.

싱크의 대상이 로그 항목이 발생한 Google Cloud 프로젝트의 로그 버킷이 아닌 경우 서비스 계정이 필요합니다. Cloud Logging은 이 서비스 계정을 자동으로 만들고 관리하지만 서비스 계정에 부여된 권한은 수정해야 할 수 있습니다. 여러 프로젝트에서 싱크가 사용하는 서비스 계정을 만들고 관리할 수 있습니다. 자세한 내용은 사용자 관리 서비스 계정으로 로그 싱크 구성을 참조하세요.

개요

싱크는 Cloud Logging에서 로그 항목을 라우팅하는 방법을 결정합니다. 싱크를 사용하면 로그 항목의 일부 또는 전부를 다음 대상으로 라우팅할 수 있습니다.

  • Cloud Logging 버킷: Cloud Logging에서 스토리지를 제공합니다. 로그 버킷은 여러 Google Cloud 프로젝트에서 수신한 로그 항목을 저장할 수 있습니다. 로그 버킷은 로그 항목이 시작된 동일한 프로젝트에 있거나 다른 프로젝트에 있을 수 있습니다. 로그 버킷에 저장된 로그 항목을 보는 방법에 대한 자세한 내용은 로그 쿼리 및 보기 개요 및 Cloud Logging 버킷으로 라우팅된 로그 보기를 참조하세요.

    로그 애널리틱스를 사용하도록 로그 버킷을 업그레이드한 후 연결된 데이터 세트를 만들어 Cloud Logging 데이터를 다른 데이터와 결합할 수 있습니다. 연결된 데이터 세트는 BigQuery Studio 및 Looker Studio 페이지에서 쿼리할 수 있는 읽기 전용 데이터 세트입니다.

  • BigQuery 데이터 세트: 쓰기 가능한 BigQuery 데이터 세트에서 로그 항목의 스토리지를 제공합니다. BigQuery 데이터 세트는 로그 항목이 시작하는 같은 프로젝트에 있거나 다른 프로젝트에 있을 수 있습니다. 저장된 로그 항목에서 빅데이터 분석 기능을 사용할 수 있습니다. BigQuery로 라우팅된 로그 항목을 보는 방법을 자세히 알아보려면 BigQuery로 라우팅된 로그 보기를 참조하세요.

  • Cloud Storage 버킷: Cloud Storage에서 로그 항목의 스토리지를 제공합니다. Cloud Storage 버킷은 로그 항목이 시작된 동일한 프로젝트에 있거나 다른 프로젝트에 있을 수 있습니다. 로그 항목은 JSON 파일로 저장됩니다. Cloud Storage로 라우팅된 로그 항목을 보는 방법을 자세한 내용은 Cloud Storage로 라우팅된 로그 보기를 참조하세요.

  • Pub/Sub 주제: 서드 파티 통합을 지원합니다. 로그 항목은 JSON 형식으로 지정된 후 Pub/Sub 주제로 라우팅됩니다. 주제는 로그 항목이 시작된 동일한 프로젝트에 있거나 다른 프로젝트에 있을 수 있습니다. Pub/Sub로 라우팅된 로그 항목을 보는 방법을 자세한 내용은 Pub/Sub로 라우팅된 로그 보기를 참조하세요.

  • Google Cloud 프로젝트: 로그 항목을 다른 Google Cloud 프로젝트로 라우팅합니다. 이 구성에서는 대상 프로젝트의 싱크가 로그 항목을 처리합니다.

싱크는 Google Cloud 프로젝트, 결제 계정, 폴더, 조직 등 지정된 Google Cloud 리소스에 속합니다. 리소스가 로그 항목을 수신하면 리소스의 모든 싱크가 로그 항목을 처리합니다. 로그 항목이 싱크의 필터와 일치하면 로그 항목이 싱크의 대상으로 라우팅됩니다.

일반적으로 싱크는 리소스에서 발생한 로그 항목만 라우팅합니다. 하지만 폴더와 조직의 경우 폴더 또는 조직의 로그 항목과 포함된 리소스를 라우팅하는 집계 싱크를 만들 수 있습니다. 이 문서에서는 집계 싱크에 대해 설명하지 않습니다. 자세한 내용은 조직 수준 로그를 취합하여 지원되는 목적지로 라우팅을 참조하세요.

Google Cloud 콘솔, Cloud Logging API, Google Cloud CLI를 사용하여 싱크를 만들고 관리할 수 있습니다. 다음과 같은 경우에는 Google Cloud 콘솔을 사용하는 것이 좋습니다.

  • 로그 라우터 페이지에는 모든 싱크가 나열되며 싱크를 관리하는 옵션이 제공됩니다.
  • 싱크를 만들 때 싱크의 필터와 일치하는 로그 항목을 미리 볼 수 있습니다.
  • 싱크를 만들 때 싱크 대상을 구성할 수 있습니다.
  • 일부 승인 단계는 자동으로 완료됩니다.

시작하기 전에

이 문서의 안내에서는 Google Cloud 프로젝트 수준에서 싱크를 만들고 관리하는 방법을 설명합니다. 동일한 절차를 사용하여 조직, 폴더 또는 결제 계정에서 발생한 로그 항목을 라우팅하는 싱크를 만들 수 있습니다.

시작하려면 다음 안내를 따르세요.

  1. Enable the Cloud Logging API.

    Enable the API

  2. Google Cloud 프로젝트에 로그 탐색기에서 볼 수 있는 로그 항목이 포함되어 있는지 확인합니다.

  3. 싱크를 생성, 수정 또는 삭제하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 로그 구성 작성자(roles/logging.configWriter) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

    커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

    IAM 역할 부여에 대한 자세한 내용은 Logging 액세스 제어 가이드를 참조하세요.

  4. 지원되는 대상에 리소스가 있거나 이를 만들 수 있어야 합니다.

    로그 항목을 대상으로 라우팅하려면 싱크를 만들기 전에 대상이 있어야 합니다. 모든 조직의 모든 Google Cloud 프로젝트에서 대상을 만들 수 있습니다.

  5. 싱크를 만들기 전에 싱크 대상에 적용되는 제한사항을 검토하세요. 자세한 내용은 이 문서의 대상 제한사항 섹션을 참조하세요.

  6. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    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.

    REST

    로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참고하세요.

싱크 만들기

Google Cloud 프로젝트에서 싱크를 만드는 방법은 다음과 같습니다. 동일한 절차를 사용하여 조직, 폴더 또는 결제 계정에서 발생한 로그 항목을 라우팅할 수 있습니다.

  • Google Cloud 프로젝트당 최대 200개의 싱크를 만들 수 있습니다.
  • 싱크 필터에 민감한 정보를 넣지 마세요. 싱크 필터는 서비스 데이터로 취급됩니다.
  • Cloud Storage 버킷에 대한 새 싱크가 로그 항목 라우팅을 시작하는 데 몇 시간이 걸릴 수 있습니다. Cloud Storage로의 싱크가 매시간 처리되지만 다른 대상 유형은 실시간으로 처리됩니다.

  • 싱크는 읽기 전용인 연결된 BigQuery 데이터 세트로 로그 항목을 라우팅할 수 없습니다. 로그 항목을 BigQuery로 라우팅하려면 대상 데이터 세트에서 쓰기가 사용 설정되어 있어야 합니다.

  • 싱크는 BigQuery 데이터 세트의 스키마를 정의하지 않습니다. 대신 BigQuery에서 수신한 첫 번째 로그 항목은 대상 테이블의 스키마를 결정합니다. 자세한 내용은 라우팅된 로그의 BigQuery 스키마를 참조하세요.

  • 싱크 대상에서 로그 항목을 확인하는 방법에 대한 자세한 내용은 Cloud Logging 버킷으로 라우팅된 로그 보기를 참조하세요.

  • 라우팅된 로그 항목의 수와 볼륨을 보려면 logging.googleapis.com/exports/ 측정항목을 확인하세요.

  • 로그 탐색기는 쿼리 창에 표시된 문에 논리곱 제한자 AND를 암시적으로 추가합니다. 예를 들어 첫 번째 줄이 resource.type = "gce_instance"이고 두 번째 줄이 severity >= "ERROR"이면 쿼리는 resource.type = "gce_instance" AND severity >= "ERROR"입니다. 로그 탐색기에 표시된 쿼리를 다른 컨텍스트(예: 싱크의 포함 또는 제외 필터)에 사용하려면 쿼리를 수정하고 논리곱 제한자를 추가해야 합니다. 자세한 내용은 Logging 쿼리 언어를 참조하세요.

싱크를 만들려면 다음을 수행합니다.

콘솔

  1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

    로그 라우터로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 라우팅할 로그 항목이 생성된 Google Cloud 프로젝트를 선택합니다.

    예를 들어 Project-A라는 프로젝트에서 Project-B라는 프로젝트의 로그 버킷으로 데이터 액세스 로그 항목을 라우팅하려면 Project-A를 선택합니다.

  3. 싱크 만들기를 선택합니다.

  4. 싱크 세부정보 패널에서 다음 세부정보를 입력합니다.

    • 싱크 이름: 싱크의 식별자를 제공합니다. 싱크를 만든 후에는 싱크 이름을 바꿀 수 없지만 이를 삭제하고 새 싱크를 만들 수 있습니다.

    • 싱크 설명(선택사항): 싱크의 목적 또는 사용 사례를 설명합니다.

  5. 싱크 대상 패널에서 싱크 서비스 선택 메뉴를 사용하여 싱크 서비스와 대상을 선택합니다. 다음 중 하나를 수행합니다.

    • 동일한 Google Cloud 프로젝트에 있는 서비스로 로그 항목을 라우팅하려면 다음 옵션 중 하나를 선택합니다.

      • Cloud Logging 버킷: Logging 버킷을 선택하거나 만듭니다.
      • BigQuery 데이터 세트: 라우팅된 로그 항목을 수신할 쓰기 가능한 데이터 세트를 선택하거나 만듭니다. 파티션을 나눈 테이블도 사용할 수 있습니다.
      • Cloud Storage 버킷: 라우팅된 로그 항목을 수신할 특정 Cloud Storage 버킷을 선택하거나 만듭니다.
      • Pub/Sub 주제: 라우팅된 로그 항목을 수신할 특정 주제를 선택하거나 만듭니다.
      • Splunk: Splunk 서비스에 대한 Pub/Sub 주제를 선택합니다.

    • 로그 항목을 다른 Google Cloud 프로젝트로 라우팅하려면 Google Cloud 프로젝트를 선택한 후 대상의 정규화된 이름을 입력합니다. 구문에 대한 자세한 내용은 대상 경로 형식을 참조하세요.

    • 다른 Google Cloud 프로젝트에 있는 서비스로 로그 항목을 라우팅하려면 다음 단계를 따르세요.

      1. 기타 리소스를 선택합니다.
      2. 대상의 정규화된 이름을 입력합니다. 구문에 대한 자세한 내용은 대상 경로 형식을 참조하세요.

  6. 포함할 로그 항목을 지정합니다.

    1. 싱크에 포함할 로그 선택 패널로 이동합니다.

    2. 포함 필터 빌드 필드에서 포함하려는 로그 항목과 일치하는 필터 표현식을 입력합니다. 필터를 작성하는 문법에 대한 자세한 내용은 Logging 쿼리 언어를 참조하세요.

      필터를 설정하지 않으면 선택한 리소스의 모든 항목이 대상으로 라우팅됩니다.

      예를 들어 모든 데이터 액세스 로그 항목을 Logging 버킷으로 라우팅하려면 다음 필터를 사용하면 됩니다.

      log_id("cloudaudit.googleapis.com/data_access") OR log_id("externalaudit.googleapis.com/data_access")

      필터 길이는 20,000자(영문 기준)를 초과할 수 없습니다.

    3. 올바른 필터를 입력했는지 확인하려면 미리보기 로그를 선택합니다. 필터가 미리 채워진 새 탭에서 로그 탐색기가 열립니다.

  7. (선택사항) 포함된 로그 항목 중 일부를 삭제하도록 제외 필터를 구성합니다.

    1. 싱크를 필터링할 로그 선택 패널로 이동합니다.

    2. 제외 필터 이름 필드에 이름을 입력합니다.

    3. 제외 필터 빌드 필드에서 제외할 로그 항목과 일치하는 필터 표현식을 입력합니다. 또한 sample 함수를 사용하여 제외할 로그 항목 부분을 선택할 수 있습니다.

    싱크당 최대 50개의 제외 필터를 만들 수 있습니다. 필터의 길이는 20,000자를 초과할 수 없습니다.

  8. 싱크 만들기를 선택합니다.

  9. 싱크의 서비스 계정에 싱크의 대상에 로그 항목을 쓸 수 있는 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

gcloud

싱크를 만들려면 다음을 수행합니다.

  1. 다음 gcloud logging sinks create 명령어를 실행합니다.

    gcloud logging sinks create SINK_NAME SINK_DESTINATION

    명령어를 실행하기 전에 다음을 바꿉니다.

    • SINK_NAME: 로그 싱크의 이름. 싱크를 만든 후에는 싱크 이름을 변경할 수 없습니다.

    • SINK_DESTINATION: 로그 항목을 라우팅하려는 서비스 또는 프로젝트. 대상 경로 형식에 설명된 대로 SINK_DESTINATION을 적절한 경로로 설정합니다.

      예를 들어 싱크 대상이 Pub/Sub 주제이면 SINK_DESTINATION은 다음과 같습니다.

      pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

    다음 옵션을 제공할 수도 있습니다.

    • --log-filter: 이 옵션을 사용하여 싱크에 포함하려는 로그 항목과 일치하는 필터를 설정합니다. 포함 필터의 값을 제공하지 않으면 이 필터는 모든 로그 항목과 일치합니다.
    • --exclusion: 이 옵션을 사용하여 라우팅에서 싱크를 제외하려는 로그 항목에 대해 제외 필터를 설정합니다. 또한 sample 함수를 사용하여 제외할 로그 항목 부분을 선택할 수 있습니다. 이 옵션은 반복 가능합니다. 싱크당 최대 50개까지 제외 필터를 만들 수 있습니다.
    • --description: 이 옵션을 사용하여 싱크의 목적이나 사용 사례를 설명합니다.

    예를 들어 Logging 버킷에 대해 싱크를 만들려는 경우 명령어가 다음과 같습니다.

    gcloud logging sinks create my-sink logging.googleapis.com/projects/myproject123/locations/global/buckets/my-bucket \
 --log-filter='logName="projects/myproject123/logs/matched"' --description="My first sink"

    Google Cloud CLI를 사용하여 싱크를 생성하는 방법에 대한 자세한 내용은 gcloud logging sinks 참조를 확인하세요.

  2. 명령어 응답에 "writerIdentity"라는 라벨이 지정된 JSON 키가 포함된 경우 싱크의 서비스 계정에 싱크 대상에 대한 쓰기 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

    응답에 "writerIdentity"라는 라벨이 지정된 JSON 키가 포함되지 않은 경우 대상 권한을 설정할 필요가 없습니다.

REST

  1. Google Cloud 프로젝트에서 로깅 싱크를 만들려면 Logging API에서 projects.sinks.create를 사용합니다. LogSink 객체에서 메서드 요청 본문에 적절한 필수 값을 제공합니다.

    • name: 싱크의 식별자. 싱크를 만든 후에는 싱크 이름을 바꿀 수 없지만 이를 삭제하고 새 싱크를 만들 수 있습니다.

    • destination: 로그 항목을 라우팅하려는 서비스 및 대상. 로그 항목을 다른 프로젝트 또는 다른 프로젝트에 있는 대상으로 라우팅하려면 대상 경로 형식에 설명된 대로 destination 필드를 적절한 경로로 설정합니다.

      예를 들어 싱크 대상이 Pub/Sub 주제인 경우 destination은 다음과 같습니다.

      pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

  2. LogSink 객체에서 적절한 선택적 정보를 제공합니다.

    • filter: 싱크에 포함할 로그 항목과 일치하는 filter 필드를 설정합니다. 필터를 설정하지 않으면 Google Cloud 프로젝트의 모든 로그가 대상으로 라우팅됩니다. 필터의 길이는 20,000자를 초과할 수 없습니다.
    • exclusions: 싱크에서 제외하려는 로그 항목과 일치하도록 이 필드를 설정합니다. 또한 sample 함수를 사용하여 제외할 로그 항목 부분을 선택할 수 있습니다. 싱크당 최대 50개의 제외 필터를 만들 수 있습니다.
    • description: 이 필드를 설정하여 싱크의 목적 또는 사용 사례를 기술합니다.

  3. projects.sinks.create를 호출하여 싱크를 만듭니다.

  4. API 응답에 "writerIdentity"라는 라벨이 지정된 JSON 키가 포함된 경우 싱크의 서비스 계정에 싱크 대상에 대한 쓰기 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

    API 응답에 "writerIdentity"라는 라벨이 지정된 JSON 키가 포함되지 않은 경우에는 대상 권한을 설정할 필요가 없습니다.

Logging API를 사용하여 싱크 만들기에 대한 자세한 내용은 LogSink 참조를 확인하세요.

오류 알림을 받으면 라우팅 및 싱크 문제 해결을 참조하세요.

대상 경로 형식

로그 항목을 다른 프로젝트의 서비스로 라우팅하는 경우 싱크에 서비스의 정규화된 이름을 제공해야 합니다. 마찬가지로 로그 항목을 다른 Google Cloud 프로젝트로 라우팅하는 경우 싱크에 대상 프로젝트의 정규화된 이름을 제공해야 합니다.

  • Cloud Logging 로그 버킷:

    logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

  • 다른 Google Cloud 프로젝트:

    logging.googleapis.com/projects/DESTINATION_PROJECT_ID

  • BigQuery 데이터 세트:

    bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID

  • Cloud Storage:

    storage.googleapis.com/BUCKET_NAME

  • Pub/Sub 주제:

    pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

싱크 관리

싱크가 생성된 후 여기에서 다음 작업을 수행할 수 있습니다. 싱크에서 변경사항을 적용하는 데 몇 분 정도 걸릴 수 있습니다.

  • 세부정보 보기
  • 업데이트

  • 사용 중지

    • _Required 싱크는 사용 중지할 수 없습니다.
    • _Default 싱크를 사용 중지하여 로그 항목이 _Default Logging 버킷으로 라우팅되지 않도록 할 수 있습니다.
    • 조직에서 만든 새 Google Cloud 프로젝트나 폴더의 _Default 싱크를 사용 중지하려면 기본 리소스 설정을 구성하는 것이 좋습니다.

  • 삭제

    • _Default 또는 _Required 싱크는 삭제할 수 없습니다.
    • 싱크를 삭제하면 더 이상 로그 항목이 라우팅되지 않습니다.
    • 싱크에 전용 서비스 계정이 있으면 싱크를 삭제할 때 서비스 계정도 삭제됩니다. 2023년 5월 22일 이전에 생성된 싱크에는 전용 서비스 계정이 포함됩니다. 2023년 5월 22일 이후에 생성된 싱크에는 공유 서비스 계정이 포함됩니다. 싱크를 삭제해도 공유 서비스 계정이 삭제되지 않습니다.

  • 문제 해결 실패

  • 로그 볼륨 및 오류율 보기

Google Cloud 프로젝트에서 싱크를 관리하는 방법은 다음과 같습니다. Google Cloud 프로젝트 대신 결제 계정, 폴더, 조직을 지정할 수 있습니다.

콘솔

  1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

    로그 라우터로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 툴바에서 싱크가 포함된 리소스를 선택합니다. 리소스는 프로젝트, 폴더, 조직 또는 결제 계정일 수 있습니다.

로그 라우터 페이지에는 선택한 리소스의 싱크가 표시됩니다. 각 테이블 행에는 싱크의 속성에 대한 정보가 포함됩니다.

  • 사용 설정: 싱크 상태가 사용 설정 또는 사용 중지되었는지를 나타냅니다.
  • 유형: 싱크의 대상 서비스입니다. 예를 들면 Cloud Logging bucket입니다.
  • 이름: 싱크가 생성될 때 제공된 대로의 싱크 식별자입니다. 예를 들면 _Default입니다.
  • 설명: 싱크가 생성될 때 제공된 대로의 싱크 설명입니다.
  • 대상: 라우팅된 로그 항목이 전송되는 대상의 전체 이름입니다.
  • 생성됨: 싱크가 생성된 날짜 및 시간입니다.
  • 최종 업데이트됨: 싱크가 마지막으로 수정된 날짜 및 시간입니다.

각 테이블 행에 대해 작업 더보기 메뉴에서 다음 옵션을 제공합니다.

  • 싱크 세부정보 보기: 싱크의 이름, 설명, 대상 서비스, 대상, 포함 필터, 제외 필터를 표시합니다. 수정을 선택하면 싱크 수정 패널이 열립니다.
  • 싱크 수정: 싱크 매개변수를 업데이트할 수 있는 싱크 수정 패널이 열립니다.
  • 싱크 사용 중지: 싱크를 사용 중지하고 싱크의 대상 위치로 로그 항목 라우팅을 중지합니다. 싱크 사용 중지에 대한 자세한 내용은 로그 버킷에 로그 저장 중지를 참조하세요.
  • 싱크 사용 설정: 사용 중지된 싱크를 사용 설정하고 싱크의 대상 위치로 로그 항목 라우팅을 다시 시작합니다.
  • 싱크 삭제: 싱크를 삭제하고 싱크의 대상 위치로 로그 항목 라우팅을 중지할 수 있습니다.
  • 싱크 문제 해결: 싱크로 오류 문제를 해결할 수 있는 로그 탐색기가 열립니다.
  • 싱크 로그 볼륨 및 오류율 보기: 싱크에서 데이터를 보고 분석할 수 있는 측정항목 탐색기를 엽니다.

열을 기준으로 표를 정렬하려면 열 이름을 선택합니다.

gcloud

  • Google Cloud 프로젝트의 싱크 목록을 보려면 Logging API 메서드 projects.sinks.list에 해당하는 gcloud logging sinks list 명령어를 사용하세요.

    gcloud logging sinks list

    집계 싱크 목록을 보려면 적절한 옵션을 사용하여 싱크가 포함된 리소스를 지정합니다. 예를 들어 조직 수준에서 싱크를 만든 경우 --organization=ORGANIZATION_ID 옵션을 사용하여 조직의 싱크를 나열합니다.

  • 싱크를 설명하려면 gcloud logging sinks describe 명령어를 사용합니다. 이 명령어는 Logging API 메서드 projects.sinks.get에 해당합니다.

    gcloud logging sinks describe SINK_NAME

  • 싱크를 업데이트하려면 gcloud logging sinks update 명령어를 사용합니다. 이 명령어는 API 메서드 projects.sink.update에 해당합니다.

    대상, 필터, 설명을 변경하기 위해 또는 싱크를 사용 중지하거나 다시 사용 설정하기 위해 싱크를 업데이트할 수 있습니다.

    gcloud logging sinks update SINK_NAME NEW_DESTINATION --log-filter=NEW_FILTER

    해당 파트가 변경되지 않으면 NEW_DESTINATION 또는 --log-filter를 생략합니다.

    예를 들어 my-project-sink라는 싱크 대상을 my-second-gcs-bucket이라는 새로운 Cloud Storage 버킷 대상으로 업데이트할 때 명령어는 다음과 같습니다.

    gcloud logging sinks update  my-project-sink storage.googleapis.com/my-second-gcs-bucket

  • 싱크를 사용 중지하려면 gcloud logging sinks update 명령어를 사용합니다. 이 명령어는 API 메서드 projects.sink.update에 해당하며 --disabled 옵션을 포함합니다.

    gcloud logging sinks update SINK_NAME --disabled

    싱크를 다시 사용 설정하려면 gcloud logging sinks update 명령어를 사용하고 --disabled 옵션을 삭제하고 --no-disabled 옵션을 포함합니다.

    gcloud logging sinks update SINK_NAME --no-disabled

  • 싱크를 삭제하려면 gcloud logging sinks delete 명령어를 사용합니다. 이 명령어는 API 메서드 projects.sinks.delete에 해당합니다.

    gcloud logging sinks delete SINK_NAME

    Google Cloud CLI를 사용하여 싱크를 관리하는 방법에 대한 자세한 내용은 gcloud logging sinks 참조를 확인하세요.

REST

  • Google Cloud 프로젝트의 싱크를 보려면 projects.sinks.list를 호출합니다.

  • 싱크의 세부정보를 보려면 projects.sinks.get을 호출합니다.

  • 싱크를 업데이트하려면 projects.sink.update를 호출합니다.

    싱크의 대상, 필터, 설명을 업데이트할 수 있습니다. 싱크를 사용 중지하거나 다시 사용 설정할 수도 있습니다.

  • 싱크를 사용 중지하려면 LogSink 객체의 disabled 필드를 true로 설정한 다음 projects.sink.update를 호출합니다.

    싱크를 다시 사용 설정하려면 LogSink 객체의 disabled 필드를 false로 설정한 다음 projects.sink.update를 호출합니다.

  • 싱크를 삭제하려면 projects.sinks.delete를 호출합니다.

    Logging API를 사용하여 싱크를 관리하는 방법에 관한 자세한 내용은 LogSink 참조를 확인하세요.

로그 버킷에 로그 항목 저장 중지

_Default 싱크와 모든 사용자 정의 싱크를 사용 중지할 수 있습니다. 싱크를 사용 중지하면 싱크가 대상으로의 로그 항목 라우팅을 중지합니다. 예를 들어 _Default 싱크를 사용 중지하면 _Default 버킷으로 라우팅되는 로그 항목이 없습니다. 이전에 저장된 모든 로그 항목이 버킷의 보관 기간을 완료했으면 _Default 버킷이 비워집니다.

다음 안내는 로그 항목을 _Default 로그 버킷으로 라우팅하는 Google Cloud 프로젝트 싱크를 사용 중지하는 방법을 보여줍니다.

콘솔

  1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

    로그 라우터로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 로그 항목을 _Default 로그 버킷으로 라우팅하는 모든 싱크를 찾으려면 싱크를 대상별로 필터링한 후 _Default를 입력합니다.

  3. 싱크마다 메뉴를 선택한 후 싱크 사용 중지를 선택합니다.

    이제 싱크가 중지되고 Google Cloud 프로젝트 싱크가 더 이상 로그 항목을 _Default 버킷으로 라우팅하지 않습니다.

사용 중지된 싱크를 다시 사용 설정하고 싱크 대상으로 로그 항목 라우팅을 다시 시작하려면 다음을 수행합니다.

  1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

    로그 라우터로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 로그 항목을 _Default 로그 버킷으로 라우팅하는 모든 싱크를 찾으려면 싱크를 대상별로 필터링한 후 _Default를 입력합니다.
  3. 싱크마다 메뉴를 선택한 후 싱크 사용 설정을 선택합니다.

gcloud

  1. Google Cloud 프로젝트의 싱크 목록을 보려면 Logging API 메서드 projects.sinks.list에 해당하는 gcloud logging sinks list 명령어를 사용하세요.

    gcloud logging sinks list

  2. _Default 로그 버킷으로 라우팅하는 싱크를 식별합니다. 대상 이름 보기를 포함하여 싱크를 설명하려면 gcloud logging sinks describe 명령어를 사용합니다. 이 명령어는 Logging API 메서드 projects.sinks.get에 해당합니다.

    gcloud logging sinks describe SINK_NAME

  3. gcloud logging sinks update 명령어를 실행하고 --disabled 옵션을 포함합니다. 예를 들어 _Default 싱크를 사용 중지하려면 다음 명령어를 사용합니다.

    gcloud logging sinks update _Default  --disabled

    이제 _Default 싱크가 사용 중지되고, 더 이상 로그 항목을 _Default 로그 버킷으로 라우팅하지 않습니다.

Google Cloud 프로젝트에서 _Default 버킷으로 라우팅하는 다른 싱크를 사용 중지하려면 이전 단계를 반복합니다.

싱크를 다시 사용 설정하려면 gcloud logging sinks update 명령어를 사용하고 --disabled 옵션을 삭제하고 --no-disabled 옵션을 포함합니다.

gcloud logging sinks update _Default  --no-disabled

REST

  1. Google Cloud 프로젝트의 싱크를 보려면 Logging API 메서드 projects.sinks.list를 호출합니다.

    _Default 버킷으로 라우팅하는 싱크를 식별합니다.

  2. 예를 들어 _Default 싱크를 사용 중지하려면 LogSink 객체의 disabled 필드를 true로 설정한 다음 projects.sink.update를 호출합니다.

    이제 _Default 싱크가 사용 중지되고, 더 이상 로그 항목을 _Default 버킷으로 라우팅하지 않습니다.

Google Cloud 프로젝트에서 _Default 버킷으로 라우팅하는 다른 싱크를 사용 중지하려면 이전 단계를 반복합니다.

싱크를 다시 사용 설정하려면 LogSink 객체의 disabled 필드를 false로 설정한 다음 projects.sink.update를 호출합니다.

대상 권한 설정

이 섹션에서는 Logging에 Identity and Access Management 권한을 부여하여 싱크의 대상에 로그 항목을 작성할 수 있는 방법을 설명합니다. Logging 역할과 권한 전체 목록은 액세스 제어를 참조하세요.

Cloud Logging은 필요한 서비스 계정이 이미 존재하지 않는 한 싱크가 생성될 때 리소스의 공유 서비스 계정을 만듭니다. 기본 리소스의 모든 싱크에 동일한 서비스 계정이 사용되므로 서비스 계정이 있을 수 있습니다. 리소스는 Google Cloud 프로젝트, 조직, 폴더 또는 결제 계정이 될 수 있습니다.

싱크의 작성자 ID는 해당 싱크와 연결된 서비스 계정의 식별자입니다. 로그 항목이 발생한 동일한 Google Cloud 프로젝트의 로그 버킷에 쓰는 싱크를 제외한 모든 싱크에는 작성자 ID가 있습니다. 후자의 구성에는 서비스 계정이 필요하지 않으므로 싱크의 작성자 ID 필드가 콘솔에 None으로 표시됩니다. API 및 Google Cloud CLI 명령어는 작성자 ID를 보고하지 않습니다.

다음 안내는 프로젝트, 폴더, 조직, 결제 계정에 적용됩니다.

콘솔

  1. 대상이 포함된 Google Cloud 프로젝트에 대한 소유자 액세스 권한이 있어야 합니다. 싱크의 대상에 소유자 액세스 권한이 없으면 프로젝트 소유자에게 작성자 ID를 주 구성원으로 추가하도록 요청하세요.

  2. 새로운 싱크에서 싱크의 작성자 ID(이메일 주소)를 가져오려면 다음을 수행하세요.

    1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

      로그 라우터로 이동

      검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

    2. 툴바에서 싱크가 포함된 프로젝트를 선택합니다.
    3. 메뉴를 선택한 다음 싱크 세부정보 보기를 선택합니다. 작성자 ID가 싱크 세부정보 패널에 표시됩니다.

  3. writerIdentity 필드 값에 이메일 주소가 포함된 경우 다음 단계로 진행합니다. 값이 None이면 싱크에 대한 대상 권한을 구성할 필요가 없습니다.

  4. 싱크의 작성자 ID를 클립보드에 복사합니다.

  5. 대상이 다른 프로젝트의 서비스이거나 다른 프로젝트인 경우 툴바에서 대상 프로젝트를 선택합니다.

  6. 서비스 계정을 대상 프로젝트에서 IAM 주 구성원으로 추가합니다.

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

      IAM으로 이동합니다.

      검색창을 사용하여 이 페이지를 찾은 경우 부제목이 IAM 및 관리자인 결과를 선택합니다.

    2. 대상 프로젝트를 선택합니다.

    3. 액세스 권한 부여를 클릭합니다.

    4. 서비스 계정에 필요한 IAM 역할을 부여합니다.

      • 대상 위치가 Cloud Storage이면 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 스토리지 객체 생성자 역할(roles/storage.objectCreator)을 부여합니다.
      • 대상 위치가 BigQuery이면 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 BigQuery 데이터 편집자 역할(roles/bigquery.dataEditor)을 부여합니다.
      • Splunk를 포함한 Pub/Sub 대상의 경우, IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후Pub/Sub 게시자 역할(roles/pubsub.publisher)을 부여합니다.
      • 다른 Google Cloud 프로젝트에 있는 Logging 버킷 대상의 경우 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 로그 버킷 작성자 역할(roles/logging.bucketWriter)을 부여합니다.
      • Google Cloud 프로젝트 대상의 경우 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 로그 작성자 역할(roles/logging.logWriter)을 부여합니다. 특히 주 구성원에게는 logging.logEntries.route 권한이 필요합니다.

gcloud

  1. 대상이 포함된 Google Cloud 프로젝트에 대한 소유자 액세스 권한이 있어야 합니다. 싱크의 대상에 소유자 액세스 권한이 없으면 프로젝트 소유자에게 작성자 ID를 주 구성원으로 추가하도록 요청하세요.

  2. 싱크 writerIdentity 필드에서 서비스 계정을 가져옵니다.

    gcloud logging sinks describe SINK_NAME

  3. 권한을 수정할 싱크를 찾고 싱크 세부정보에 writerIdentity 줄이 포함된 경우 다음 단계로 진행합니다. 세부정보에 writerIdentity 필드가 포함되지 않으면 싱크에 대한 대상 권한을 구성할 필요가 없습니다.

    서비스 계정의 작성자 ID는 다음과 유사합니다.

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  4. 서비스 계정을 대상 프로젝트에서 IAM 주 구성원으로 추가합니다.

    다음 명령어를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 식별자입니다.
    • PRINCIPAL: 역할을 부여할 주 구성원의 식별자입니다. 주 구성원 식별자는 일반적으로 PRINCIPAL-TYPE:ID 형식입니다. 예를 들면 user:my-user@example.com입니다. PRINCIPAL 형식 전체 목록은 주 구성원 식별자를 참조하세요.

    • ROLE: IAM 역할

      • 대상 위치가 Cloud Storage이면 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 스토리지 객체 생성자 역할(roles/storage.objectCreator)을 부여합니다.
      • 대상 위치가 BigQuery이면 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 BigQuery 데이터 편집자 역할(roles/bigquery.dataEditor)을 부여합니다.
      • Splunk를 포함한 Pub/Sub 대상의 경우, IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후Pub/Sub 게시자 역할(roles/pubsub.publisher)을 부여합니다.
      • 다른 Google Cloud 프로젝트에 있는 Logging 버킷 대상의 경우 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 로그 버킷 작성자 역할(roles/logging.bucketWriter)을 부여합니다.
      • Google Cloud 프로젝트 대상의 경우 IAM을 사용하여 싱크의 작성자 ID를 주 구성원으로 추가한 후 로그 작성자 역할(roles/logging.logWriter)을 부여합니다. 특히 주 구성원에게는 logging.logEntries.route 권한이 필요합니다.

    gcloud projects add-iam-policy-binding 명령어를 실행합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

서비스 계정에 역할을 부여하려면 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하는 것이 좋습니다.

대상 제한사항

이 섹션에서는 대상별 제한사항을 설명합니다.

  • 다른 Google Cloud 프로젝트의 로그 버킷으로 로그 항목을 라우팅하는 경우 Error Reporting이 이러한 로그 항목을 분석하지 않습니다. 자세한 내용은 Error Reporting 개요를 참조하세요.
  • 로그 항목을 BigQuery로 라우팅하는 경우 BigQuery 데이터 세트에서 쓰기가 사용 설정되어야 합니다. 읽기 전용인 연결된 데이터 세트로 로그 항목을 라우팅할 수는 없습니다.

  • 로그 항목을 다른 Google Cloud 프로젝트로 라우팅할 때 다음 제한사항이 적용됩니다.

    • 하나의 홉 제한이 있습니다.

      예를 들어 프로젝트 A에서 프로젝트 B로 로그 항목을 라우팅하는 경우 프로젝트 B의 로그 항목을 다른 프로젝트로 라우팅할 수 없습니다.

    • 감사 로그는 대상 프로젝트의 _Required 로그 버킷으로 라우팅되지 않습니다.

      예를 들어 프로젝트 A에서 프로젝트 B로 로그 항목을 라우팅하는 경우 프로젝트 A의 _Required 로그 버킷에 프로젝트 A의 감사 로그가 포함됩니다. A 프로젝트의 감사 로그가 B 프로젝트로 라우팅되지 않습니다. 이러한 로그 항목을 라우팅하려면 대상이 로그 버킷인 싱크를 만듭니다.

    • 대상 프로젝트가 다른 폴더 또는 조직에 있는 경우 해당 폴더 또는 조직의 집계된 싱크는 로그 항목을 라우팅하지 않습니다.

      예를 들어 프로젝트 A가 X 폴더에 있다고 가정해 보겠습니다. 로그 항목이 프로젝트 A에서 발생하면 로그 항목은 X 폴더의 집계된 싱크와 프로젝트 A의 싱크에서 처리됩니다. 이제 프로젝트 A에 로그 항목을 Y 폴더에 있는 프로젝트 B로 라우팅하는 싱크가 포함되어 있다고 가정해 보겠습니다. A 프로젝트의 로그 항목은 B 프로젝트의 싱크를 통과하지만 Y 폴더의 집계 싱크는 통과하지 않습니다.

  • 집계된 싱크를 사용하여 프로젝트로 라우팅된 로그 항목을 로그 탐색기로 보려면 범위 미세 조정 필드를 저장소 범위로 설정한 다음 이러한 로그 항목에 액세스할 수 있는 로그 뷰를 선택합니다.

코드 샘플

클라이언트 라이브러리 코드를 사용하여 선택한 언어로 싱크를 구성하려면 Logging 클라이언트 라이브러리: 로그 싱크를 참조하세요.

필터 예시

다음은 싱크를 만들 때 특히 유용한 몇 가지 필터 예시입니다. 포함 필터 및 제외 필터를 만들 때 유용할 수 있는 추가 예시는 샘플 쿼리를 참조하세요.

_Default 싱크 필터 복원

_Default 싱크의 필터를 수정한 경우 이 싱크를 원래 구성으로 복원해야 할 수 있습니다. _Default 싱크는 생성 시 다음 포함 필터와 비어 있는 제외 필터로 구성됩니다.

  NOT log_id("cloudaudit.googleapis.com/activity") AND NOT \
  log_id("externalaudit.googleapis.com/activity") AND NOT \
  log_id("cloudaudit.googleapis.com/system_event") AND NOT \
  log_id("externalaudit.googleapis.com/system_event") AND NOT \
  log_id("cloudaudit.googleapis.com/access_transparency") AND NOT \
  log_id("externalaudit.googleapis.com/access_transparency")

Google Kubernetes Engine 컨테이너 및 포드 로그 제외

GKE 시스템 namespaces에 대해 Google Kubernetes Engine 컨테이너 및 포드 로그 항목을 제외하려면 다음 필터를 사용합니다.

resource.type = ("k8s_container" OR "k8s_pod")
resource.labels.namespace_name = (
"cnrm-system" OR
"config-management-system" OR
"gatekeeper-system" OR
"gke-connect" OR
"gke-system" OR
"istio-system" OR
"knative-serving" OR
"monitoring-system" OR
"kube-system")

GKE 시스템 logNames에 대해 Google Kubernetes Engine 노드 로그 항목을 제외하려면 다음 필터를 사용합니다.

resource.type = "k8s_node"
logName:( "logs/container-runtime" OR
"logs/docker" OR
"logs/kube-container-runtime-monitor" OR
"logs/kube-logrotate" OR
"logs/kube-node-configuration" OR
"logs/kube-node-installation" OR
"logs/kubelet" OR
"logs/kubelet-monitor" OR
"logs/node-journal" OR
"logs/node-problem-detector")

로그 버킷에 저장된 Google Kubernetes Engine 노드, 포드, 컨테이너 로그 항목의 볼륨을 보려면 측정항목 탐색기를 사용하세요.

지원 용이성에 필요하지 않은 Dataflow 로그 제외

지원 용이성에 필요하지 않은 Dataflow 로그 항목을 제외하려면 다음 필터를 사용합니다.

resource.type="dataflow_step"
labels."dataflow.googleapis.com/log_type"!="system" AND labels."dataflow.googleapis.com/log_type"!="supportability"

로그 버킷에 저장된 Dataflow 로그 볼륨을 보려면 측정항목 탐색기를 사용하세요.

지원 용이성

Cloud Logging에서 로그 항목을 제외하고 로그 버킷에 저장되지 않도록 할 수 있지만 지원 용이성에 도움이 되는 로그 항목을 유지하는 것이 좋습니다. 이러한 로그 항목을 사용하면 애플리케이션의 문제를 해결하고 식별하는 데 도움이 됩니다.

예를 들어 GKE 시스템 로그 항목은 클러스터에서 발생하는 이벤트에 대해 생성되기 때문에 GKE 애플리케이션 및 클러스터의 문제를 해결하는 데 유용합니다. 이러한 로그 항목은 애플리케이션 코드 또는 기본 GKE 클러스터가 애플리케이션 오류를 일으키는지 확인하는 데 도움이 될 수 있습니다. GKE 시스템 로그에는 또한 Kubernetes API 서버 구성요소에서 생성되는 Kubernetes Audit Logging이 포함됩니다. 여기에는 kubectl 명령어 및 Kubernetes 이벤트를 사용하여 수행된 변경사항이 포함됩니다.

Dataflow의 경우 최소한 시스템 로그(labels."dataflow.googleapis.com/log_type"="system") 및 지원 로그(labels."dataflow.googleapis.com/log_type"="supportability")를 기록하는 것이 좋습니다. 이러한 로그는 개발자가 Dataflow 파이프라인을 관찰하고 문제를 해결하는 데 필수적이며, 사용자는 Dataflow 작업 세부정보 페이지를 사용하여 작업 로그를 보지 못할 수 있습니다.

다음 단계