BigQuery로 라우팅된 로그 보기

이 문서에서는 Cloud Logging에서 BigQuery 테이블로 라우팅한 로그 항목을 찾는 방법을 설명합니다. Logging 싱크는 데이터를 작은 배치로 BigQuery에 스트리밍하므로 로드 작업을 실행하지 않고도 데이터를 쿼리할 수 있습니다. 쿼리를 만들고 BigQuery 테이블의 형식을 이해하는 데 도움이 되도록 이 문서에서는 라우팅된 로그의 BigQuery 스키마에 대해서도 설명합니다.

Cloud Logging은 기존 스트리밍 API를 사용하여 로그 항목을 BigQuery로 스트리밍합니다. 일반적으로 로그 항목은 1분 이내에 BigQuery에 표시됩니다. 하지만 새 테이블이 생성되면 첫 번째 로그 항목을 사용할 수 있기까지 몇 분이 걸릴 수 있습니다.

시작하기 전에

싱크에 대한 개념 설명은 라우팅 및 스토리지 모델 개요: 싱크를 참조하세요.

로그를 라우팅하는 방법에 대한 자세한 내용은 지원되는 대상으로 로그 라우팅을 참조하세요.

라우팅된 로그 항목 필드의 이름을 지정하는 방법을 알아보려면 라우팅된 로그의 BigQuery 스키마를 참조하세요.

로그 보기

BigQuery로 라우팅된 로그를 보려면 다음을 수행하세요.

  1. Google Cloud console에서 BigQuery 페이지로 이동합니다.

    BigQuery Studio로 이동

    검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

  2. 탐색기 패널에서 프로젝트를 확장하고 데이터 세트를 선택합니다.

    세부정보 탭에서 로그 항목을 보거나 테이블을 쿼리하여 데이터를 반환할 수 있습니다.

샘플 쿼리

BigQuery 쿼리 구문에 대한 자세한 내용은 쿼리 참조를 확인하세요. 특히 테이블 와일드 카드 함수는 여러 테이블에서 쿼리하는 데, flatten 연산자는 반복되는 필드의 데이터를 표시하는 데 유용합니다.

샘플 Compute Engine 쿼리

다음 BigQuery 쿼리는 여러 날짜와 여러 로그 유형의 로그 항목을 가져옵니다.

  • 쿼리는 지난 3일 동안의 syslog 및 apache-access 로그를 검색합니다. 즉, 2020년 2월 23일에 생성된 쿼리에는 2월 21일과 2월 22일에 수신된 모든 로그 항목과 2월 23일에 쿼리가 실행된 시간까지 수신된 모든 로그 항목이 포함됩니다.

  • 쿼리는 단일 Compute Engine 인스턴스 1554300700000000000의 결과를 가져옵니다.

SELECT
  timestamp AS Time,
  logName as Log,
  textPayload AS Message
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.syslog_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())),
  (TABLE_DATE_RANGE(my_bq_dataset.apache_access_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP()))
WHERE
  resource.type == 'gce_instance'
  AND resource.labels.instance_id == '1554300700000000000'
ORDER BY time;

다음은 몇 가지 출력 행의 예시입니다.

Row | Time                    | Log                                         | Message
--- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------
 5  | 2020-02-21 03:40:14 UTC | projects/project-id/logs/syslog             | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269;
 6  | 2020-02-21 04:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 7  | 2020-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2020:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2020-02-21 05:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 9  | 2020-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2020:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

샘플 App Engine 쿼리

다음 BigQuery 쿼리는 지난 달에 실패한 App Engine 요청을 가져옵니다.

SELECT
  timestamp AS Time,
  protoPayload.host AS Host,
  protoPayload.status AS Status,
  protoPayload.resource AS Path
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_,
    DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP()))
WHERE
  protoPayload.status != 200
ORDER BY time

일부 결과는 다음과 같습니다.

Row | Time                    | Host                                  | Status | Path
--- | ----------------------- | ------------------------------------- | ------ | ------
 6  | 2020-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2020-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2020-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2020-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

라우팅된 로그의 BigQuery 스키마

