로그의 BigQuery 스키마

이 페이지에서는 Cloud Logging에서 BigQuery로 로그 항목을 라우팅할 때 적용되는 형식과 규칙을 자세히 설명합니다.

개요

싱크를 사용하여 Cloud Logging에서 BigQuery로 로그 항목을 라우팅할 수 있습니다. 싱크를 만들 때 BigQuery 데이터 세트를 대상으로 정의합니다. Logging은 해당 BigQuery 데이터 세트에서 생성된 파티션을 나눈 테이블에 싱크의 규칙과 일치하는 로그 항목을 보냅니다.

Cloud Logging에서 수신된 데이터의 BigQuery 테이블 스키마는 LogEntry 유형의 구조와 로그 항목 페이로드의 콘텐츠를 기반으로 합니다. 또한 Cloud Logging은 감사 로그 및 특정 구조화된 페이로드 필드의 BigQuery 스키마 필드 이름을 짧게 줄이기 위해 규칙을 적용합니다.

Logging 싱크는 데이터를 작은 배치로 BigQuery에 스트리밍하므로 로드 작업을 실행하지 않고도 데이터를 쿼리할 수 있습니다. 자세한 내용은 BigQuery로 데이터 스트리밍을 참조하세요. 가격 책정 정보는 BigQuery 가격 책정: 데이터 수집 가격 책정의 스트리밍 삽입 섹션을 참조하세요.

필드 이름 지정 규칙

BigQuery로 로그를 전송할 때 로그 항목 필드에 적용되는 몇 가지 이름 지정 규칙은 다음과 같습니다.

  • 로그 항목 필드 이름은 128자(영문 기준)를 초과할 수 없습니다.

  • 로그 항목 필드 이름은 영숫자 문자로만 구성될 수 있습니다. 지원되지 않는 문자는 필드 이름에서 삭제되고 밑줄로 대체됩니다. 예를 들어 jsonPayload.foo%%jsonPayload.foo__로 변환됩니다.

    로그 항목 필드 이름은 변환 후에도 영숫자 문자로 시작해야 합니다. 시작 위치에 밑줄이 있으면 모두 삭제됩니다.

  • LogEntry 유형에 속하는 로그 항목 필드의 경우 해당 BigQuery 필드 이름이 로그 항목 필드와 정확히 일치합니다.

  • 사용자가 제공한 로그 항목 필드의 경우 해당 BigQuery 필드 이름은 소문자로 정규화되지만 그 밖의 이름 지정 규칙은 유지됩니다.

  • 구조화된 페이로드 내 필드의 경우 @type 지정자가 존재하지 않는 한 해당 BigQuery 필드 이름이 소문자로 정규화되지만 그 밖의 이름 지정 규칙은 유지됩니다.

    @type 지정자가 있는 구조화된 페이로드에 대한 상세 내용은 이 페이지의 @type이 있는 페이로드 필드를 참조하세요.

다음 예시에서는 이러한 이름 지정 규칙이 적용되는 방식을 보여줍니다.

로그 항목 필드 LogEntry 유형 매핑 BigQuery 필드 이름
insertId insertId insertId
textPayload textPayload textPayload
httpRequest.status httpRequest.status httpRequest.status
httpRequest.requestMethod.GET httpRequest.requestMethod.[ABC] httpRequest.requestMethod.get
resource.labels.moduleid resource.labels.[ABC] resource.labels.moduleid
jsonPayload.MESSAGE jsonPayload.[ABC] jsonPayload.message
jsonPayload.myField.mySubfield jsonPayload.[ABC].[XYZ] jsonPayload.myfield.mysubfield

@type이 있는 페이로드 필드

이 섹션에서는 페이로드에 지정자 @type가 포함된 로그 항목의 특수한 BigQuery 스키마 필드 이름에 대해 설명합니다. 여기에는 BigQuery로 라우팅된 감사 로그 항목이 포함됩니다.

