로그 뷰어를 통해 내보내기

이 페이지에서는 Cloud Console을 사용하여 로그 항목을 내보내는 방법을 설명합니다. Cloud Logging API 또는 gcloud logging 명령줄 도구를 사용하여 로그 항목을 내보낼 수도 있습니다.

Logging에서 로그 내보내기에 대한 간략한 개념은 로그 내보내기 개요를 참조하세요. 요약하자면, 로그를 내보낼 때는 로그 쿼리내보내기 대상 위치를 포함하는 하나 이상의 싱크를 만듭니다. Cloud Logging에서 새로운 로그 항목을 수신하면 로그 항목이 각 싱크와 비교됩니다. 로그 항목이 싱크의 쿼리와 일치하면 로그 항목의 복사본이 내보내기 대상 위치에 기록됩니다.

내보낸 로그 항목의 대상 위치로는 Cloud Storage, BigQuery, Pub/Sub가 지원됩니다.

내보낸 로그의 형식 지정 및 구성 방법과 내보낸 로그를 보는 방법은 내보낸 로그 사용을 참조하세요.

시작하기 전에

  • 프로젝트: 로그 뷰어에서 볼 수 있는 로그가 포함된 Google Cloud 프로젝트가 있어야 합니다.

    싱크를 만들거나 삭제하거나 수정하려면 프로젝트의 소유자 또는 Logging/로그 구성 작성자 Cloud IAM 역할이 있어야 합니다. 자세한 내용은 권한 및 역할을 참조하세요.

  • 대상 서비스: 로그를 내보내려면 로그를 작성할 Google Cloud 서비스, 즉 Cloud Storage, BigQuery 또는 Pub/Sub에 가입해야 합니다.

시작하기

  1. Cloud Console에서 Cloud Logging > 로그 라우터로 이동합니다.

    로그 라우터로 이동

  2. 페이지 상단에서 기존 Google Cloud 프로젝트를 선택합니다.

다음 스크린샷은 여러 로그 싱크가 이미 구성되어 있는 로그 라우터 페이지의 예시를 보여줍니다.

내보내기 목록을 보여주는 사용자 인터페이스

로그 싱크를 아직 구성하지 않았으면 로그 싱크가 구성되지 않았습니다라는 메시지가 표시됩니다.

로그 라우터 사용자 인터페이스

로그 라우터 인터페이스에는 내보내기가 요약된 테이블이 있습니다. 테이블의 각 행에는 로그 내보내기에 설명된 싱크 속성에 해당하는 정보가 있습니다.

  • 싱크 이름: 현재 프로젝트의 싱크 식별자입니다.
  • 대상 위치: 내보낸 로그 항목이 전달되는 대상 위치입니다.
  • 작성자 ID: Logging에서 로그 항목을 대상 위치에 작성하는 데 사용하는 서비스 계정입니다. 이 서비스 계정에는 싱크의 내보내기 대상 위치에 작성할 권한이 있어야 합니다.

테이블의 행마다 오른쪽 끝에 메뉴 가 있습니다. 여기에는 다음과 같은 옵션이 있습니다.

  • 싱크 수정: 싱크 매개변수를 변경할 수 있는 싱크 수정 패널이 열립니다.
  • 싱크 삭제: 싱크를 삭제하고 로그 내보내기를 중지할 수 있습니다.
  • 싱크 세부정보 보기: 싱크의 쿼리를 표시합니다. 수정을 클릭하면 싱크의 속성이나 쿼리를 변경할 수 있습니다.

표 위의 검색어 상자에서는 텍스트 검색 또는 싱크 속성(싱크 이름, 대상 위치, 작성자 ID)을 기준으로 싱크를 쿼리할 수 있습니다. 예를 들어 다음 스크린샷은 대상 위치 bigquery에 대한 검색과 OR(AND가 기본값)로 다른 싱크 속성을 인수에 연결하는 옵션을 보여줍니다.

검색어를 보여주는 사용자 인터페이스

또한 열 이름을 클릭하면 오름차순 또는 내림차순으로 데이터를 정렬할 수 있고, 표 하단에서 표시할 행 개수를 선택할 수도 있습니다.

