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

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

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

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

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

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

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

LogEntry 기본 제공 필드(예: httpRequest.status)나 페이로드 필드 textPayload, jsonPayload 또는 protoPayload 중 하나에서 라벨을 추출할 수 있습니다. 하지만 errorGroups 필드에서 오류 그룹의 ID를 추출할 수는 없습니다.

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

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

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

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

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

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

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

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

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

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

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

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

기본 라벨

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

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

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

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

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

측정항목 탐색기를 사용하여 라벨 보기

로그 기반 측정항목에 대해 생성된 시계열의 라벨을 보려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 로그 기반 측정항목 페이지로 이동합니다.

    로그 기반 측정항목으로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 보려는 측정항목을 찾은 후 측정항목의 더보기 메뉴에서 측정항목 탐색기에서 보기를 클릭합니다.

    계속하기 전에 차트에 데이터가 표시될 때까지 기다립니다. 로그 기반 측정항목을 만든 경우 몇 분 정도 걸릴 수 있습니다.

  3. 사용 가능한 라벨을 보려면 필터 필드를 펼칩니다. 리소스 라벨과 측정항목 라벨이 표시될 수 있습니다. 라벨 목록은 리소스 유형과 측정항목 유형에 따라 다릅니다. 예를 들면 다음과 같습니다.

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

    • logging/log_entry_count 측정항목 유형에는 log 및 severity라는 두 개의 측정항목 라벨이 있습니다. 이 섹션에는 사용자가 정의한 라벨도 표시됩니다.

  4. 사용자 정의 라벨이 로그 항목에서 올바른 데이터를 추출하는지 확인하려면 다음 단계를 따르세요.

    1. 집계 요소를 집계되지 않음으로 변경합니다.

    2. 차트에서 테이블 또는 둘 다를 선택합니다.

    3. 툴바에서 열 표시 메뉴를 선택한 다음 라벨을 선택합니다. 이 메뉴에는 데이터가 있는 모든 라벨이 표시됩니다.

      생성한 라벨이 표시되지 않으면 필드 이름과 추출기 표현식을 확인하세요.

라벨 만들기

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

라벨을 만들려면 로그 항목의 필드를 지정한 다음 지정된 필드에서 값을 추출하는 표현식을 정의합니다.

콘솔

  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 유형을 참조하세요.

예시

이 섹션에서는 사용자 정의 로그 기반 측정항목에 라벨을 만드는 데 도움이 될 수 있는 몇 가지 예시를 제공합니다. 라벨을 만든 후 측정항목 탐색기를 사용하여 라벨을 확인하는 것이 좋습니다.

도움말:

  • 추출기 표현식을 지정할 때는 캡처 그룹을 사용해야 합니다.
  • 추출기 표현식을 지정하지 않으면 필드의 전체 값이 추출됩니다.

  • 라벨에 가능한 값 세트를 제한해야 합니다. '빨간색', '녹색', '파란색'과 같은 개별 값의 작은 집합을 사용하는 것이 좋습니다. 예를 들어 색상 라벨의 8비트 RGB 값을 추출하면 1,600만 개 이상의 서로 다른 값을 가질 수 있습니다. 즉, 1,600만 개가 넘는 시계열이 있을 수 있습니다.

    타임스탬프, 모든 종류의 고유 식별자, 사용자 ID, IP 주소, 매개변수화되지 않은 URL 등의 고해상도 값을 추출하지 마세요.

감사 로그에서 상태 코드 추출

필드에 특수문자가 포함되어 있지 않으면 로그 기반 측정항목의 라벨에 필드 이름을 사용할 수 있습니다.

예를 들어 감사 로그의 경우 protoPayload 필드가 AuditLog 구조를 따릅니다. 따라서 감사 로그에서 status 필드를 추출하려면 필드 이름을 protoPayload.status.code로 설정하고 추출기 표현식을 비워두면 됩니다.

오류 코드의 첫 번째 숫자만 추출하려면 추출기 표현식을 (\d)\d\d로 설정하면 됩니다.

특수 문자가 있는 필드에서 값 추출

로그 항목의 필드에 특수문자가 포함되어 있으면 필드를 큰따옴표로 묶습니다.

예를 들어 k8s-pod/k8s-app 라벨의 전체 값을 추출하려면 필드 이름을 labels."k8s-pod/k8s-app"으로 설정하고 표현식을 비워둡니다.

텍스트 페이로드에서 값 추출

다음 형식이 있는 로그 항목을 고려해 보세요.

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

이전 형식의 로그 항목에서 deferred와 같은 상태 값을 추출하려면 다음과 같이 하면 됩니다.

  • 필드 이름: textPayload
  • 추출기 표현식: ^unfinished.*state: ([a-z]+)

반복 필드에서 값 추출

로그 항목에 반복 필드가 있는 필드가 포함될 수 있습니다. JSON에서 이러한 필드는 대괄호([])를 사용하여 표시됩니다. 라벨의 관점에서 반복 필드를 집합으로, 라벨 추출기를 반복자로 간주합니다. 라벨을 정의할 때 일치 기준을 제공하면 추출기가 일치 항목이 발견될 때까지 집합을 반복합니다. 세트의 여러 구성원이 기준을 충족하는 경우에도 항상 첫 번째 일치 항목이 반환됩니다.

감사 로그를 집계하는 로그 기반 측정항목을 만들기로 결정합니다. 라벨을 구성하기 전에 여러 감사 로그를 검토하고 protoPayload 형식이 AuditLog 구조를 준수하는지 확인합니다. 다음은 감사 로그 항목의 일부를 보여줍니다.

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

permission 필드의 정보를 저장하는 로그 기반 측정항목의 라벨을 만들기로 결정합니다. 이러한 필드는 io.k8s.xyz와 같이 형식이 지정되어 있으며, 여기서 xyz는 요청에 관한 자세한 내용을 제공하는 문자열입니다. 이 문자열의 값은 get일 수도 있고 io.k8s.coordination.v1.leases.get과 같은 더 복잡한 형식일 수도 있습니다.

라벨 값의 수를 최소화하려면 세부정보를 추출하지 않는 것이 좋습니다. get 또는 coordination과 같은 값만 라벨에 저장하려고 합니다. 또한 라벨 값에 공통 프리픽스 io.k8s.를 포함하지 않기로 결정합니다.

다음으로 라벨을 구성합니다. permission 필드는 반복 필드이고 상위 필드는 authorizationInfo 필드이므로 필드 이름을 다음과 같이 설정합니다.

protoPayload.authorizationInfo.permission

마지막으로 다음 정규 표현식을 만듭니다.

io.k8s.([a-z]+).*