ログベースの指標にラベルを構成する

このドキュメントでは、ログベースの指標ラベルについて検討し、ログベースの指標にラベルを作成して使用する方法について説明します。

ラベルについてよく理解している場合は、このページのラベルを作成するに直接進むことができます。

ログベースの指標のラベルの概要

ラベルを使用すると、ログベースの指標に、ラベル値の組み合わせごとに 1 つずつ、複数の時系列を含めることができます。すべてのログベースの指標には、デフォルトのラベルがあります。

抽出式を指定すると、カウンタタイプと分布タイプの両方の指標で追加のラベルを作成できます。抽出式によって、Cloud Logging に、ログエントリからラベルの値を抽出する方法が指示されます。ラベルの値は、次のいずれかを指定できます。

  • LogEntry オブジェクトの名前付きフィールドの内容全体。
  • 正規表現（regexp）に一致する名前付きフィールドの一部。

ラベルは、httpRequest.status などの LogEntry の組み込みフィールドから抽出することも、textPayload、jsonPayload、protoPayload のいずれかのペイロード フィールドから抽出することもできます。

正規表現の詳細については、RE2 構文をご覧ください。

機密情報を抽出式に入力したり、センシティブ データをラベル内に抽出したりしないでください。これらはサービスデータとして扱われます。

ユーザー定義ラベルの制限

ユーザー定義ラベルには次の制限があります。

  • 指標 1 つあたり最大 10 個のユーザー定義ラベルを作成できます。

  • 作成したラベルは削除できません。

    • 作成したラベルの抽出式と説明は変更できます。

    • 作成したラベルの名前と値の型は変更できません。

  • ラベル値の最初の 1,024 文字だけが保持されます。

  • ログベースの各指標は、約 30,000 個のアクティブ時系列に制限されています。これは、デフォルト ラベルを含む各ラベルに有効な値の数に依存します。

    たとえば、ログエントリの取得元が VM インスタンスなどの 100 個のリソースで、20 個の有効な値でラベルを定義する場合、指標に対して最大 2,000 個の時系列を格納できます。

時系列が多すぎたり、データポイントが多すぎたりすると、コストが上昇し、アクティビティが抑制される可能性があります。ログベースの指標の費用の詳細については、Cloud Monitoring の料金: 課金対象指標をご覧ください。ログベースの指標に適用される上限については、割り当てと上限: ログベースの指標とログベースの指標のトラブルシューティングをご覧ください。

デフォルト ラベル

すべてのログベースの指標には、定義済みのラベルが付与されています。

  • リソースラベル: すべての指標は、モニタリング対象のリソース オブジェクトを使用して時系列データのソースを識別します。リソースタイプは、タイプ名と 1 つ以上のラベルから構成されます。リソースのタイプとしては、たとえば VM インスタンス、Cloud SQL データベース、ロードバランサなどがあります。

    リソースとそのラベルは、Cloud Monitoring の他の指標ラベルとは別に表示されますが、効果は同じです。指標に追加の時系列が作成されます。詳細については、指標、時系列、リソースをご覧ください。

  • ログ: このラベルは、ログエントリの logName フィールドの LOG_ID 部分に含まれる値を保持します。

  • 重大度: このラベルは、ログエントリの severity フィールドの値を保持します。 重大度ラベルは、システム ログベースの指標でのみデフォルトで提供されます。

例: Metrics Explorer を使用する

Metrics Explorer の次のスクリーンショットは、システム ログベースの指標の 1 つのラベルを示しています。[Filter] テキスト ボックス内をクリックすると、ラベルリストが表示されます。

Metrics Explorer

スクリーンショットには、次の情報が表示されます。

  • Metrics Explorer は、logging/log_entry_count 指標と gce_instance リソースタイプ（Compute Engine VM インスタンス）の時系列を使用しています。

    この指標には他のリソースタイプの時系列も含まれますが、Metrics Explorer では一度に 1 つのリソースタイプのみを表示できます。

  • gce_instance リソースタイプには、3 つのリソースラベル（project_id、instance_id、zone）があります。

  • この指標には 2 つの指標ラベル（log と severity）があります。このセクションには、ユーザー定義のラベルも表示されます。

ラベルを作成する

指標を作成するときに、ユーザー定義のラベルを作成します。カウンタ指標と分散指標の両方にラベルを付けることができます。システム ログベースの指標にラベルを追加することはできません。

Console

  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. 正規表現: ラベルの値によってフィールドのコンテンツ全体が構成されている場合は、このフィールドを空のままにしておくことができます。それ以外の場合は、フィールド値からラベル値を抽出する正規表現のキャプチャ グループを指定します。

      たとえば、フィールドには通常、次のようなテキストが含まれているとします。

      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 タイプをご覧ください。