조직 및 폴더 수준 로그를 취합하여 지원되는 목적지로 라우팅

이 문서에서는 집계 싱크를 만드는 방법을 설명합니다. 집계 싱크를 사용하면 조직 또는 폴더의 Google Cloud 리소스에서 생성된 로그를 결합하여 중앙 위치로 라우팅할 수 있습니다.

시작하기 전에

싱크를 만들기 전에 먼저 다음을 확인합니다.

  • 집계 싱크의 동작을 잘 알고 있습니다. 이러한 싱크에 대해 자세히 알아보려면 집계 싱크 개요를 참조하세요.

  • 로그 탐색기에서 볼 수 있는 로그 항목이 포함된 Google Cloud 폴더 또는 조직이 있습니다.

  • 로그 항목을 라우팅할Google Cloud 조직이나 폴더에 대한 다음 IAM 역할 중 하나가 있습니다.

    • 소유자(roles/owner)
    • Logging 관리자(roles/logging.admin)
    • 로그 구성 작성자(roles/logging.configWriter)

    이러한 역할에 포함된 권한을 사용하면 싱크를 생성, 삭제 또는 수정할 수 있습니다. IAM 역할 설정에 대한 자세한 내용은 Logging 액세스 제어 가이드를 참조하세요.

  • 집계 싱크의 대상이 있거나 이를 만들 수 있습니다.

    대상이 Google Cloud 프로젝트인 경우 프로젝트는 모든 조직에 있을 수 있습니다. 다른 모든 대상은 모든 조직의 모든 프로젝트에 있을 수 있습니다.

  • 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에 제공한 사용자 인증 정보를 사용합니다.

      Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다. 

      gcloud init

      외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

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

집계 싱크 만들기

집계 싱크를 구성하려면 싱크를 만든 다음 싱크에 대상에 쓸 수 있는 권한을 부여합니다. 이 섹션에서는 집계 싱크를 만드는 방법을 설명합니다. 싱크에 권한을 부여하는 방법에 대한 자세한 내용은 이 페이지의 대상 권한 설정 섹션을 참조하세요.

폴더 또는 조직당 싱크를 최대 200개까지 만들 수 있습니다.

콘솔

폴더 또는 조직의 집계 싱크를 만들려면 다음을 수행하세요.

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

    로그 라우터로 이동

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

  2. 기존 폴더 또는 조직을 선택합니다.

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

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

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

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

  5. 싱크 서비스 선택 메뉴에서 대상 유형을 선택한 후 대화상자를 완료하여 대상을 지정합니다. 기존 대상을 선택하거나 대상을 만들 수 있습니다.

    • 가로채기 싱크의 경우 Google Cloud 프로젝트를 선택한 후 대상 Google Cloud 프로젝트의 정규화된 이름을 입력합니다.

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • 비가로채기 싱크의 경우 대상을 선택한 다음 대상의 정규화된 이름을 입력합니다. 다음 대상이 지원됩니다.

      • Google Cloud 프로젝트

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Cloud Logging 버킷

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

      • 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

      • Splunk

        Splunk 서비스의 Pub/Sub 주제를 입력합니다.

  6. 싱크에 포함할 로그 선택 패널에서 싱크에 포함할 리소스를 선택합니다.

    • 가로채기 싱크의 경우 이 조직 및 모든 하위 리소스에서 수집한 로그 가로채기를 선택합니다.

    • 비가로채기 싱크의 경우 이 리소스와 모든 하위 리소스에서 수집한 로그 포함을 선택합니다.

  7. 포함 필터 빌드 필드에서 포함하려는 로그 항목과 일치하는 필터 표현식을 입력합니다. 필터를 설정하지 않으면 선택한 리소스의 모든 로그 항목이 대상으로 라우팅됩니다.

    예를 들어 데이터 액세스 감사 로그를 단일 Logging 버킷으로 라우팅하도록 필터를 빌드해야 할 수 있습니다. 이 필터는 다음과 같습니다.

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

    필터 예시는 이 페이지의 집계 싱크를 위한 필터 만들기 섹션을 참조하세요.

    필터의 길이는 20,000자를 초과할 수 없습니다.

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

  9. 선택사항: 싱크에서 제외할 로그 선택 패널에서 다음을 수행합니다.

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

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

      예를 들어 특정 프로젝트의 로그 항목이 대상으로 라우팅되지 않도록 제외하려면 다음 제외 필터를 추가합니다.

      logName:projects/PROJECT_ID

      여러 프로젝트에서 로그 항목을 제외하려면 논리 OR 연산자를 사용하여 logName 절을 조인합니다.

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

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

  11. 집계된 싱크의 구성을 완료하려면 싱크의 서비스 계정에 싱크의 대상에 로그 항목을 쓸 수 있는 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

gcloud

