分布指標を構成する

このページでは、Google Cloud コンソール、Logging API、Google Cloud CLI を使用して分布タイプのログベースの指標を作成する方法について説明します。ログベースの指標の概要については、ログベースの指標の概要をご覧ください。

概要

分布指標では、関連するログエントリを選択するフィルタと、分布の数値を取得するための値エクストラクタの両方が必要です。値エクストラクタは、ユーザー定義ラベルに使用されるものと同じ種類です。

分布指標は、抽出された値の統計的分布をヒストグラムバケットに記録します。抽出された値は個別には記録されませんが、構成されているバケット全体における分布が、数、平均、その値の偏差平方和とともに記録されます。分布内のヒストグラムバケットのデフォルトレイアウトを使用したり、バケットの境界を微調整しておおよその値をキャプチャしたりできます。

分布指標の表示と解釈の詳細については、分布指標をご覧ください。

始める前に

ログベースの指標を使用するには、課金を有効にした Google Cloud プロジェクトが必要です。
Identity and Access Management のロールに、ログベースの指標の作成と表示とアラートポリシーの作成に必要な権限が含まれていることを確認します。詳細については、ログベースの指標の権限をご覧ください。

分布指標を作成する

この指標は、指定したフィルタによって特定されるログエントリをカウントします。フィルタで正規表現を使用できますが、リソースタイプを含めることをおすすめします。フィルタの長さは 20,000 文字以下にする必要があります。

フィルタには機密情報を含めないでください。フィルタはサービスデータとして扱われます。

Console

次の手順に沿って操作し、Google Cloud プロジェクトの Google Cloud コンソールでログベースのカウンタ指標を作成します。

Google Cloud コンソールのナビゲーションパネルで、[Logging] を選択してから、[ログエクスプローラ] を選択します。
[ログベースの指標] に移動
[指標を作成] をクリックします。[ログの指標の作成] パネルが表示されます。
[指標タイプ] で [Distribution] を選択します。
[詳細] セクションで次のフィールドを設定します。
- ログ指標の名前: Google Cloud プロジェクトのログベースの指標で一意の名前を選択します。命名に関する制限事項が適用されます。詳細についてはトラブルシューティングをご覧ください。
- 説明: 指標の説明を入力します。
- 単位: （省略可）分布指標の場合は、s、ms などをオプションとして入力できます。詳細については、MetricDescriptor の unit フィールドをご覧ください。
[フィルタの選択] で指標フィルタを定義します。
1. [ログのスコープを選択する] を使用して、フィルタの対象がすべての Google Cloud プロジェクトのログか、特定のバケットのログのみかを選択します。
2. ロギングクエリ言語を使用して、指標でカウントするログエントリのみを収集するフィルタを作成します。正規表現を使用して指標のフィルタを作成することもできます。
3. フィールド名: 分布の値を含むログエントリフィールドを入力します。入力時に選択肢が表示されます。次に例を示します。
```
 protoPayload.latency
```
4. 正規表現:（省略可）double 型に変換可能な数値が [フィールド名] に常に含まれる場合は、このフィールドは空白にしておくことができます。それ以外の場合は、フィールド値から数値分布値を抽出する正規表現を指定します。
  
  例: たとえば、latency ログエントリのフィールドに数字が含まれ、その後にミリ秒を表す ms が続きます。次の正規表現は、単位のサフィックスなしの数値を選択します。
```
([0-9.]+)
```
  正規表現のキャプチャグループと呼ばれる括弧は、抽出されるテキスト一致の部分を識別します。詳しくは、正規表現の使用をご覧ください。
- その他（ヒストグラムバケット）: （省略可）[その他] をクリックすると、カスタムバケットのレイアウトの指定に使用できるフォームのセクションが開きます。バケットのレイアウトを指定しない場合、デフォルトのバケットレイアウトが適用されます。詳細については、このページのヒストグラムバケットをご覧ください。
1. フィルタに一致するログエントリを確認するには、[ログをプレビュー] をクリックします。
（省略可）[ラベル] にラベルを追加します。ラベルの作成手順については、ラベルの作成をご覧ください。
[指標を作成] をクリックして、メトリックを作成します。