싱크 만들기

내보내기 싱크를 만들려면 로그 라우터 페이지 상단에 있는 싱크 만들기를 클릭합니다. 로그 뷰어 페이지 상단에서 이 작업을 수행할 수도 있습니다.

사용하는 서비스 계정에 프로젝트의 내보내기를 만들 수 있는 권한이 없으면 이 옵션을 사용할 수 없습니다. 자세한 내용은 위의 시작하기 전에를 참조하세요.

다음 스크린샷은 일부 필드가 입력된 싱크 수정 패널을 보여줍니다.

내보내기 수정 패널을 보여주는 사용자 인터페이스

싱크를 만들려면 다음과 같이 싱크 수정 패널을 입력합니다.

  1. (필터): 고급 로그 쿼리를 입력합니다. 쿼리를 따옴표로 묶을 필요는 없으며 여러 행을 사용할 수 있습니다. 초기 쿼리는 내보내기 만들기를 클릭할 때 표시 중인 로그 항목에 따라 결정됩니다.

    쿼리를 수정할 때마다 쿼리 제출을 클릭하면 일치하는 로그 항목이 표시됩니다. 최신 로그를 가져오려면 최신 로그로 이동을 클릭합니다.

    기본 보기 인터페이스를 사용하여 로그를 선택하려면 검색어 상자에서 드롭다운 메뉴 를 사용합니다.

  2. 싱크 이름: 싱크에 할당할 식별자를 입력합니다.

  3. 싱크 서비스: Cloud Storage, Pub/Sub, BigQuery, 또는 커스텀 대상 위치 중에서 대상 서비스를 선택합니다.

    커스텀 내보내기 대상 위치도 Cloud Storage, BigQuery 또는 Pub/Sub 중에 있어야 하지만 이 옵션을 사용하면 다른 Google Cloud 프로젝트의 싱크로 로그를 보낼 수 있습니다. 즉, 싱크의 소스와 대상 위치가 동일한 Google Cloud 조직 내에 있지 않아도 됩니다.

  4. 싱크 대상 위치:

    1. Cloud Storage: 내보낸 로그를 수신할 특정 버킷을 선택하거나 만듭니다.
    2. Pub/Sub: 내보낸 로그를 수신할 특정 주제를 선택하거나 만듭니다.
    3. BigQuery: 내보낸 로그를 수신할 특정 데이터세트를 선택하거나 만듭니다. 파티션을 나눈 테이블도 사용할 수 있습니다.
    4. 커스텀 대상 위치: Cloud Storage, Pub/Sub 또는 BigQuery Google Cloud 프로젝트를 문자열로 추가합니다. 프로젝트 이름 형식에 대한 자세한 내용은 싱크 속성을 참조하세요.
  5. 싱크 업데이트를 클릭하여 싱크를 만듭니다.

    Logging에서는 싱크가 만들어지는 동안 대상 위치에 작성할 수 있도록 싱크의 작성자 ID 권한을 부여하려고 시도합니다. 로그가 있는 프로젝트가 아닌 다른 프로젝트의 대상 위치로 내보내는 경우 새로운 대상 위치의 관리자가 권한을 부여해야 합니다. 라우터 페이지에 싱크와 함께 나열되는 싱크의 작성자 ID를 관리자에게 보내야 합니다.

싱크와 일치하는 새로운 로그 항목의 내보내기가 시작됩니다. BigQuery 또는 Pub/Sub로 전달되는 로그 항목은 이러한 내보내기 대상 위치로 즉시 스트리밍됩니다. Cloud Storage로 전달되는 로그 항목은 약 1시간마다 배치로 전송됩니다. 자세한 내용은 내보낸 로그 사용을 참조하세요.

로그를 내보내기 대상 위치로 내보내려고 시도할 때 Logging에 오류가 발생하면 프로젝트의 활동 스트림에 오류가 표시됩니다. Google Cloud Console의 프로젝트 홈페이지 상단에서 활동을 선택하세요. 일반적인 오류를 진단하려면 아래의 문제해결을 참조하세요.

싱크 업데이트

