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

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

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

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

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

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

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

ラベルは、httpRequest.status などの LogEntry の組み込みフィールドから抽出することも、textPayload、jsonPayload、protoPayload のいずれかのペイロード フィールドから抽出することもできます。ただし、errorGroups フィールドからエラー グループの ID を抽出することはできません。

正規表現の詳細については、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 を使用してラベルを表示する

ログベースの指標用に生成された時系列のラベルを表示するには、次の操作を行います。

1. Google Cloud コンソールで、[ログベースの指標] ページに移動します。

   [ログベースの指標] に移動

   このページを検索バーで検索する場合は、小見出しが「Logging」の結果を選択します。

2. 表示する指標を見つけて、指標のmore_vert [その他] メニューから [Metric Explorer で表示する] を選択します。

   続行する前に、グラフにデータが表示されるまで待ちます。ログベースの指標を作成した場合は、数分かかることがあります。

3. 使用可能なラベルを表示するには、[フィルタ] フィールドを開きます。リソースラベルと指標ラベルが表示されます。ラベルのリストは、リソースタイプと指標タイプに固有です。例:

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

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

4. ユーザー定義ラベルがログエントリから正しいデータを抽出していることを確認するには、次の操作を行います。

   1. [集計] 要素を [未集計] に変更します。

   2. グラフで、[テーブル] または [両方] を選択します。

   3. ツールバーで view_column 列表示メニューを選択し、ラベルを選択します。このメニューには、データがあるすべてのラベルが表示されます。

      作成したラベルが表示されない場合は、フィールド名と抽出式を確認します。

ラベルを作成する

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

ラベルを作成するには、ログエントリのフィールドを指定し、指定したフィールドから値を抽出する式を定義します。

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

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

{
  ...
  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)",
  },
}

例

このセクションでは、ユーザー定義のログベースの指標にラベルを作成する際に役立つ例をいくつか示します。ラベルを作成したら、Metrics Explorer を使用してラベルを確認することをおすすめします。

ヒント:

• 抽出式を指定する場合は、キャプチャ グループを使用する必要があります。
• 抽出式を指定しない場合、フィールドの値全体が抽出されます。

• ラベルに使用できる一連の値に制約があることを確認してください。少数の個別の値（「red」、「green」、「blue」など）が推奨される方法です。たとえば、色ラベルの 8 ビット RGB 値を抽出すると、1,600 万を超える異なる値を使用できます。つまり、1,600 万を超える時系列を作成できます。

  タイムスタンプ、一意の ID、ユーザー 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]+).*