gcloud

分布タイプのログベースの指標を作成するには、JSON または YAML 形式の LogMetric 定義の表現を含むファイルを作成します。次に、次のコマンドを使用して、ファイルから構成を読み取ります。

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

分布のヒストグラムバケットの説明については、ヒストグラムバケットをご覧ください。

API

分布指標を作成するには、Logging API の projects.metrics.create メソッドを使用します。このメソッドは、API Explorer で試用できます。次のように、メソッドの引数を準備します。

parent フィールドを、指標を作成するプロジェクトまたはバケットに設定します。
- プロジェクトスコープのログベースの指標の場合は、プロジェクトを指定します。
```
projects/PROJECT_ID
```
- バケットスコープのログベースの指標の場合は、バケットを指定します。
```
projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
```

リクエスト本文を LogMetric オブジェクトに設定します。以下は分布指標のサンプルオブジェクトです。

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

注:

命名に関する制限事項が適用されます。詳細についてはトラブルシューティングをご覧ください。
metricDescriptor: MetricDescriptor オブジェクトです。metricKind が DELTA でなければなりません。valueType が DISTRIBUTION でなければなりません。

ヒストグラムバケット

分布指標には、指定された範囲（バケット）に含まれる値の数をカウントするヒストグラムが含まれます。分布指標は、最大 200 個のバケットを持つことができます。

各バケットには、それぞれバケットの最小値と最大値を表す L と H の 2 つの境界値があります。バケットの幅は H - L です。複数のバケット間に隙間はないので、1 つのバケットの下限は前のバケットの上限と同じになります。境界は複数のバケットにまたがらないため、バケットに下限がある場合、そのバケットの上限は次のバケットに属します。

すべてのバケットレイアウトは、個別のバケット間の境界値を昇順に並べることで指定できます。最初のバケットは、最初の境界よりも小さい値をカウントするアンダーフローバケットです。最後のバケットは、最後の境界以上の値をカウントするオーバーフローバケットです。他のバケットは、下の境界以上の値および上の境界未満の値をカウントします。n 個の境界値がある場合、n+1 個のバケットがあります。アンダーフローバケットとオーバーフローバケットを除いて、n-1 個の有限バケットがあります。

分布指標のヒストグラムバケット間の境界を指定するには、次の 3 つの異なる方法があります。境界値の数式を指定するか、境界値のリストを作成します。

線形（offset、width、i）: すべてのバケットは同じ幅になります。境界は offset + width * i です（i=0, 1, 2, ..., N）。線形バケットの詳細については、API リファレンスをご覧ください。
指数（scale、growth_factor、i）: 値が大きくなるとバケット幅が大きくなります。境界は scale * growth_factor ⁱ です（i = 0、1、2、...、N）。指数バケットの詳細については、API リファレンスをご覧ください。
明示: バケットのすべての境界を bounds 配列で列挙します。バケット i には次の境界があります。

上限: bounds[i]（0 <= i < N-1）
下限: bounds[i - 1]（1 <= i < N）

明示的なバケットの詳細については、API リファレンスをご覧ください。

ヒストグラムバケットの指定方法については、次のセクションで説明します。

コンソール

分布指標を作成し、[指標エディタ] フォームで [その他] をクリックすると、[Histogram buckets] サブメニューが開きます。次に、線形バケットレイアウトのサブフォームを示します。

ヒストグラムバケット

線形バケット: 次のようにヒストグラムバケットフォームに入力します。

タイプ: 線形。
開始値（a）: 最初の有限バケットの下限。 この値は API ではオフセットと呼ばれます。
バケット数（N）: 有限バケットの数。値は 0 以上である必要があります。
バケット幅（b）: 各有限バケットの上限と下限の差。この値は 0 よりも大きくする必要があります。

