커스텀 색인 생성 구성

이 문서에서는 색인 생성된 LogEntry 필드를 Cloud Logging 버킷에 추가하여 로그 데이터를 더 빠르게 쿼리하는 방법을 설명합니다.

개요

쿼리 성능은 모든 로깅 솔루션에 중요합니다. 워크로드가 확장되고 해당 로그 볼륨이 증가함에 따라 가장 자주 사용되는 로그 데이터를 색인으로 생성하면 쿼리 시간을 줄일 수 있습니다.

쿼리 성능을 향상시키기 위해 Logging은 다음 LogEntry 필드를 자동으로 색인으로 생성합니다.

• resource.type
• resource.labels.*
• logName
• severity
• timestamp
• insertId
• operation.id
• trace
• httpRequest.status
• labels.*
• split.uid

Logging이 자동으로 색인을 생성하는 필드 외에도 버킷에 대해 커스텀 색인을 만들어 다른 LogEntry 필드를 색인으로 생성하도록 로그 버킷을 지정할 수 있습니다.

예를 들어 쿼리 표현식에 jsonPayload.request.status 필드가 자주 포함된다고 가정해보세요. jsonPayload.request.status가 포함된 버킷에 대해 커스텀 색인을 구성하면 쿼리 표현식에 이 필드가 포함된 경우 이 버킷의 데이터에 대한 모든 후속 쿼리에서 색인으로 생성된 jsonPayload.request.status 데이터가 참조됩니다.

Google Cloud CLI 또는 Logging API를 사용하여 기존 또는 새 로그 버킷에 커스텀 색인을 추가할 수 있습니다. 커스텀 색인에 포함할 추가 필드를 선택할 때는 다음 제한사항에 주의하세요.

• 커스텀 색인당 최대 20개까지 필드를 추가할 수 있습니다.
• 버킷의 커스텀 인덱스를 구성하거나 업데이트한 후에는 변경사항이 쿼리에 적용되도록 1시간 정도 기다려야 합니다. 이러한 지연 시간은 정확한 쿼리 결과를 보장하고 이전에 기록된 로그가 적용되게 해줍니다.
• Logging은 색인이 생성되거나 변경된 후 로그 버킷에 저장된 데이터에 커스텀 색인 생성을 적용합니다. 커스텀 색인 변경사항은 로그에 소급 적용되지 않습니다.

시작하기 전에

커스텀 색인을 구성하려면 먼저 다음을 수행합니다.

• 최신 버전의 gcloud CLI를 사용하고 있는지 확인합니다. 자세한 내용은 Google Cloud CLI 구성요소 관리를 참조하세요.

  참고: 이 문서의 gcloud CLI 예에서는 올바른 프로젝트를 업데이트하도록 gcloud CLI가 구성되었다고 가정합니다. 명령어에서 프로젝트를 지정하려면 --project 플래그를 포함하고 Google Cloud 프로젝트 ID를 지정합니다.

• 다음 권한이 있는 Identity and Access Management 역할이 있는지 확인합니다.

  • roles/logging.admin
  • roles/logging.configWriter

  이러한 역할에 대한 자세한 내용은 IAM을 사용한 액세스 제어를 참조하세요.

커스텀 색인 정의

버킷의 커스텀 색인에 추가하는 각 필드에 대해 필드 경로와 필드 유형의 두 가지 속성을 정의합니다.

• fieldPath: 로그 항목에서 LogEntry 필드에 대한 특정 경로를 설명합니다. 예를 들면 jsonPayload.req_status입니다.
• type: 필드가 문자열 또는 정수 유형인지를 나타냅니다. 가능한 값은 INDEX_TYPE_STRING 및 INDEX_TYPE_INTEGER입니다.

커스텀 색인은 새 버킷을 만들거나 기존 버킷을 업데이트하여 추가할 수 있습니다. 버킷 구성에 대한 자세한 내용은 로그 버킷 구성을 참조하세요.

버킷을 만들 때 커스텀 색인을 구성하려면 다음을 수행합니다.

gcloud

gcloud logging buckets create 명령어를 사용하고 --index 플래그를 설정합니다.

gcloud logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

명령어 예시:

gcloud logging buckets create int_index_test_bucket \
--location=global \
--description="Bucket with integer index" \
--index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

버킷을 만들려면 Logging API에서 projects.locations.buckets.create를 사용합니다. 메서드의 인수를 다음과 같이 준비하세요.

