分布指標を構成する

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

概要

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

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

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

始める前に

  1. ログベースの指標を使用するには、課金を有効にした Google Cloud プロジェクトが必要です。

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    3. Make sure that billing is enabled for your Google Cloud project.

    4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    5. Make sure that billing is enabled for your Google Cloud project.

  2. Identity and Access Management のロールに、ログベースの指標の作成と表示とアラート ポリシーの作成に必要な権限が含まれていることを確認します。詳細については、ログベースの指標の権限をご覧ください。

分布指標を作成する

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

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

Console

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

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

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

    検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

  2. [指標を作成] をクリックします。[ログの指標の作成] パネルが表示されます。

  3. [指標タイプ] で [Distribution] を選択します。

  4. [詳細] セクションで次のフィールドを設定します。

    • ログ指標の名前: Google Cloud プロジェクトのログベースの指標で一意の名前を選択します。命名に関する制限事項が適用されます。詳細についてはトラブルシューティングをご覧ください。
    • 説明: 指標の説明を入力します。
    • 単位: (省略可)分布指標の場合は、sms などをオプションとして入力できます。詳細については、MetricDescriptorunit フィールドをご覧ください。
  5. [フィルタの選択] で指標フィルタを定義します。

    1. [ログのスコープを選択する] を使用して、フィルタの対象がすべての Google Cloud プロジェクトのログか、特定のバケットのログのみかを選択します。

    2. ロギングクエリ言語を使用して、指標でカウントするログエントリのみを収集するフィルタを作成します。正規表現を使用して指標のフィルタを作成することもできます。

    3. フィールド名: 分布の値を含むログエントリ フィールドを入力します。入力時に選択肢が表示されます。次に例を示します。

       protoPayload.latency
      
    4. 正規表現:(省略可)double 型に変換可能な数値が [フィールド名] に常に含まれる場合は、このフィールドは空白にしておくことができます。それ以外の場合は、フィールド値から数値分布値を抽出する正規表現を指定します。

      : たとえば、latency ログエントリのフィールドに数字が含まれ、その後にミリ秒を表す ms が続きます。次の正規表現は、単位のサフィックスなしの数値を選択します。

      ([0-9.]+)
      

      正規表現のキャプチャ グループと呼ばれる括弧は、抽出されるテキスト一致の部分を識別します。詳しくは、正規表現の使用をご覧ください。

    • その他(ヒストグラム バケット): (省略可)[その他] をクリックすると、カスタム バケットのレイアウトの指定に使用できるフォームのセクションが開きます。バケットのレイアウトを指定しない場合、デフォルトのバケット レイアウトが適用されます。詳細については、このページのヒストグラム バケットをご覧ください。
    1. フィルタに一致するログエントリがどれかを確認するには、[ログをプレビューする] をクリックします。
  6. (省略可)[ラベル] にラベルを追加します。ラベルの作成手順については、ラベルの作成をご覧ください。

  7. [指標を作成] をクリックして、メトリックを作成します。

gcloud

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

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

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

API

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

  1. parent フィールドを、指標を作成するプロジェクトまたはバケットに設定します。

    • プロジェクト スコープのログベースの指標の場合は、プロジェクトを指定します。
    projects/PROJECT_ID
    
    • バケット スコープのログベースの指標の場合は、バケットを指定します。
    projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
    
  2. リクエスト本文を 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 オブジェクトです。metricKindDELTA でなければなりません。valueTypeDISTRIBUTION でなければなりません。

ヒストグラム バケット

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

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

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

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

  • 線形(offset、width、i): すべてのバケットは同じ幅になります。境界は offset + width * i です(i=0, 1, 2, ..., N)。線形バケットの詳細については、API リファレンスをご覧ください。

  • 指数scale、growth_factor、i): 値が大きくなるとバケット幅が大きくなります。境界は scale * growth_factor i です(i = 0、1、2、...、N)。指数バケットの詳細については、API リファレンスをご覧ください。

  • 明示: バケットのすべての境界を bounds 配列で列挙します。バケット i には次の境界があります。

    上限: bounds[i](0 <= i < N-1)
    下限: bounds[i - 1](1 <= i < N

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

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

Console

分布指標を作成し、[指標エディタ] フォームで [その他] をクリックすると、[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 プロジェクトの特定の指標を検査したりするには、次のようにします。

Console

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

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

    検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

  2. [ユーザー定義の指標] ペインに、現在の Google Cloud プロジェクト内にあるユーザー定義のログベース指標が表示されます。

  3. ログベースの指標でデータを表示するには、指標の行にある [メニュー] をクリックして、[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 メソッドを使用します。メソッドのパラメータには、次のように入力します。

  • parent: 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

分布指標を更新する

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

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

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

Console

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

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

    検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

  2. 変更するログベースの指標のメニューで [指標を編集] をクリックします。

  3. 指標の変更可能な項目を変更します。

  4. [指標の更新] をクリックします。

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 オブジェクトを含めます。

分布指標を削除する

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

Console

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

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

    検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。

  2. 削除する接続を選択して、[削除] をクリックします。

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

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 プロジェクトのユーザー定義の指標の管理に役立ちます。詳しくは、[ユーザー定義の指標] ペインをご覧ください。