たとえば、開始値が 5、バケット数が 4、バケット幅が 15 の場合、バケット範囲は次のようになります。

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

明示的なバケット: 次のようにヒストグラムバケットフォームに入力します。

タイプ: 明示。
境界（b）: 有限バケットの境界値のカンマ区切りリスト。これにより、バケットの数とその幅も設定されます。

たとえば、境界のリストが次の場合:

0, 1, 2, 5, 10, 20

次の範囲の有限バケットが 5 つあります。

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

指数バケット: 次のようにヒストグラムバケットフォームに入力します。

タイプ: 指数。
バケット数（N）: 有限バケットの総数。この値は 0 よりも大きくする必要があります。
線形目盛（a）: バケットの線形目盛。この値は 0 よりも大きくする必要があります。
指数増加係数（b）: バケットの指数増加係数。この値は 1 よりも大きくする必要があります。

たとえば、N=4、a=3、b=2 の場合、バケット範囲は次のようになります。

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

バケットの詳細については、Cloud Monitoring API の BucketOptions をご覧ください。

API

オプションのバケットレイアウトは、projects.metrics.create に指定された LogMetric オブジェクトの bucketOptions フィールドで指定されます。完全な LogMetric オブジェクトについては、このページの分布指標を作成するをご覧ください。バケットレイアウトの追加は次のとおりです。

線形バケット:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

上記のサンプルによって、次のバケットが作成されます。

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

明示的なバケット: 境界が個別にリストされます。

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

上記のサンプルによって、次のバケットが作成されます。

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

指数バケット: 境界は scale * growthFactor ^ i です（i=0, 1, 2, ..., numFiniteBuckets）。

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

上記のサンプルによって、次のバケットが作成されます。

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

新しい指標レイテンシ

新しい指標は、指標のリストと関連する Monitoring メニューにすぐに表示されます。ただし、一致するログエントリのデータ収集が開始するまでに 1 分ほどかかる場合があります。

分布指標を検査する

Google Cloud プロジェクトのユーザー定義のログベース指標をリスト表示したり、Google Cloud プロジェクトの特定の指標を検査したりするには、次のようにします。

コンソール

Google Cloud コンソールのナビゲーションパネルで、[Logging] を選択してから、[ログエクスプローラ] を選択します。
[ログベースの指標] に移動
[ユーザー定義の指標] ペインに、現在の Google Cloud プロジェクト内にあるユーザー定義のログベース指標が表示されます。
ログベースの指標でデータを表示するには、指標の行にある [メニュー] をクリックして、[Metrics Explorer に表示] を選択します。

gcloud

Google Cloud プロジェクトのユーザー定義のログベース指標を一覧表示するには、次のコマンドを使用します。

gcloud logging metrics list

Google Cloud のユーザー定義のログベース指標を表示するには、次のコマンドを使用します。

gcloud logging metrics describe METRIC_NAME

サポートが必要な場合は、次のコマンドを使用します。

gcloud logging metrics --help

Google Cloud CLI から指標の時系列データは読み取れません。

API

指標のリスト

Google Cloud プロジェクトのユーザー定義のログベース指標を一覧表示するには、projects.metrics.list API メソッドを使用します。メソッドのパラメータには、次のように入力します。

親: Google Cloud プロジェクトのリソース名。projects/PROJECT_ID。
pageSize: 結果の最大数。
pageToken: 結果の次のページを取得します。ページトークンの使用方法について詳しくは、projects.metrics.list をご覧ください。

指標の定義を取得する

ユーザー定義のログベース指標を 1 つ取得するには、projects.metrics.get API メソッドを使用します。メソッドのパラメータには、次のように入力します。

metricName: 指標のリソース名。
```
projects/PROJECT_ID/metrics/METRIC_ID
```

指標データを読み取る

