내보낸 로그의 BigQuery 스키마

내보낸 로그의 BigQuery 테이블 스키마는 LogEntry 유형의 구조와 로그 페이로드의 콘텐츠에 기반을 둡니다. 또한 Stackdriver 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

구조화된 필드에 @type 지정자가 포함되어 있으면 구조화된 페이로드 필드를 BigQuery 필드 이름에 매핑하는 것이 더 복잡합니다. 여기에 관해서는 아래 섹션에서 설명합니다.

@type이 있는 페이로드 필드

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

현재 BigQuery에는 감사 로그 항목을 위한 두 가지 스키마가 있습니다. 여기서 두 가지 스키마란 현재 일부 감사 로그 페이로드 정보가 2가지 BigQuery 필드에 중복되어 존재한다는 것을 의미합니다. 이러한 필드에는 기존의 '확장형' 필드 이름과 새로운 '축약형' 필드 이름이라는 서로 다른 형식으로 정보가 포함되어 있습니다. 2019년 3월 1일자로 기존의 스키마(필드 이름)는 삭제됩니다. 자세한 내용은 아래의 업데이트된 스키마로 마이그레이션 섹션을 참조하세요.

스키마 이름 지정 규칙

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

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

형식 지정자가 있는 구조화된 필드에는 일반적으로 필드 이름에 [TYPE]이 붙는 BigQuery 필드 이름이 지정됩니다.

예를 들어 다음 표는 최상위 수준의 구조화된 페이로드 필드를 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입니다. 쿼리의 App Engine 로그 쿼리 예시에서 이를 확인할 수 있습니다.

  • Stackdriver Logging은 감사 로그의 BigQuery 스키마 필드 이름을 짧게 줄이기 위해 몇 가지 특수 규칙을 적용합니다. 여기에 관해서는 아래의 감사 로그 스키마 필드 섹션에서 설명합니다.

  • 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로 내보낸 감사 로그로 작업하지 않을 경우 이 섹션을 건너뛰어도 됩니다.

기존('확장형') 감사 로그 페이로드 필드 모두에는 Stackdriver의 형식 지정자(@type 필드)가 있습니다. 이 경우 해당 BigQuery 필드 이름은 너무 길어지지 않도록 특수하게 구성됩니다.

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

감사 로그 페이로드 필드 이름의 이 두 가지 세트를 다음 표에 나열하였습니다.

로그 항목 필드 확장형(기존) BigQuery 필드 이름 축약형(새로운) BigQuery 필드 이름
protoPayload protopayload_auditlog 동일
protopayload.metadata protopayload_auditlog.metadata_* protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
예: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
동일
protoPayload.request protopayload_auditlog.request_[Vn]_[PROTO_NAME]
예: protopayload_auditlog.request_v2_listlogsinksrequest
protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.response_[Vn]_[PROTO_NAME]
예: protopayload_auditlog.response_v2_listlogsinksresponse
protopayload_auditlog.responseJson

기존의 확장형 스키마(필드 이름)이 삭제되는 2019년 3월 1일 이전에 새로운 축약형 스키마(필드 이름)를 사용하도록 쿼리를 수정해야 합니다.