1. parent 매개변수를 버킷을 만들 리소스 projects/PROJECT_ID/locations/LOCATION으로 설정합니다.

   LOCATION 변수는 로그를 저장할 리전을 나타냅니다.

   예를 들어 asia-east2 리전에서 my-project 프로젝트에 대해 버킷을 만들려는 경우 parent 매개변수는 projects/my-project/locations/asia-east2와 같습니다.

2. bucketId 매개변수를 설정합니다. 예를 들면 my-bucket입니다.

3. LogBucket 요청 본문에서 커스텀 색인을 만들도록 IndexConfig 객체를 구성합니다.

4. projects.locations.buckets.create를 호출하여 버킷을 만듭니다.

커스텀 색인을 포함하도록 기존 버킷을 업데이트하려면 다음을 수행합니다.

gcloud

gcloud logging buckets update 명령어를 사용하고 --add-index 플래그를 설정합니다.

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

명령어 예시:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \ --add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Logging API에서 projects.locations.buckets.patch를 사용합니다. LogBucket 요청 본문에서 색인을 생성하려는 LogEntry 필드를 포함하도록 IndexConfig 객체를 구성합니다.

커스텀 색인 생성된 필드 삭제

버킷의 커스텀 색인에서 필드를 삭제하려면 다음을 수행합니다.

gcloud

gcloud logging buckets update 명령어를 사용하고 --remove-indexes 플래그를 설정합니다.

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=INDEX_FIELD_NAME

명령어 예시:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

Logging API에서 projects.locations.buckets.patch를 사용합니다. LogBucket 요청 본문에서 IndexConfig 객체의 LogEntry 필드를 삭제합니다.

커스텀 색인 생성된 필드의 데이터 유형 업데이트

커스텀 색인 생성된 필드의 데이터 유형을 수정하려면 다음을 수행합니다.

gcloud

gcloud logging buckets update 명령어를 사용하고 --update-index 플래그를 설정합니다.

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

명령어 예시:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Logging API에서 projects.locations.buckets.patch를 사용합니다. LogBucket 요청 본문에서 IndexConfig 객체를 업데이트하여 LogEntry 필드에 올바른 데이터 유형을 제공합니다.

커스텀 색인 생성된 필드의 경로 업데이트

커스텀 색인 생성된 필드의 필드 경로를 수정해야 할 경우 다음을 수행합니다.

gcloud

gcloud logging buckets update 명령어를 사용하고 --remove-indexes 및 --update-index 플래그를 설정합니다.

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

명령어 예시:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status_old_path \
--add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER

API

Logging API에서 projects.locations.buckets.patch를 사용합니다. LogBucket 요청 본문에서 IndexConfig 객체를 업데이트하여 LogEntry 필드에 올바른 필드 경로를 입력합니다.

버킷의 모든 색인 생성된 필드 나열

커스텀 색인 생성된 필드를 포함하여 버킷의 세부정보를 나열하려면 다음을 수행합니다.

gcloud

gcloud logging buckets describe 명령어를 사용합니다.

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

명령어 예시:

gcloud logging buckets describe indexed-bucket \
--location global

API

Logging API에서 projects.locations.buckets.get를 사용합니다.

커스텀 색인 생성된 필드 삭제

버킷에서 모든 커스텀 색인 생성된 필드를 삭제하려면 다음을 수행합니다.

gcloud

gcloud logging buckets update 명령어를 사용하고 --clear-indexes 플래그를 추가합니다.

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--clear-indexes

명령어 예시:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--clear-indexes

API

Logging API에서 projects.locations.buckets.patch를 사용합니다. LogBucket 요청 본문에서 IndexConfig 객체를 삭제합니다.

색인 생성된 데이터 쿼리 및 보기

커스텀 색인 생성된 필드에 포함된 데이터를 쿼리하려면 커스텀 색인 생성된 필드가 포함된 버킷으로 쿼리 범위를 제한하고 적합한 로그 보기를 지정합니다.

gcloud

로그 버킷에서 로그를 읽으려면 gcloud 로깅 읽기 명령어를 사용하고 색인 생성된 데이터를 포함하도록 LOG_FILTER를 추가합니다.

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID

API

로그 버킷에서 로그를 읽으려면 entries.list 메서드를 사용합니다. resourceNames를 설정해서 적절한 버킷 및 로그 보기를 지정하고 filter를 설정해서 색인 생성된 데이터를 선택합니다.

