로그 기반 측정항목 라벨 구성

이 문서에서는 로그 기반 측정항목 라벨과 로그 측정항목에서 라벨을 만들고 사용하는 방법을 설명합니다.

라벨에 익숙한 경우 이 페이지에서 라벨 만들기로 바로 이동할 수 있습니다.

로그 기반 측정항목 라벨 개요

라벨을 사용하면 라벨 값의 각 조합에 대해 하나씩 로그 기반 측정항목에 여러 개의 시계열을 포함할 수 있습니다. 모든 로그 기반 측정항목은 기본 라벨과 함께 제공됩니다.

추출기 표현식을 지정하면 카운터 유형과 분포 유형 측정항목 모두에서 사용자 정의 라벨을 추가로 만들 수 있습니다. 추출기 표현식은 로그 항목에서 라벨 값을 추출하는 방법을 Cloud Logging에 알려줍니다. 라벨 값은 다음 중 하나로 지정할 수 있습니다.

  • LogEntry 객체에 있는 명명된 필드의 전체 콘텐츠
  • 정규 표현식(regexp)과 일치하는 명명된 필드의 일부

라벨은 LogEntry 기본 제공 필드(예: httpRequest.status)나 페이로드 필드 textPayload, jsonPayload 또는 protoPayload 중 하나에서 추출할 수 있습니다.

정규 표현식에 관한 자세한 내용은 RE2 구문을 참조하세요.

추출기 표현식에 민감한 정보를 넣지 말고 라벨에 민감한 정보를 추출하지 마세요. 이는 서비스 데이터로 처리됩니다.

사용자 정의 라벨의 제한사항

사용자 정의 라벨에는 다음 제한사항이 적용됩니다.

  • 측정항목당 최대 10개의 사용자 정의 라벨을 만들 수 있습니다.

  • 라벨을 만든 후에는 삭제할 수 없습니다.

    • 이미 만들어진 라벨의 추출기 표현식과 설명을 수정하는 것은 가능합니다.

    • 이미 만들어진 라벨의 이름이나 값 유형은 변경할 수 없습니다.

  • 라벨 값의 첫 1,024자만 유지됩니다.

  • 각 로그 기반 측정항목의 활성 시계열은 약 30,000개로 제한되며, 기본 라벨을 포함해 각 라벨에서 가능한 값의 개수에 따라 달라집니다.

    예를 들어 VM 인스턴스와 같은 리소스 100개에서 로그 항목을 가져오고 가능한 값 20개로 라벨을 정의하는 경우 측정항목에는 최대 2,000개의 시계열이 있을 수 있습니다.

시계열이나 데이터 포인트가 너무 많으면 비용이 높아지고 활동이 제한될 수 있습니다. 로그 기반 측정항목의 비용에 대한 자세한 내용은 Cloud Monitoring 가격 책정: 요금이 부과되는 측정항목을 참조하세요. 로그 기반 측정항목에 적용되는 한도에 대한 자세한 내용은 할당량 및 한도: 로그 기반 측정항목 및 로그 기반 측정항목 문제 해결을 참조하세요.

기본 라벨

모든 로그 기반 측정항목은 사전 정의된 몇 가지 라벨과 함께 제공됩니다.

  • 리소스 라벨: 모든 측정항목은 모니터링 리소스 객체를 사용하여 시계열 데이터의 소스를 식별합니다. 각 리소스 유형에는 유형 이름과 하나 이상의 라벨이 포함되어 있습니다. 리소스 유형의 예로는 VM 인스턴스, Cloud SQL 데이터베이스, 부하 분산기 등이 있습니다.

    Cloud Monitoring에서 리소스와 라벨은 다른 측정항목 라벨과 분리되어 나열되어 있으나 측정항목에서 추가 시계열을 만드는 효과는 동일합니다. 자세한 내용은 측정항목, 시계열, 리소스를 참조하세요.

  • 로그: 이 라벨은 로그 항목의 logName 필드 중 LOG_ID 부분의 값을 포함합니다.

  • 심각도: 이 라벨은 로그 항목의 severity 필드 값을 포함합니다. 심각도 라벨은 시스템 로그 기반 측정항목에서만 기본적으로 제공됩니다.

예: 측정항목 탐색기 사용

측정항목 탐색기의 다음 스크린샷은 시스템 로그 기반 측정항목 중 하나의 라벨을 보여줍니다. 필터 텍스트 상자를 클릭하면 라벨 목록을 가져올 수 있습니다.

측정항목 탐색기

이 스크린샷은 다음 정보를 보여줍니다.

  • 측정항목 탐색기는 logging/log_entry_count 측정항목과 Compute Engine VM 인스턴스인 gce_instance 리소스 유형의 시계열을 사용합니다.

    이 측정항목에는 다른 리소스 유형의 시계열도 포함되어 있으나 측정항목 탐색기로는 한 번에 하나의 리소스 유형만 볼 수 있습니다.

  • gce_instance 리소스 유형에는 3가지 리소스 라벨(project_id, instance_id, zone)이 있습니다.

  • 측정항목에는 2가지 측정항목 라벨(log, severity)이 있습니다. 이 섹션에는 사용자가 정의한 라벨도 표시됩니다.