라우팅된 로그의 BigQuery 테이블 스키마는 LogEntry 유형의 구조와 로그 페이로드의 콘텐츠에 기반합니다. 또한 Cloud Logging은 감사 로그 및 특정 구조화된 페이로드 필드의 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에서 로그 항목을 저장할 테이블을 만듭니다. BigQuery에서 수신한 첫 번째 로그 항목은 대상 BigQuery 테이블의 스키마를 결정합니다. BigQuery는 첫 번째 로그 항목의 필드와 유형을 기반으로 하는 열이 포함된 테이블을 만듭니다. 이후 로그 항목으로 인해 스키마 불일치가 발생할 수 있습니다. 이러한 상황이 발생하는 시기와 처리 방법에 대한 자세한 내용은 스키마 불일치를 참조하세요.

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

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

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

테이블 구성

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

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

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

로그 이름 로그 항목 timestamp1 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

1 로그 항목 타임스탬프는 UTC(협정 세계시)로 표시됩니다.

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

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

싱크를 만드는 방법은 다음 리소스를 참조하세요.

스키마 불일치

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

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

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

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

  • 새 로그 항목에 현재 스키마에 없는 필드가 포함되며 이 필드를 대상 테이블에 삽입하면 BigQuery 열 한도가 초과됩니다.

    열 제한이 초과되지 않으면 대상 테이블에서 새 필드를 허용할 수 있습니다.

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

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

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

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

오류 테이블 스키마

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

  • logEntry: 전체 로그 항목, 그러나 로그 항목은 JSON에서 문자열로 변환됩니다.
  • schemaErrorDetail: BigQuery에서 반환한 전체 오류 메시지를 포함합니다.
  • sink: 로그 싱크의 전체 리소스 경로를 포함합니다.
  • logName: LogEntry에서 추출됩니다.
  • timestamp: LogEntry에서 추출됩니다.
  • receiveTimestamp: LogEntry에서 추출됩니다.
  • severity: LogEntry에서 추출됩니다.
  • insertId: LogEntry에서 추출됩니다.
  • trace: LogEntry에서 추출됩니다.
  • resourceType: LogEntry에서 추출됩니다.

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

  • 프로젝트 소유자에게 이메일을 전송합니다. 세부정보에 Google Cloud 프로젝트 ID, 싱크 이름, 대상을 포함합니다.
  • Google Cloud 콘솔 활동 페이지에 Stackdriver Config error라는 오류를 표시합니다. 세부정보에는 싱크 이름과 대상, 그리고 오류를 유발한 로그 항목의 예시에 대한 링크가 포함됩니다.

향후 필드 유형 불일치 방지

나중에 로그 항목의 필드 유형 불일치를 수정하려면 필드 유형을 현재 스키마와 일치하도록 수정합니다. 필드 유형을 수정하는 방법에 대한 자세한 내용은 열의 데이터 유형 변경을 참조하세요.

필드 유형을 변경할 수 없는 경우도 있습니다. 예를 들어 Google Cloud 서비스에서 자동으로 생성되는 로그의 필드 유형은 변경할 수 없습니다. 필드 유형을 변경할 수 없는 경우 스키마 불일치를 방지하려면 테이블 이름을 바꾸거나 싱크의 매개변수를 변경하여 Logging이 다른 데이터 세트에서 테이블을 다시 만들도록 합니다. 자세한 내용은 싱크 관리를 참조하세요.

문제 해결

로그가 싱크 대상에서 누락된 것으로 보이거나 싱크가 제대로 로그를 라우팅하지 않는 것으로 의심되는 경우 로그 라우팅 문제 해결을 참조하세요.

가격 책정

Cloud Logging은 로그를 지원되는 대상으로 라우팅하는 데 비용을 청구하지 않지만 대상에 요금이 부과될 수 있습니다. _Required 로그 버킷을 제외하고 Cloud Logging은 로그를 로그 버킷으로 스트리밍하고 로그 버킷의 기본 보관 기간보다 긴 스토리지에 대해 요금을 청구합니다.

Cloud Logging은 로그 복사, 로그 범위 정의, 로그 탐색기 또는 로그 애널리틱스 페이지를 통해 실행되는 쿼리에 대해 요금을 부과하지 않습니다.

자세한 내용은 다음 문서를 참조하세요.