싱크를 업데이트하려면 싱크 이름 오른쪽에 있는 메뉴 에서 싱크 수정 명령어를 선택합니다. 그러면 다음과 같은 매개변수를 변경할 수 있습니다.

  • 대상 위치
  • 쿼리

다른 싱크 매개변수를 변경하려면 projects.sinks.update API 메서드를 사용하세요.

싱크 삭제

싱크를 삭제하려면 라우터 페이지에서 싱크를 선택하고 페이지 상단에 있는 삭제를 클릭합니다. 또는 싱크 이름 오른쪽의 메뉴에서 싱크 삭제를 선택합니다.

대상 위치 권한

이 섹션에서는 Logging에 내보낸 로그를 싱크의 내보내기 대상 위치에 쓸 수 있는 Cloud Identity and Access Management 권한의 부여 방법을 설명합니다.

싱크를 만들면 Logging에서 고유한 작성자 ID라는 싱크의 새로운 서비스 계정을 만듭니다. 이 서비스 계정은 Cloud Logging에서 소유 및 관리하는 계정으로, 직접 관리할 수 없습니다. 싱크가 삭제되면 서비스 계정이 삭제됩니다.

그러면 내보내기 대상 위치는 이 서비스 계정이 로그 항목을 작성할 수 있도록 허용해야 합니다. 이 권한을 설정하려면 다음 단계를 따르세요.

  1. Cloud Console, gcloud logging 명령줄 인터페이스 또는 Logging API에서 새 싱크를 만듭니다.

  2. Cloud Console에 싱크를 만들었고 대상 위치에 대한 소유자 액세스 권한이 있으면 Cloud Logging이 사용자를 대신하여 필요한 권한을 설정합니다. 권한이 설정되었다면 더 이상 필요한 작업은 없습니다. 그렇지 않으면 계속 진행하세요.

  3. 새로운 싱크에서 싱크의 작성자 ID(이메일 주소)를 가져옵니다.

    • Cloud Console을 사용하는 경우 작성자 ID는 라우터 페이지의 싱크 목록에 나타납니다.
    • Logging API를 사용하는 경우에는 LogSink 객체에서 작성자 ID를 가져올 수 있습니다.
    • gcloud logging을 사용하는 경우에는 싱크를 나열할 때 작성자 ID가 표시됩니다.
  4. 대상 위치에 대한 소유자 액세스 권한이 있으면 다음 방식으로 대상 위치에 서비스 계정을 추가하세요.

    • 대상 위치가 Cloud Storage이면 버킷에 싱크의 작성자 ID를 추가하고 Storage 객체 생성자 역할을 부여합니다.
    • 대상 위치가 BigQuery이면 데이터세트에 싱크의 작성자 ID를 추가하고 BigQuery 데이터 편집자 역할을 부여합니다.
    • 대상 위치가 Pub/Sub이면 주제에 싱크의 작성자 ID를 추가하고 Pub/Sub 게시자 역할을 부여합니다.

    이렇게 하면 승인이 완료됩니다.

  5. 내보내기 대상 위치에 대한 소유자 액세스 권한이 없으면 해당 권한이 있는 사용자에게 작성자 ID 서비스 계정 이름을 보냅니다. 그러면 해당 사용자는 이전 단계의 지침에 따라 작성자 ID를 내보내기 대상 위치에 추가해야 합니다.

승인 지연

싱크가 로그 항목을 내보내려고 하는데 내보내기 대상 위치에 대한 적절한 Cloud IAM 권한이 없으면 싱크는 오류를 보고하고 해당 로그 항목을 건너뜁니다. 권한이 부여될 때까지 이 작업이 계속되며 권한이 부여되면 싱크가 새로운 로그 항목을 내보내기 시작합니다.

싱크를 만드는 시점과 싱크의 새 서비스 계정을 사용하여 내보내기 대상 위치에 대한 쓰기를 승인하는 시점 사이에는 지연이 발생합니다. 싱크를 만든 후 처음 24시간 동안에는 프로젝트의 활동 페이지에 해당 싱크의 권한 관련 오류 메시지가 표시될 수 있지만 이는 무시해도 됩니다.

이점 및 제한사항