로그 항목의 페이로드는 구조화된 데이터를 포함할 수 있습니다. 모든 구조화된 필드는 다음과 같은 형식의 형식 지정자(선택사항)를 포함할 수 있습니다.

@type: type.googleapis.com/[TYPE]

이름 지정 규칙은 감사 로그 항목의 protoPayload 필드가 BigQuery 스키마 필드 protopayload_auditlog에 매핑될 수 있는 이유를 설명합니다.

@type의 이름 지정 규칙

형식 지정자가 있는 구조화된 필드에는 일반적으로 필드 이름에 [TYPE]이 붙는 BigQuery 필드 이름이 지정됩니다. [TYPE]의 값은 어떤 문자열이라도 될 수 있습니다.

@type의 이름 지정 규칙은 jsonPayload 또는 protoPayload의 최상위 수준에만 적용됩니다. 중첩 필드는 무시됩니다. 최상위 수준의 구조화된 페이로드 필드를 처리할 때 Logging은 프리픽스 type.googleapis.com을 삭제합니다.

예를 들어 다음 표는 최상위 수준의 구조화된 페이로드 필드를 BigQuery 필드 이름에 매핑하는 것을 보여줍니다.

페이로드 페이로드 @type 페이로드 필드 BigQuery 필드 이름
jsonPayload (없음) statusCode jsonPayload.statusCode
jsonPayload type.googleapis.com/abc.Xyz statusCode jsonpayload_abc_xyz.statuscode
protoPayload (없음) statusCode protoPayload.statuscode
protoPayload type.googleapis.com/abc.Xyz statusCode protopayload_abc_xyz.statuscode

형식 지정자가 있는 필드의 경우 앞의 규칙에 다음과 같은 몇 가지 예외가 적용됩니다.

  • App Engine 요청 로그에서 BigQuery로 라우팅된 로그의 페이로드 이름은 페이로드에 형식 지정자가 있더라도 protoPayload입니다.

  • Cloud Logging은 감사 로그의 BigQuery 스키마 필드 이름을 짧게 줄이기 위해 몇 가지 특수 규칙을 적용합니다. 자세한 내용은 이 페이지의 감사 로그 필드 섹션에서 설명합니다.

이 예시에서는 구조화된 페이로드 필드를 BigQuery에서 수신할 때 이름이 지정되고 사용되는 방법을 보여줍니다.

로그 항목의 페이로드가 다음과 같이 구조화되어 있다고 가정해 보겠습니다.

jsonPayload: {
  @type: "type.googleapis.com/google.cloud.v1.CustomType"
    name_a: {
      sub_a: "A value"
    }
    name_b: {
      sub_b: 22
    }
  }

BigQuery 필드에 다음과 같이 매핑됩니다.

  • 최상위 수준의 구조화된 필드 jsonPayload에는 @type 지정자가 포함됩니다. BigQuery 이름은 jsonpayload_v1_customtype입니다.

  • 중첩 필드는 유형 지정자 규칙이 적용되지 않으므로 표준 BigQuery 이름 지정 규칙으로 처리됩니다.

따라서 로그 항목의 페이로드에 대해 다음와 같은 BigQuery 이름이 정의됩니다.

  jsonpayload_v1_customtype
  jsonpayload_v1_customtype._type
  jsonpayload_v1_customtype.name_b
  jsonpayload_v1_customtype.name_b.sub_b
  jsonpayload_v1_customtype.name_a
  jsonpayload_v1_customtype.name_a.sub_a

감사 로그 필드

BigQuery로 라우팅된 감사 로그로 작업하지 않을 경우 이 섹션을 건너뛰어도 됩니다.

감사 로그 페이로드 필드 protoPayload.request, protoPayload.response, protoPayload.metadata@type 지정자가 있지만 JSON 데이터로 처리됩니다. 즉, 이러한 필드의 BigQuery 스키마 이름은 해당 필드 이름에 Json이 붙은 형태이며 JSON 형식의 문자열 데이터를 포함합니다.