집계된 싱크를 만들려면 logging sinks create 명령어를 사용합니다.

  1. 싱크를 만들려면 gcloud logging sinks create 명령어를 호출하고 --include-children 옵션을 포함해야 합니다.

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

    • SINK_NAME: 로그 싱크의 이름 싱크를 만든 후에는 싱크 이름을 변경할 수 없습니다.
    • SINK_DESTINATION: 로그 항목을 라우팅하려는 서비스 또는 프로젝트. 이러한 대상의 형식에 대한 자세한 내용은 대상 경로 형식을 참조하세요.
    • INCLUSION_FILTER: 싱크의 포함 필터. 필터 예시는 집계 싱크를 위한 필터 만들기를 참조하세요.
    • FOLDER_ID: 폴더의 ID입니다. 조직 수준에서 싱크를 만들려면 --folder=FOLDER_ID를 -- organization=ORGANIZATION_ID로 바꿉니다.

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

    gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"

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

    • 가로채기 싱크를 만들려면 --intercept-children 옵션을 포함합니다.

    예를 들어 폴더 수준에서 집계 싱크를 만들고 대상이 Pub/Sub 주제인 경우 명령어는 다음과 같을 수 있습니다.

    gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"

  2. 싱크의 서비스 계정에 싱크 대상에 대한 쓰기 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

REST

집계 싱크를 만들려면 organizations.sinks.create 또는 folders.sinks.create Logging API 메서드를 사용합니다. 메서드의 인수를 다음과 같이 준비하세요.

  1. parent 필드를 싱크를 만들 Google Cloud 조직이나 폴더로 설정합니다. 이 상위 요소는 다음 중 하나가 되어야 합니다.

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. 메서드 요청 본문의 LogSink 객체에서 다음 중 하나를 수행합니다.

    • includeChildren을 True로 설정합니다.

    • 가로채기 싱크를 만들려면 interceptChildren 필드도 True로 설정합니다.

  3. 포함하려는 로그 항목과 일치하도록 filter 필드를 설정합니다.

    필터 예시는 집계 싱크를 위한 필터 만들기를 참조하세요.

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

  4. 나머지 LogSink 필드는 일반 싱크와 동일하게 설정합니다. 자세한 내용은 지원되는 대상으로 로그 라우팅을 참조하세요.

  5. organizations.sinks.create 또는 folders.sinks.create를 호출하여 싱크를 만듭니다.

  6. 싱크의 서비스 계정에 싱크 대상에 대한 쓰기 권한을 부여합니다. 자세한 내용은 대상 권한 설정을 참조하세요.

싱크에서 변경사항을 적용하는 데 몇 분 정도 걸릴 수 있습니다.

집계 싱크의 필터

이 섹션에서는 집계 싱크에서 사용할 수 있는 필터의 예시를 제공합니다. 자세한 예시는 로그 탐색기를 사용하는 샘플 쿼리를 참조하세요.

일부 예에서는 다음과 같은 표기법을 사용합니다.

  • :은 하위 문자열 연산자입니다. = 연산자를 대체하지 마세요.
  • ...은 추가 필터 비교를 나타냅니다.
  • 변수는 색상별 텍스트로 표시됩니다. 변수 값을 유효한 값으로 바꿉니다.

필터 길이는 20,000자(영문 기준)로 제한됩니다.

필터링 문법에 대한 자세한 내용은 Logging 쿼리 언어를 참조하세요.

로그 소스 선택

모든 하위 리소스의 로그 항목을 라우팅하려면 싱크의 포함 및 제외 필터에 프로젝트, 폴더, 조직을 지정하지 마세요. 예를 들어 다음 필터를 사용하여 조직에 대해 집계 싱크를 구성한다고 가정합니다.

resource.type="gce_instance"

이전 필터를 사용하면 해당 조직의 모든 하위 요소에 작성된 Compute Engine 인스턴스의 리소스 유형이 있는 로그 항목이 집계 싱크에 의해 대상으로 라우팅됩니다.

그러나 집계 싱크를 사용하여 특정 하위 리소스에서만 로그 항목을 라우팅하려는 상황이 발생할 수 있습니다. 예를 들어 규정 준수를 위해 특정 폴더 또는 프로젝트의 감사 로그를 자체 Cloud Storage 버킷에 저장해야 할 수 있습니다. 이러한 경우 포함 필터를 구성하여 라우팅할 로그 항목이 있는 각 하위 리소스를 지정합니다. 폴더와 해당 폴더 내의 모든 프로젝트에서 로그 항목을 라우팅하려면 필터에서 폴더와 해당 폴더에 포함된 각 프로젝트를 나열하고 OR 절과 함께 문을 조인해야 합니다.

다음 필터는 로그 항목을 특정 Google Cloud 프로젝트, 폴더 또는 조직으로 제한합니다.

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ...

예를 들어 my-folder 폴더에 작성된 Compute Engine 인스턴스에 작성된 로그 항목만 라우팅하려면 다음 필터를 사용합니다.

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

이전 필터를 사용하면 my-folder의 하위 요소인 Google Cloud 프로젝트에 작성된 로그 항목을 포함하여 my-folder 이외의 리소스에 작성된 로그 항목은 대상으로 라우팅되지 않습니다.