Cloud Console을 사용하면 Logging API를 사용할 때에 비해 다음과 같은 이점이 있습니다.

  • Cloud Console은 모든 싱크를 한곳에서 보여줍니다.
  • Cloud Console은 싱크를 만들기 전에 싱크 쿼리와 일치하는 로그 항목을 보여줍니다.
  • Cloud Console은 싱크의 내보내기 대상 위치를 만들고 승인할 수 있습니다.

하지만 Cloud Console에서는 프로젝트에 싱크만 만들거나 볼 수 있습니다. 조직, 폴더 또는 결제 계정에 싱크를 만들려면 집계 싱크를 참조하세요.

문제해결

다음은 로그를 내보낼 때 발생할 수 있는 몇 가지 일반적인 문제와 그 해결책입니다.

  • 대상 위치에서 발생하는 오류: 싱크에서 내보내기 대상 위치의 사양을 확인하세요. projects.sinks.get을 사용하여 싱크의 작성자 ID를 찾고 내보내기 대상 위치에 대한 쓰기 권한이 이 ID에 있는지 확인하세요.

  • 로그가 내보내지지 않음: 가능한 몇 가지 원인은 다음과 같습니다.

    • 쿼리가 잘못되었습니다. 내보내기 쿼리를 검사하여 최근에 쿼리와 일치하는 로그 항목이 Logging에 전달되었는지 확인하고 맞춤법 또는 형식 오류를 수정하세요.

    • 싱크를 만들거나 업데이트한 이후로 일치하는 로그 항목이 수신되지 않았습니다. 새 로그 항목만 내보내집니다.

      지연 시간이 지나야 내보낸 로그를 대상 위치에서 볼 수 있습니다. Cloud Storage 대상 위치의 경우에는 특히 그렇습니다. 자세한 내용은 내보낸 로그 사용 가능 여부 확인을 참조하세요.

      내보내기 시스템 측정항목을 확인할 수도 있습니다. 내보내기 시스템 측정항목은 내보낸 로그 항목의 수와 오류로 인해 중단된 항목의 수를 각각 알려줍니다.

오류가 해결되면 싱크가 로그 내보내기를 시작합니다.

로그 뷰어를 사용하여 싱크 오류를 보려면 다음을 수행합니다.

  1. 싱크가 만들어진 프로젝트 또는 기타 리소스의 활동 스트림으로 이동합니다.

    활동 스트림으로 이동

  2. 필터 패널에서 활동 유형 > 구성을 선택하고 리소스 유형 > 로그 기록 내보내기 싱크를 선택합니다.

  3. 해당 기간의 싱크 오류를 확인할 수 있도록 날짜/시간을 조정합니다.

    싱크 오류가 표시됩니다.

다음 섹션에서는 서비스별로 발생 가능한 오류와 예기치 않은 결과를 나열하고 그에 대응할 방법을 설명합니다.

Cloud Storage로 내보내는 중 발생하는 오류

다음 표에는 Cloud Storage로 로그를 내보낼 때 발생하는 가장 일반적인 오류가 나와 있습니다.

오류 원인 해결책
버킷 [YOUR_BUCKET]에 대한 권한으로 인해 로그 그룹이 새 객체를 생성할 수 없습니다. 싱크의 작성자 ID에 버킷에 대한 올바른 권한이 없습니다. 버킷에 필요한 권한을 추가하거나 다른 버킷을 사용하도록 싱크를 업데이트하세요. 대상 위치 권한을 참조하세요.
[YOUR_BUCKET]이라는 이름의 버킷을 찾을 수 없습니다. 버킷 이름에 오류가 있거나 버킷이 삭제되었을 수 있습니다. 올바른 버킷 대상 위치로 싱크를 업데이트하세요.
싱크가 생성되었지만 대상 위치에 대한 올바른 권한을 부여하지 못했습니다. 버킷을 만들 때 버킷의 액세스 제어 모델을 균일한 액세스 제어로 설정했습니다.

(이 오류 메시지는 서비스 계정을 추가한 후에도 계속 표시됩니다.)
버킷을 만들 때 액세스 제어 모델로 세분화된 액세스 제어를 선택하세요. 기존 버킷의 경우 버킷을 만든 지 90일이 지나지 않았다면 권한 탭을 사용해 액세스 제어 모델을 변경할 수 있습니다.

