내보낸 로그의 BigQuery 스키마

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

Logging은 로드 작업을 사용하는 대신 한 번에 레코드 한 개씩 BigQuery에 로깅 데이터를 스트리밍합니다. 이 방법을 사용하면 로드 작업의 실행 지연 없이 BigQuery에서 데이터를 쿼리할 수 있습니다. 자세한 내용은 BigQuery로 데이터 스트리밍을 참조하세요.

내보낸 로그의 BigQuery 테이블 스키마는 LogEntry 유형의 구조와 로그 페이로드의 콘텐츠에 기반합니다. 또한 Cloud Logging은 감사 로그의 BigQuery 스키마 필드 이름을 짧게 줄이기 위해 몇 가지 특수 규칙을 적용합니다. BigQuery 웹 UI에서 내보낸 로그 항목이 있는 테이블을 선택하면 테이블 스키마를 볼 수 있습니다.

필드 이름 지정 규칙

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

  • LogEntry 유형에 속하는 로그 항목 필드의 경우 해당 BigQuery 필드 이름이 로그 항목 필드와 정확히 일치합니다.
  • 사용자가 제공한 필드의 경우 문자의 대소문자 구분이 소문자로 정규화되지만 그 밖의 이름 지정 규칙은 유지됩니다.

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

      @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

구조화된 페이로드 필드를 BigQuery 필드 이름에 매핑할 때 구조화된 필드에 @type 지정자가 포함되어 있으면 매핑이 좀더 복잡합니다. 이에 대해서는 다음 섹션에서 설명합니다.

@type이 있는 페이로드 필드

이 섹션에서는 페이로드에 형식 지정자(@type 필드)가 포함되어 있는 로그 항목의 특수한 BigQuery 스키마 필드 이름에 대해 설명합니다. 여기에는 BigQuery에 있는 내보낸 감사 로그 항목이 포함됩니다. 예를 들어 이 섹션에서는 감사 로그 항목의 protoPayload 필드가 BigQuery 스키마 필드 protopayload_auditlog에 매핑될 수 있는 이유를 설명합니다.

스키마 이름 지정 규칙

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

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

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

예를 들어 다음 표는 최상위 수준의 구조화된 페이로드 필드를 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

jsonPayload 또는 protoPayload에 다른 구조화된 필드가 포함되어 있으면 그 내부 필드는 다음과 같이 매핑됩니다.

  • 중첩된 구조화된 필드에 @type 지정자가 없으면 BigQuery 필드 이름은 소문자로 정규화된다는 점을 제외하고 원래 필드 이름과 동일합니다.
  • 중첩된 구조화된 필드에 @type 지정자가 있으면 BigQuery 필드 이름에 [TYPE](고쳐 씀)이 추가되고 필드 이름이 소문자로 정규화됩니다.

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

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

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

예시

이 예시는 구조화된 페이로드 필드로 내보낸 BigQuery가 어떻게 사용되고 이름이 지정되는지 보여줍니다.

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

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

이 경우 BigQuery 필드에 매핑되는 방식은 다음과 같습니다.

  • 필드 jsonPayloadname_a는 구조화되어 있지만 @type 지정자가 없습니다. 이 필드의 BigQuery 이름은 각각 jsonPayloadname_a입니다.

  • 필드 sub_asub_b는 구조화되어 있지 않으므로 BigQuery 이름은 각각 sub_asub_b입니다.

  • 필드 name_b에는 @type 지정자가 있으며 [TYPE]은 google.cloud.v1.SubType입니다. 따라서 BigQuery 이름은 name_b_google_cloud_v1_subtype입니다.

요컨대 로그 항목 페이로드에는 다음과 같은 5개의 BigQuery 이름이 정의됩니다.

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

내보낸 감사 로그의 필드

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 필드는 어떻게 참조될까요? 내보내지는 필드의 축약 전 이름은 다음과 같을 것입니다.

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 테이블에 배치됩니다.

다음 표에는 로그 이름 및 샘플 타임스탬프가 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을 사용하는 방법은 로그 뷰어로 내보내기를 참조하세요.

명령줄 인터페이스인 Cloud SDK를 사용하는 방법은 gcloud alpha logging sinks create를 참조하세요.

스키마 불일치

첫 번째로 내보내지는 로그 항목에 따라 대상 BigQuery 테이블의 스키마가 결정됩니다. 이 로그 항목의 필드와 유형을 기반으로 한 열을 포함하는 테이블이 생성됩니다. 이후 로그 항목에 새로운 필드가 나타나면 테이블 스키마가 업데이트됩니다. 그러나 기존 필드의 값 유형이 변경될 경우에는 스키마와 일치하지 않는 최신 로그 항목이 삭제됩니다.

예를 들어 초기 내보내기에 jsonPayload.user_idstring인 로그 항목이 포함된 경우 해당 로그 항목은 해당 필드에 대한 문자열 유형이 있는 테이블을 생성합니다. jsonPayload.user_idarray로 로깅하기 시작하면 해당 로그 항목은 테이블에 삽입되지 않고 손실됩니다.

Logging은 내보내기가 포함된 Google Cloud 프로젝트의 데이터 손실을 다음과 같은 방식으로 전달합니다.

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

이후 로그 항목의 문제를 해결하여 더 이상 데이터 손실이 발생하지 않도록 하려면 필드 유형을 현재 스키마와 일치하도록 수정합니다. Logging이 다른 데이터세트에서 테이블을 다시 만들도록 테이블 이름을 바꾸거나 싱크의 매개변수를 변경할 수도 있습니다. 자세한 내용은 싱크 업데이트를 참조하세요.

로그 보기

BigQuery 웹 UI를 사용하여 로그를 보려면 내보낸 로그 항목이 포함된 테이블을 선택하세요.