다음 표에는 감사 로그 페이로드의 두 가지 필드 이름이 나와 있습니다.

로그 항목 필드 BigQuery 필드 이름
protoPayload protopayload_auditlog
protopayload.metadata protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
예: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.responseJson

serviceData 이름 지정 규칙은 BigQuery에 의해 생성된 후 Cloud Logging에서 BigQuery로 라우팅된 감사 로그에만 적용됩니다. 이러한 감사 로그 항목에는 @type 지정자 type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata가 있는 serviceData 필드가 포함됩니다.

예시

BigQuery에 의해 생성되는 감사 로그 항목에는 다음과 같은 이름의 필드가 있습니다.

protoPayload.serviceData.tableInsertRequest

나중에 이 로그 항목이 BigQuery로 라우팅된다면 tableInsertRequest 필드는 어떻게 참조될까요? 이름을 축약하기 전 BigQuery의 해당 필드 이름은 다음과 같습니다.

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

이름을 축약한 후에는 다음과 같이 BigQuery 테이블의 동일한 필드가 참조됩니다.

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

파티션을 나눈 테이블

이 섹션에서는 BigQuery로 라우팅되는 로그의 파티션을 나눈 테이블에 대해 간략히 설명합니다.

BigQuery 데이터 세트로 로그를 라우팅하면 Logging에서 로그 항목을 저장할 테이블을 만듭니다. Logging은 라우팅하는 데이터를 날짜로 샤딩된 테이블파티션을 나눈 테이블이라는 두 가지 테이블 유형으로 정리합니다. 두 테이블 유형은 모두 로그 항목의 timestamp 필드를 기준으로 로그 데이터를 서로 다른 파티션으로 나눕니다. 그러나 이러한 테이블 유형에는 다음과 같은 두 가지 주요 차이점이 있습니다.

  • 성능: 파티션을 나눈 테이블은 큰 테이블을 작은 파티션으로 나누므로 쿼리 성능을 높일 수 있으며, 따라서 쿼리에서 읽는 바이트 수를 줄여 BigQuery 비용을 제어할 수 있습니다.

  • 테이블 명명법: 테이블 유형에 서로 다른 명명 규칙이 사용되며, 이에 대해서는 아래 섹션에서 설명합니다.

테이블 구성

로그 항목은 항목의 로그 이름과 타임스탬프를 기반으로 하는 조직 및 이름이 있는 BigQuery 테이블로 샤딩됩니다.

테이블 이름에 ISO 8601 기본 형식(YYYYMMDD)을 사용하여 로그 항목의 UTC 타임스탬프 캘린더 날짜를 서픽스로 붙입니다.

다음 표에는 로그 이름 및 샘플 타임스탬프가 BigQuery의 테이블 이름에 매핑되는 방식을 보여주는 몇 가지 예시가 나와 있습니다.

로그 이름 로그 항목 timestamp BigQuery 테이블 이름
(날짜로 샤딩됨)
BigQuery 테이블 이름
(파티션 나뉨)
syslog 2017-05-23T18:19:22.135Z syslog_20170523 syslog
apache-access 2017-01-01T00:00:00.000Z apache_access_20170101 apache_access
compute.googleapis.com/activity_log 2017-12-31T23:59:59.999Z compute_googleapis_com_activity_log_20171231 compute_googleapis_com_activity_log

파티션을 나눈 테이블 만들기

로그를 BigQuery로 라우팅할 싱크를 만들 때 날짜로 샤딩된 테이블이나 파티션을 나눈 테이블을 사용할 수 있습니다. 기본적으로는 날짜로 샤딩된 테이블이 선택됩니다.

Google Cloud Console을 사용하는 방법은 싱크 구성 및 관리를 참조하세요.

gcloud 명령줄 도구 사용 안내는 gcloud logging sinks create를 참조하세요.

스키마 불일치