필터링 구문에 대한 자세한 내용은 Logging 쿼리 언어를 참조하세요.

색인 생성 및 필드 유형

커스텀 필드 색인 생성 구성 방법에 따라 로그 버킷에 로그가 저장되는 방식과 쿼리가 처리되는 방식이 영향을 받을 수 있습니다.

쓰기 시간

Logging이 색인 생성 후 로그 버킷에 저장된 데이터에 커스텀 색인을 사용하려고 시도합니다.

색인이 생성된 필드의 유형이 지정되며 이는 로그 항목의 타임스탬프에 영향을 미칩니다. 로그 항목이 로그 버킷에 저장되면 로그 필드가 다음 규칙을 통해 색인 유형에 대해 평가됩니다.

• 필드 유형이 색인 유형과 동일하면 데이터가 색인에 그대로 추가됩니다.
• 필드 유형이 색인 유형과 다르면 Logging이 이를 색인 유형에 맞게 변환하려고 시도합니다(예: 정수에서 문자열로 변환).
  • 유형 강제 변환이 실패하면 데이터가 색인으로 생성되지 않습니다. 유형 강제 변환이 성공하면 데이터가 색인으로 생성됩니다.

쿼리 시

필드에 색인을 사용 설정하면 해당 필드의 쿼리 방법이 변경됩니다. 기본적으로 Logging은 평가 중인 각 로그 항목의 데이터 유형을 기준으로 필드에 필터 제약조건을 적용합니다. 색인 생성이 사용 설정되었으면 필드에 대한 필터 제약조건이 색인 유형을 기준으로 적용됩니다. 필드에 색인을 추가하면 해당 필드에 스키마가 적용됩니다.

커스텀 색인이 버킷에 대해 구성된 경우에는 이러한 조건이 모두 충족될 때 스키마 일치 동작이 달라집니다.

• 필드의 소스 데이터 유형은 해당 필드의 색인 유형과 일치하지 않습니다.
• 사용자가 해당 필드에 제약조건을 적용합니다.

다음 JSON 페이로드를 고려해보세요.

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

이제 이 필터를 각 항목에 적용합니다.

jsonPayload.value > 20

jsonPayoad.value 필드에 커스텀 색인 생성이 없으면 Logging이 가변형 유형의 일치를 적용합니다.

• 'A'의 경우 Logging에서는 'value' 키의 값이 실제로 정수이고 제약조건 '20'을 정수로 변환할 수 있다는 것이 관찰됩니다. 그런 다음 Logging이 12345 > 20을 평가하고 이 결과가 숫자에 해당하기 때문에 'true'를 반환합니다.

• 'B'의 경우에는 Logging에서 'value' 키의 값이 실제로 문자열인 것으로 확인됩니다. 그런 후 "3" > "20"을 평가하고 결과가 영숫자에 해당하기 때문에 'true'를 반환합니다.

jsonPayload.value 필드가 커스텀 색인에 포함된 경우에는 Logging이 일반적인 Logging 논리 대신 색인을 사용하여 제약조건을 평가합니다. 이러한 동작이 변경됩니다.

• 색인이 문자열 유형이면 모든 비교가 문자열 비교로 수행됩니다.
  • '12345'가 영숫자 측면에서는 '20'보다 크지 않기 때문에 'A' 항목이 일치하지 않습니다. 문자열 '3'은 '20'보다 크기 때문에 'B' 항목이 일치합니다.
• 색인이 정수 유형이면 모든 비교가 정수 비교로 수행됩니다.
  • 숫자 측면에서 '3'이 '20'보다 크지 않기 때문에 'B' 항목이 일치하지 않습니다. '12345'는 '20'보다 크기 때문에 'A' 항목이 일치합니다.

이러한 동작은 차이가 크지 않으며 커스텀 색인을 정의하고 사용할 때 주의가 필요합니다.

필터링 특이 사례

jsonPayload.value 정수 유형 색인의 경우 문자열 값이 필터링된다고 가정해 보세요.

jsonPayload.value = "hello"

쿼리 값을 색인 값으로 변환할 수 없으면 색인이 무시됩니다.

하지만 문자열 유형 색인에는 정수 값을 전달한다고 가정해 보세요.

jsonPayload.value > 50

'12345'나 '3' 중 어느 것도 영숫자 측면에서 '50보다 크기 때문에 A와 B 모두 일치하지 않습니다.