라벨 만들기

측정항목을 만들 때 사용자 정의 라벨을 만듭니다. 카운터 측정항목과 분포 측정항목 모두에 라벨을 만들 수 있습니다. 시스템 로그 기반 측정항목에 라벨을 추가할 수 없습니다.

콘솔

  1. 로그 기반 측정항목을 만들 때 로그 측정항목 만들기 패널에는 라벨 추가 옵션이 포함되어 있습니다.

  2. 라벨 추가를 클릭합니다.

    팁: 로그 항목 내부의 필드 및 값을 보려면 다음 단계를 따르세요.

    1. 필터 선택 섹션에서 로그 미리보기를 클릭합니다.
    2. 로그 보기 창에서 로그 항목을 선택하고 그 옆에 있는 펼치기 를 클릭합니다.
    3. 중첩 필드 확장을 클릭합니다.

  3. 라벨 섹션에서 다음 필드를 설정합니다.

    1. 라벨 이름: 라벨의 이름을 입력합니다. 예를 들면 ID입니다.

      이름은 다음 기준을 충족해야 합니다.

      • 길이는 100자(영문 기준) 이하여야 합니다.
      • 정규 표현식([a-zA-Z][a-zA-Z0-9_]*)과 일치해야 합니다.
      • 'log'보다는 긴 문자열로 구성되어야 합니다.

    2. 설명: 라벨을 설명합니다. 예상되는 로그 값의 형식을 가능한 한 구체적으로 설명하세요. 예를 들면 Instance number입니다.

    3. 라벨 유형: 문자열, 불리언 또는 정수를 선택합니다.

    4. 필드 이름: 라벨 값이 포함된 로그 항목 필드의 이름을 입력합니다. 입력하는 동안 선택사항이 제시됩니다. 이 샘플의 경우 필드는 다음과 같습니다.

      labels."compute.googleapis.com/resource_id"

    5. 정규 표현식: 라벨의 값이 필드의 전체 내용으로 구성되었다면 이 필드를 비워 두어도 됩니다. 그렇지 않으면 필드 값에서 라벨 값을 추출하는 regexp 캡처 그룹을 지정합니다.

      예를 들어 필드에는 일반적으로 다음 텍스트가 포함된다고 가정해 보겠습니다.

      The instance number is 0123456789; the ID is my-test-instance22

      라벨 값을 인스턴스 숫자로 지정하려는 경우 정확한 숫자를 추출하는 정규 표현식이 여러 개 있으며, 예를 들어 다음 표현식에서 괄호는 추출할 텍스트 부분을 나타내는 캡처 그룹입니다.

      The instance number is ([0-9]+); .*

      정규 표현식에 관한 자세한 내용은 RE2 구문을 참조하세요.

  4. 완료를 클릭하면 라벨이 만들어집니다. 위의 단계를 반복하여 라벨을 추가할 수 있습니다.

  5. 측정항목 만들기를 완료하기 위해 측정항목 만들기를 클릭합니다.

gcloud

커스텀 라벨이 있는 로그 기반 측정항목을 만들려면 커스텀 라벨을 포함하여 JSON 또는 YAML 형식의 LogMetric 정의 표현을 포함하는 파일을 만들어야 합니다. 그런 다음 --config-from-file 플래그가 지정된 create 명령어를 호출하여 측정항목을 만듭니다. 여기서 FILENAME을 JSON 또는 YAML 파일의 이름으로 바꿉니다.

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

자세한 내용은 gcloud logging metrics create를 참조하세요.

API

라벨은 Logging API의 projects.metrics.create 메서드를 호출할 때 요청 본문에서 LogMetric 객체의 일부로 지정됩니다. 전체 메서드 호출에 대한 자세한 내용은 카운터 측정항목 만들기 또는 분포 측정항목 만들기를 참조하세요.

LogMetric에서 metricDescriptor 및 labelExtractors 필드 모두에 라벨마다 세그먼트를 추가해야 합니다.

구문은 다음과 같습니다.

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

구문 요소의 의미는 다음과 같습니다.

  • LABEL_NAME: 라벨의 이름(문자열)입니다.
  • VALUE_TYPE: 라벨의 유형(STRING, BOOL 또는 INT64)입니다.
  • LABEL_DESCRIPTION: 라벨에 대한 설명입니다.

  • EXTRACTOR_EXPRESSION: 정규 표현식(선택사항)에 로그 항목 필드 이름을 결합하는 문자열입니다. 추출기 표현식은 다음 중 하나일 수 있습니다.

    EXTRACT(FIELD)

    REGEXP_EXTRACT(FIELD, REGEXP)

정규 표현식에 관한 자세한 내용은 RE2 구문을 참조하세요.

다음은 라벨이 2개인 예시입니다.

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

자세한 내용은 LogMetric 유형을 참조하세요.