分布指標の作成

このページでは、GCP Console と Stackdriver Logging API を使用して分布タイプのログベースの指標を作成する方法について説明します。

概要

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

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

分布指標の作成

Logging Console

GCP Console でログベースの指標を作成するには、次の手順に従います。

  1. GCP Console の左側のナビゲーション リストで、[Stackdriver Logging] > [ログベースの指標] をクリックするか、次のボタンをクリックします。

    ログビューアに移動

  2. ページの上部にあるプルダウン メニューを使用してプロジェクトを選択します。

  3. ページの上部にある [指標を作成] をクリックします。ページの右側に [指標エディタ]、左側にログを表示するビューアパネルが表示されます。

    分布指標の作成

  4. ビューアパネルで、指標でカウントするログエントリのみを表示するフィルタを作成します。

    基本フィルタは、ログエントリの上にあるプルダウン メニューから選択できます。検索バーの右側にあるプルダウン メニューをクリックして、[高度なフィルタに変換] を選択すると、高度なフィルタのインターフェースを表示できます。

    詳しくは、ユーザー インターフェースをご覧ください。

  5. [指標エディタ] パネルで、次のフィールドを設定します。

    • 名前: プロジェクトのログベースの指標で一意の名前を選択します。命名に関する制限事項が適用されます。詳細についてはトラブルシューティングをご覧ください。
    • 説明: 指標を説明します。
    • ラベル: (省略可)ラベルごとに [アイテムを追加] をクリックして、ラベルを追加します。ラベルの定義の詳細については、ログベースの指標ラベルをご覧ください。
    • 単位: (省略可)分布指標の場合は sms などの単位を任意で入力できます。詳しくは、MetricDescriptorunit フィールドをご覧ください。
    • タイプ: Distribution
    • フィールド名: 分布の値を含むログエントリ フィールドを入力します。入力時に選択肢が表示されます。次に例を示します。

      jsonPayload.latency
      
    • 抽出の正規表現: (省略可)double 型に変換可能な数値が [フィールド名] に常に含まれる場合は、このフィールドを空のままにできます。それ以外の場合は、フィールド値から数値分布値を抽出する正規表現を指定します。[作成] メニューを使用して、対話形式で正規表現を構築および検証できます。

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

      ([0-9.]+)ms
      

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

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

  6. [指標を作成] をクリックします。

Logging API

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

  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: "REGEX_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 オブジェクト。metricKindDELTAvalueTypeDISTRIBUTION でなければなりません。

ヒストグラム バケット

分布指標には、指定された範囲(バケット)に含まれる値の数をカウントするヒストグラムが含まれます。分布指標は、最大 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 リファレンスをご覧ください。

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

Logging 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]

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

Logging 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]

新しい指標レイテンシ

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

分布指標の検査

GCP プロジェクトのログベース指標を一覧表示する、またはプロジェクトの特定の指標を検査するには、次の手順に従います。

Logging Console

次のボタンをクリックして、[ログベースの指標] ページに移動します。このページには、現在のプロジェクトのすべてのログベースの指標が一覧表示されます。

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

ログベースの指標でデータを表示するには、指標のリストの右側にあるオーバーフロー メニューから [Metric Explorer に表示] を選択します。

Logging API

指標の一覧表示

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

  • parent: プロジェクトのリソース名: projects/[PROJECT_ID]
  • pageSize: 結果の最大数。
  • pageToken: 結果の次のページを取得します。projects.metrics.list をご覧ください。

指標定義の取得

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

  • metricName: 指標のリソース名。

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

指標データの読み取り

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

  • 指標タイプは logging.googleapis.com/user/[METRIC_ID] です。

Cloud SDK

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

gcloud logging metrics list

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

gcloud logging metrics describe [METRIC_NAME]

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

gcloud logging metrics --help

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

分布指標の更新

ログベースの指標を更新して、説明、フィルタ、および指標で参照されるフィールド名を変更できます。新しいラベルを指標に追加し、指標とラベルの値を抽出する正規表現を変更できます。

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

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

Logging Console

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

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

  2. 編集するログベースの指標の右側にあるメニューの [指標を編集] をクリックします。

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

  4. [完了] をクリックします。

Logging API

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

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

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    例:

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

Cloud SDK

Cloud SDK を使用すると、既存の指標の説明とフィルタのみを変更できます。

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

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

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

gcloud logging metrics update --help

分布指標の削除

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

Logging Console

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

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

  2. 削除する指標を選択し、ページの上部にある [削除] をクリックします。

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

Logging API

API の projects.metrics.delete メソッドを使用します。

Cloud SDK

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

gcloud logging metrics delete [METRIC_NAME]

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

gcloud logging metrics delete --help

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。