로그 이름 지정에 관한 다음 사항에 유의하세요.

  • serviceData 이름 지정 규칙은 BigQuery에 의해 생성된 후 BigQuery로 내보내지는 감사 로그에만 적용됩니다. 이러한 감사 로그 항목에는 다음과 같은 @type 지정자가 있는 serviceData 필드가 포함되어 있습니다.

    type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
    
  • 확장형(기존) requestresponse 필드의 이름 지정 규칙은 형식 지정자가 다음과 같은 일반적인 형식을 따른다고 가정합니다.

    [GOOGLE_SERVICE].[Vn].[PROTO_NAME]
    

    예를 들어 request 필드에서 형식 지정자는 다음과 같을 수 있습니다.

    google.logging.v2.ListLogSinksRequest
    

    마침표를 밑줄로 대체하고 소문자로 변경하면 다음과 같은 일반적인 필드 이름이 됩니다.

    request_google_logging_v2_listlogsinksrequest
    

    특수하게 구성된 스키마 필드 이름은 다음과 같습니다.

    request_v2_listlogsinksrequest
    

    다른 패턴의 형식 지정자가 있을 경우 내보낸 로그 항목 일부를 검토하여 내보내진 필드 이름이 어떻게 축약되어 있는지 확인하세요.

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의 감사 로그 항목에는 '확장형'과 '축약형'의 두 가지 필드 이름 세트가 존재합니다. 2019년 3월 1일부터 필드 이름의 확장형 세트가 삭제됩니다. 쿼리를 검토하여 새로운 필드 이름 세트로 마이그레이션해야 할지 결정하세요.

  • 현재 BigQuery 쿼리에 내보내진 감사 로그에서 request, response, requestMetadata 필드를 사용하고 있지 않다면 마이그레이션을 수행해도 아무런 영향이 없습니다. 이 섹션을 건너뛰세요.

  • request, response 또는 requestMetadata 필드를 처음으로 사용하는 경우 먼저 축약형(새로운) 이름을 사용합니다. 신규 서비스에서 생성되는 모든 감사 로그는 새로운 축약형 형태만 사용합니다. 이 섹션을 건너뛰세요.

  • BigQuery 쿼리에서 내보낸 감사 로그에서 request, response 또는 requestMetadata 필드를 사용하고 확장형(기존) 필드 이름을 사용하고 있으면 가능한 한 빨리 축약형(새로운) 이름으로 전환합니다. 이 섹션을 읽어보고 쿼리 업데이트에서 쿼리 업데이트 방법의 예를 확인하세요.

이러한 변화는 관리자 활동 감사 로그와 데이터 액세스 감사 로그 모두에 영향을 미쳐서 필드 개수가 임의의 수인 현재의 확장형에서 업데이트된 축약형 JSON 형식으로 변환됩니다. 기존의 감사 로그의 경우 Stackdriver Logging이 이미 새로운 축약형으로 작성하고 있습니다.

축약형 스키마

확장형이 삭제되는 2019년 3월 1일까지는 BigQuery에서 두 가지 형식을 모두 볼 수 있습니다.

감사 로그를 제외한 다른 로그의 내보내기는 영향을 받지 않습니다. BigQuery가 아닌 다른 위치로 감사 로그를 내보내는 경우에도 영향을 받지 않습니다.

쿼리 업데이트

감사 로그 스키마 필드 표에는 확장형 필드 이름에서 축약형 필드 이름으로 변경됨에 따라 영향을 받는 필드의 목록이 나와 있습니다. 이러한 필드를 쿼리할 경우 BigQuery 쿼리를 검토하여 필요한 경우 기존 필드가 삭제되는 2019년 3월 1일 이전에 수정해야 합니다.

쿼리를 업데이트하려면 BigQuery JSON_EXTRACT() 메소드를 사용해야 합니다. 이러한 필드의 @type 지정자는 JSON 데이터의 내용 설명으로 처리되어야 합니다.

예를 들어 createSinkRequest 필드 중 하나를 선택하는 쿼리에 확장형 필드 이름을 사용하면 다음과 같은 형태가 됩니다.

 SELECT protopayload_auditlog.request_v2_createsinkrequest.sink.destination
 as dest FROM ...

축약형 필드 이름으로 변경된 후 구문의 형태는 다음과 같은 모습일 것입니다.

SELECT JSON_EXTRACT(protopayload_auditlog.requestJson, '$.sink.destination')
as dest FROM ...

감사 로그 보기

기존의 감사 로그의 경우 Stackdriver Logging은 새로운 축약형과 기존의 확장형 모두로 작성합니다. 확장형이 삭제되는 2019년 3월 1일까지는 BigQuery에서 두 가지 형식을 모두 볼 수 있습니다.

감사 로그를 보려면 BigQuery 웹 UI에서 내보낸 로그 항목이 있는 표를 선택합니다.

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Stackdriver Logging
도움이 필요하시나요? 지원 페이지를 방문하세요.