모니터링 리소스 선택

Google Cloud 프로젝트 내의 특정 모니터링 리소스에서만 로그 항목을 라우팅하려면 여러 가지 비교를 사용하여 리소스를 정확하게 지정합니다.

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

리소스 유형 목록은 모니터링 리소스 유형을 참조하세요.

로그 항목 샘플 선택

로그 항목 중 임의의 샘플을 라우팅하려면 기본 제공 함수 sample을 추가합니다. 예를 들어 현재 필터와 일치하는 로그 항목의 10%만 라우팅하려면 다음과 같이 추가합니다.

sample(insertId, 0.10) AND ...

자세한 내용은 sample 함수를 참조하세요.

Cloud Logging 필터에 대한 자세한 내용은 Logging 쿼리 언어를 참조하세요.

대상 권한 설정

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

현재 프로젝트에서 로그 버킷이 아닌 다른 대상으로 로그 항목을 라우팅하는 싱크를 만들거나 업데이트할 때 해당 싱크의 서비스 계정이 필요합니다. Logging에서 서비스 계정을 자동으로 만들고 관리합니다.

  • 2023년 5월 22일자로 싱크를 만들고 기본 리소스에 대한 서비스 계정이 없으면 Logging에서 서비스 계정을 만듭니다. Logging은 기본 리소스의 모든 싱크에 대해 동일한 서비스 계정을 사용합니다. 리소스는 Google Cloud 프로젝트, 조직, 폴더 또는 결제 계정일 수 있습니다.
  • 2023년 5월 22일 이전에 Logging은 각 싱크에 대한 서비스 계정을 만들었습니다. 2023년 5월 22일부터 Logging은 기본 리소스의 모든 싱크에 공유 서비스 계정을 사용합니다.

싱크의 작성자 ID는 해당 싱크와 연결된 서비스 계정의 식별자입니다. 현재 Google Cloud 프로젝트의 로그 버킷에 쓰지 않는 한 모든 싱크는 작성자 ID를 가집니다. 작성자 ID의 이메일 주소는 대상에 데이터를 쓸 수 있는 액세스 권한이 있어야 하는 주 구성원을 식별합니다.

로그 항목을 서비스 경계로 보호되는 리소스로 라우팅하려면 해당 싱크의 서비스 계정을 액세스 수준에 추가한 후 대상 서비스 경계에 할당해야 합니다. 비집계 싱크에는 이 작업을 수행하지 않아도 됩니다. 자세한 내용은 VPC 서비스 제어: Cloud Logging을 참조하세요.

싱크가 목적지로 라우팅하도록 권한을 설정하려면 다음을 수행합니다.

콘솔

  1. 싱크의 서비스 계정에 대한 정보를 가져오려면 다음을 수행합니다.

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

      로그 라우터로 이동

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

    2. 메뉴를 선택한 다음 싱크 세부정보 보기를 선택합니다. 작성자 ID가 싱크 세부정보 패널에 표시됩니다.

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

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

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

  2. 싱크의 작성자 ID로 지정된 주 구성원에게 대상에 로그 데이터를 쓸 수 있는 권한을 부여합니다.

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

      IAM으로 이동

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

    2. Google Cloud 콘솔의 툴바에서 집계된 싱크의 대상을 저장하는 프로젝트를 선택합니다. 대상이 프로젝트인 경우 해당 프로젝트를 선택합니다.

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

    4. 싱크의 작성자 ID로 지정된 주 구성원을 입력한 후 IAM 역할을 부여합니다.

gcloud

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

  2. 싱크의 서비스 계정에 대한 정보를 가져오려면 gcloud logging sinks describe 메서드를 호출합니다.

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

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

    gcloud logging sinks describe 명령어를 실행합니다.

    gcloud logging sinks describe SINK_NAME

  3. 싱크 세부정보에 writerIdentity라는 라벨이 지정된 필드가 포함되어 있으면 다음 단계를 진행합니다. 세부정보에 writerIdentity 필드가 포함되지 않으면 싱크에 대한 대상 권한을 구성할 필요가 없습니다.

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

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

  5. gcloud projects add-iam-policy-binding 명령어를 호출하여 싱크의 작성자 ID에 대상에 로그 데이터를 쓸 수 있는 권한을 부여합니다.

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

    • PROJECT_ID: 프로젝트 식별자 집계된 싱크의 대상을 저장하는 프로젝트를 선택합니다. 대상이 프로젝트인 경우 해당 프로젝트를 선택합니다.
    • PRINCIPAL: 역할을 부여할 주 구성원의 식별자. 주 구성원 식별자는 일반적으로 PRINCIPAL-TYPE:ID 형식입니다. 예를 들면 user:my-user@example.com입니다. PRINCIPAL 형식 전체 목록은 주 구성원 식별자를 참조하세요.

    • ROLE: IAM 역할 로그 싱크의 대상에 따라 싱크의 작성자 ID에 IAM 역할을 부여합니다.

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

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

REST

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

다음 단계