BigQuery에서 수신된 첫 번째 로그 항목이 대상 BigQuery 테이블의 스키마를 결정합니다. BigQuery는 첫 번째 로그 항목의 필드와 유형을 기반으로 한 열을 포함하는 테이블을 만듭니다.

로그 항목이 대상 테이블에 기록되고 다음 오류 중 하나가 발생하면 스키마 불일치가 발생합니다.

  • 나중의 로그 항목은 테이블에 있는 기존 필드의 필드 유형을 변경합니다.

    예를 들어 초기 로그 항목의 jsonPayload.user_id 필드가 string이면 해당 로그 항목은 해당 필드의 문자열 유형이 있는 테이블을 생성합니다. 나중에 jsonPayload.user_idarray로 로깅하기 시작하면 스키마 불일치가 발생합니다.

  • 새 필드가 로그 항목에 추가되면 대상 테이블의 열 수가 BigQuery 열 제한을 초과합니다. 열 제한에 대한 상세 설명은 BigQuery 할당량 및 한도를 참조하세요.

BigQuery는 스키마 불일치를 식별한 후 해당 데이터 세트 내에 오류 정보를 저장할 테이블을 만듭니다. 테이블 유형에 따라 테이블 이름이 결정됩니다. 날짜로 샤딩된 테이블의 경우 이름 지정 형식은 export_errors_YYYYMMDD입니다. 파티션을 나눈 테이블의 이름 지정 형식은 export_errors입니다. 자세한 내용은 테이블 구성을 참조하세요.

로그 항목을 라우팅할 때 Logging은 BigQuery에 메시지를 일괄 전송합니다. BigQuery는 다음 규칙을 사용하여 현재 메시지 배치의 로그 항목이 기록되는 테이블을 결정합니다.

  • 필드 유형이 변경되면 스키마 불일치를 유발한 로그 항목만 오류 테이블에 기록됩니다. 스키마 불일치를 일으키지 않는 현재 메시지 배치의 로그 항목은 원래 대상 테이블에 기록됩니다.

  • 열 한도를 초과하면 현재 메시지 배치에 있는 모든 로그 항목이 오류 테이블에 기록됩니다.

오류 테이블에는 LogEntry의 데이터와 불일치에 대한 정보가 포함됩니다.

  • 오류 테이블에 기록되는 LogEntry 필드:

    • logName
    • timestamp
    • receiveTimestamp
    • severity
    • insertId
    • trace
    • resource.type
  • 오류 테이블에 기록되는 스키마 불일치 정보:

    • 로그 싱크의 전체 리소스 경로
    • BigQuery에서 반환한 전체 오류 메시지
    • 전체 로그 항목. 그러나 로그 항목은 JSON에서 문자열로 변환됨

Logging은 다음과 같은 방식으로 라우팅 싱크를 포함하는 Cloud 프로젝트에 스키마 불일치를 전달합니다.

  • 프로젝트 소유자에게 이메일을 전송합니다. 세부정보에 Google Cloud 프로젝트 ID, 싱크 이름, 대상을 포함합니다.
  • Google Cloud Console 활동 페이지에 Stackdriver Config error라는 오류를 표시합니다. 세부정보에는 싱크 이름과 대상, 그리고 오류를 유발한 로그 항목의 예시에 대한 링크가 포함됩니다.
  • 시스템 로그 기반 측정항목 exports/error_count는 오류로 인해 라우팅된 로그 항목의 총 개수를 알려줍니다.

이후 로그 항목의 필드-유형 불일치를 수정하려면 필드 유형을 현재 스키마와 일치하도록 수정하세요. Logging이 다른 데이터세트에서 테이블을 다시 만들도록 테이블 이름을 바꾸거나 싱크의 매개변수를 변경할 수도 있습니다. 자세한 내용은 싱크 구성 및 관리를 참조하세요.

로그 보기

BigQuery에서 라우팅된 로그를 보는 방법은 싱크 대상의 로그 보기를 참조하세요.