ログベースの指標で時系列データを読み取るには、Cloud Monitoring API の projects.timeseries.list を使用します。時系列データの詳細については、時系列の読み取りをご覧ください。

ユーザー定義のログベース指標を 1 つ読み取るには、メソッドのパラメータに次のような指標タイプと ID を入力します。

logging.googleapis.com/user/METRIC_ID

分布指標を更新する

ログベースの指標を更新して、指標で参照されるフィールドの説明、フィルタ、フィールド名を編集できます。新しいラベルを指標に追加し、指標とラベルの値を抽出する正規表現を変更できます。バケットスコープの指標を使用している場合は、指標のバケットを更新することもできます。

ユーザー定義のログベースの指標またはラベルの名前とタイプは変更できません。また、ログベース指標の既存のラベルは削除できません。

ログベースの指標を編集するには、次の手順を行います。

コンソール

Google Cloud コンソールのナビゲーションパネルで、[Logging] を選択してから、[ログエクスプローラ] を選択します。
[ログベースの指標] に移動
変更するログベースの指標のメニューで [指標を編集] をクリックします。
指標の変更可能な項目を変更します。
[指標の更新] をクリックします。

gcloud

Google Cloud CLI を使用して、カウンタ指標の説明、フィルタクエリ、バケットを変更します。任意のまたはすべてのフィールドを一度に更新できます。

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

バケットスコープの指標に関連付けられたバケットを変更すると、変更前に収集された指標データには現在の構成がもう反映されなくなります。前のバケットで収集された指標データは削除されません。

METRIC_NAME を除く分布指標または他のカウンタ指標のフィールドを更新するには、JSON 形式または YAML 形式の LogMetric の改訂仕様を含むファイルを作成します。次に、update コマンドに --config-from-file フィールドを指定して呼び出し、FILENAME を JSON または YAML ファイルの名前に置き換えて指標を更新します。

gcloud logging update METRIC_NAME --config-from-file FILENAME

詳細については、次のコマンドを使用してください。

gcloud logging metrics update --help

API

ログベースの指標を編集するには、API の projects.metrics.update メソッドを使用します。フィールドを次のように設定します。

metricName: 指標の完全リソース名。

projects/PROJECT_ID/metrics/METRIC_ID

例:

projects/my-gcp-project/metrics/my-error-metric

リクエスト本文には、加える変更や追加を除いて既存の指標とまったく同じ LogMetric オブジェクトを含めます。

分布指標を削除する

ユーザー定義のログベース指標を削除するには、次の手順に従います。

コンソール

Google Cloud コンソールのナビゲーションパネルで、[Logging] を選択してから、[ログエクスプローラ] を選択します。
[ログベースの指標] に移動
削除する接続を選択して、[削除] をクリックします。

または、削除するログベースの指標のメニューで [指標を削除] をクリックします。

gcloud

次のコマンドを使用して、現在の Google Cloud プロジェクトのユーザー定義のログベース指標を削除します。

gcloud logging metrics delete METRIC_NAME

For more details, use the following command:

gcloud logging metrics delete --help

API

ユーザー定義のログベースの指標を削除するには、API の projects.metrics.delete メソッドを使用します。

さらに、Google Cloud コンソールの [ログベースの指標] ページにある、ログベースの指標のインターフェースの [ユーザー定義の指標] ペインには、さらに多くの機能があり、Google Cloud プロジェクトのユーザー定義の指標の管理に役立ちます。詳しくは、[ユーザー定義の指標] ペインをご覧ください。

分布指標を構成する

概要

始める前に

分布指標を作成する

Console

gcloud

API

ヒストグラム バケット

コンソール

API

新しい指標レイテンシ

分布指標を検査する

コンソール

gcloud

API

指標のリスト

指標の定義を取得する

指標データを読み取る

分布指標を更新する

コンソール

gcloud

API

分布指標を削除する

コンソール

gcloud

API

ヒストグラムバケット