BigQuery로 내보내는 중 발생하는 오류

다음 표에는 로그를 BigQuery로 내보낼 때 발생하는 가장 일반적인 오류가 나와 있습니다.

오류 원인 해결책
데이터세트 [YOUR_DATASET]에 대한 권한으로 인해 로그 그룹이 새 표를 생성할 수 없습니다. 싱크의 작성자 ID에 데이터세트에 대한 충분한 권한이 없습니다. 데이터세트에 대한 권한을 추가하세요. 대상 위치 권한을 참조하세요.
[YOUR_DATASET]라는 이름의 데이터세트를 찾을 수 없습니다. 싱크의 대상 위치에 오류가 있거나 누군가 데이터세트를 삭제했을 수 있습니다. 데이터세트를 다시 생성하거나 내보내기 싱크를 업데이트하여 다른 데이터세트를 사용하세요.
데이터세트 [YOUR_DATASET]의 표 [YOUR_TABLE]로 스트리밍되는 로그가 표의 스키마와 일치하지 않습니다. 현재 표의 스키마와 호환되지 않는 로그를 내보내려고 시도하고 있습니다. 로그 항목이 표의 스키마와 일치하는지 확인하세요. 흔히 발생하는 문제로는 다른 데이터 유형의 로그 항목을 전송할 때를 들 수 있는데, 예를 들자면 로그 항목의 필드 중 하나는 정수인데 스키마에서 해당하는 열은 문자열 유형일 수 있습니다. 활동 스트림에는 잘못된 로그 항목 중 하나에 대한 링크가 포함됩니다. 오류의 원인을 해결한 후 현재 표의 이름을 다시 지정하고 Logging을 통해 표를 다시 만들 수 있습니다.
데이터세트 [YOUR_DATASET]의 테이블 [YOUR_TABLE]에서 테이블당 스트리밍 삽입 할당량이 초과되었습니다. 너무 많은 로그 항목을 지나치게 빨리 내보내고 있습니다. 로그 스트리밍에 적용되는 BigQuery 기본 할당량 한도를 참조하세요. 싱크에서 생성하는 로그 데이터의 양을 줄이세요. 싱크의 쿼리를 업데이트하여 일치하는 로그 항목 수를 줄이거나 sample() 함수를 사용하세요.
파티션을 나눈 테이블 [YOUR_TABLE]로 스트리밍한 로그가 허용되는 시간 범위를 벗어납니다. BigQuery는 지나치게 먼 과거나 미래의 로그는 수락하지 않습니다. 허용된 시간 범위를 벗어난 로그는 싱크로 내보낼 수 없습니다. 이러한 로그는 대신 Cloud Storage로 내보내고 BigQuery 로드 작업을 사용하면 됩니다. 자세한 안내는 BigQuery 문서를 참조하세요.
조직 정책에 따라 금지되는 작업이므로 로그를 데이터세트 [YOUR_DATASET]로 스트리밍할 수 없습니다. 선택한 데이터세트에 작성하는 것을 금지하는 조직 정책이 존재합니다. 조직 정책에 관한 자세한 내용은 문서를 참조하세요. 규정을 준수하는 데이터세트를 사용하도록 내보내기 싱크를 수정하세요.

Pub/Sub로 로그를 내보내는 중 발생하는 오류

다음 표에는 Pub/Sub로 로그를 내보낼 때 발생하는 가장 일반적인 오류가 나와 있습니다.

오류 원인 해결책
[ACCOUNT]가 [TOPIC]에 게시하려면 [PROJECT]의 수정 권한을 갖고 있어야 합니다. 싱크의 작성자 ID에 해당 주제에 대한 올바른 권한이 없습니다. 프로젝트에 필요한 권한을 추가하세요. 대상 위치 권한을 참조하세요.
주제 [TOPIC]이 없습니다. 내보낸 로그를 수신하도록 구성된 주제를 삭제했을 수 있습니다. 동일한 이름의 주제를 다시 만들거나 내보내기 구성을 변경하여 다른 주제를 사용하세요.

다음 단계