分布指標を構成する

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

概要

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

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

分布指標の作成

指標でカウントするログエントリをフィルタリングする場合は、正規表現を使用できます。 フィルタの長さは 20,000 文字までです。

Console

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

  1. [ロギング] > [ログベースの指標] ページに移動します。

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

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

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

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

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

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

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

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

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

      ([0-9.]+)
      

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

    • その他(ヒストグラム バケット): (省略可)[その他] をクリックすると、カスタム バケットのレイアウトの指定に使用できるフォームのセクションが開きます。バケットのレイアウトを指定しない場合、デフォルトのバケット レイアウトが適用されます。詳細については、このページのヒストグラム バケットをご覧ください。

    [ログをプレビュー] をクリックして、フィルタと一致するログエントリを表示するパネルを開きます。

  6. (省略可)[ラベル] にラベルを追加します。ラベルの作成手順については、ラベルの作成をご覧ください。

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

gcloud

gcloud コマンドライン ツールを使用して分布指標を作成するには、--config-from-file フラグを使用して完全な指標構成を指定します。構成形式は JSON または YAML です。LogMetric の構成の詳細については、projects.metrics をご覧ください。

API

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

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

    projects/PROJECT_ID
    
  2. リクエスト本文を LogMetric オブジェクトに設定します。次に、分布指標のオブジェクトの例を示します。

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/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-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 プロジェクトのユーザー定義のログベース指標をリスト表示したり、Cloud プロジェクトの特定の指標を検査したりするには、次のようにします。

Console

[ログベースの指標] ページに移動します。

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

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

ログベースの指標でデータを表示するには、指標の行にあるメニューをクリックして、[Metrics Explorer に表示] を選択します。

gcloud

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

gcloud logging metrics list

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

gcloud logging metrics describe METRIC_NAME

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

gcloud logging metrics --help

指標の時系列データを Cloud SDK から読み取ることはできません。

API

指標のリスト

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

  • : Cloud プロジェクトのリソース名。プロジェクト / 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. [ログベースの指標] ページに移動します。

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

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

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

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

gcloud

既存の指標の説明とクエリは、Cloud SDK を使用することによってのみ変更できます。

ログベースの指標を更新するには、次のコマンドを使用します。フラグのいずれかまたは両方を指定できます。

gcloud logging metrics update METRIC_NAME --description=DESCRIPTION --log-filter=FILTER

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

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. [ログベースの指標] ページに移動します。

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

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

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

gcloud

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

gcloud logging metrics delete METRIC_NAME

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

gcloud logging metrics delete --help

API

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

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