カスタム指標の作成

カスタム指標はユーザーが定義する指標です。カスタムの指標では、組み込みの Cloud Monitoring 指標と同じ要素を使用します。

  • データポイントのセット。
  • データポイントが何を表しているかを示す指標タイプ情報。
  • モニタリング対象リソース情報。データポイントの発生場所がわかります。

組み込み指標とカスタム指標の両方の基礎となる構造の概要については、指標、時系列、リソースをご覧ください。組み込み指標を参照するには、指標リストをご覧ください。 使用できるモニタリング対象リソースを参照するには、リソースリストをご覧ください。

カスタム指標を使用するには、新しい指標タイプの指標記述子が必要です。指標記述子は、Cloud Monitoring で自動的に作成することも、metricDescriptors.create API メソッドを使用して自分で作成することもできます。

Cloud Monitoring に指標記述子の作成を任せるのに必要なことは、記述子の時系列データを書くだけです。そのデータに基づいて Cloud Monitoring が記述子を作成します。自動作成には制限があるため、どの情報が指標定義に含まれるか知っておくと便利です。新しいカスタム指標記述子を作成すると、自分で作成したか Monitoring が作成したかにかかわらず、[指標記述子 API メソッド] [指標記述子] と [時系列 API メソッド] [時系列メソッド] でその指標記述子を使用できます。

カスタム指標データのグラフやアラートも作成できます。

カスタム指標名

カスタム指標を作成するときは、指標タイプを表す文字列識別子を作成します。この文字列は、Google Cloud プロジェクトのカスタム指標間で一意にする必要があります。文字列は、ユーザー定義の指標を示す接頭辞で始まる必要があります。Monitoring の場合、最も一般的な接頭辞は custom.googleapis.com/ ですが、external.googleapis.com/ も使用されます。この後には、単純な名前か、通常は収集内容を示すパスのような名前が続きます。パスのような名前を使うとカスタム指標を整理しやすくなりますが、単純名と同様に取り扱われます。詳細については、命名規則をご覧ください。次に、指標タイプの 2 種類の識別子の例を示します。

custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization
    

カスタム指標には、すべてのプロジェクトのすべての Google Cloud リソース内で一意のリソース名もあります。指標のリソース名の形式は以下のとおりです。

projects/[PROJECT_ID]/metricDescriptors/[METRIC_TYPE]
    

上の例のカスタム指標を my-project-id というプロジェクト内に作成した場合は、リソース名は次のようになります。

projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization
    

名前かタイプか:Monitoring API では通常、指標タイプ名のフィールドには type のラベルが付けられ、リソース名のフィールドには name のラベルが付けられています。しかし、会話や文書内で言及されるときは、タイプ名が「指標名」と呼ばれることもよくあります。

カスタム指標記述子の定義

カスタム指標データを収集するには、指標に関するさまざまな情報を指定する MetricDescriptor オブジェクトを提供する必要があります。Cloud Monitoring は自動的に記述子を作成できます。詳細については指標記述子の自動作成をご覧ください。

指標記述子を明示的に作成するには、以下の情報が必要です。

  • 前のセクションの説明に従って、カスタム指標タイプの識別子を選択します。

  • カスタム指標を定義してその時系列データを書き込む、対象のプロジェクトを選択します。

    選択するプロジェクトは、その指標をモニタリングするワークスペースにも属している必要があります。複数のプロジェクトで同じ指標が必要な場合は、各プロジェクト内に同一の指標の定義を作成します。

    AWS 用のカスタム指標は、ご使用の AWS アカウントの AWS コネクタ プロジェクト内に作成する必要があります。

  • 指標の表示名と説明を選択します。表示名は、Google Cloud Console で使用されます。

  • 指標の種類、値の型、単位(任意)を選択します。 値の型と指標の種類の中には、カスタム指標ではサポートされないものもあります。 値の型と指標の種類をご覧ください。

  • 指標のラベル(名前、値の型、説明)を選択します。

組み込み指標の一覧を参照して各指標の時系列データを調べると、上記の選択を行う際に役立ちます。

指標記述子を手動で作成する場合、指標記述子を手動で作成するためのコードサンプルが含まれます。

モニタリング対象リソースタイプの選択

データを時系列に書き込むときには、データの取得元を示す必要があります。それには、データの取得元を示すモニタリング対象のリソースタイプを選択し、それを使用して特定の取得元を記述します。モニタリング対象リソースは、指標タイプの一部ではありません。代わりに、データを書き込む時系列には、データを記述する指標タイプへの参照と、データの取得元を示すモニタリング対象リソースへの参照が含まれます。

指標記述子を作成する前に、モニタリング対象リソースを検討してください。指標記述子に含める必要があるラベルは、使用するモニタリング対象リソースのタイプによって影響されます。たとえば、VM インスタンスのモニタリング対象リソースをデータと一緒に使用する場合は、インスタンスを指定するための指標ラベルが不要です。詳細については、モニタリング対象リソースタイプの選択をご覧ください。

指標の各データポイントは、モニタリング対象リソース オブジェクトと関連付ける必要があります。異なるモニタリング対象リソース オブジェクトからのポイントは、異なる時系列で保持されます。

カスタム指標のモニタリング対象リソース

カスタム指標では、次のモニタリング対象リソースタイプのみを使用できます。

  • aws_ec2_instance: Amazon EC2 インスタンス。
  • dataflow_job: Dataflow ジョブ。
  • gce_instance: Compute Engine のインスタンス
  • gke_container: GKE コンテナ インスタンス
  • generic_node: ユーザー指定のコンピューティング ノード。
  • generic_task: ユーザー定義のタスク。
  • global: 他に適切なリソースタイプがない場合はこのリソースを使用します。ほとんどのケースでは、generic_node または generic_task の方が global よりも適切です。
  • k8s_cluster: Kubernetes クラスタ。
  • k8s_container: Kubernetes コンテナ。
  • k8s_node: Kubernetes ノード。
  • k8s_pod: Kubernetes ポッド。

通常は、アプリケーション コードが実行されている物理リソースを表すモニタリング対象リソース オブジェクトを使用します。このアプローチにはいくつかの利点があります。

  • 単一のリソースタイプを使用する場合に比べてパフォーマンスが向上します。
  • 複数のプロセスが同じ時系列に書き込むことに起因する順不同データを回避します。
  • カスタム指標データと、同じリソースからの他の指標データとをグループ化できます。

global リソースと generic リソースの比較

generic_taskgeneric_node のリソースタイプは、より個別な内容を扱う他のリソースタイプが適当でない場合に役立ちます。generic_task はタスクのようなリソース(たとえばアプリケーションなど)を定義する際、generic_node はノードのようなリソース(たとえば仮想マシンなど)を定義する際に便利です。どちらの generic_* タイプにも共通のラベルが用意されており、独自のリソース オブジェクトを定義できます。共通ラベルを指標フィルタに使うことで、集約や単純化が簡単に行えます。

一方、global リソースタイプには project_id ラベルと location ラベルしかありません。プロジェクト内に指標のソースが複数ある場合、同じ global リソース オブジェクトを使うと、指標データの競合や上書きが発生する可能性があります。

指標記述子の作成

カスタム指標について収集したデータは、カスタム指標タイプの記述子と関連付ける必要があります。指標記述子は、自分で作成することも、Monitoring で作成することもできます。

既存の記述子を変更する方法は限られています。詳細については、指標記述子の変更をご覧ください。

指標記述子の自動作成

存在しないカスタム指標タイプに指標データを書き込むと、新しいカスタム指標タイプが自動的に作成されます。ただし、この新しい指標記述子は、必要なものとは正確に一致しない可能性があります。指標記述子の自動作成には、いくつかの仮定とデフォルトが伴います。

具体的には、timeSeries.create の呼び出しで、TimeSeries オブジェクトに含まれる Metric オブジェクトが、存在していない指標タイプ名を指定していると、次のフィールドを持つ新しい MetricDescriptor が Cloud Monitoring によって作成されます。

  • type: タイプは、Metric オブジェクトの type フィールドからコピーされます。
  • name: 名前は、メソッド呼び出しで指定されたプロジェクト ID と Metric オブジェクトの type の値から作成されます。
  • labels: ラベルは Metric オブジェクトから取得されます。新しい指標記述子の各ラベル記述子には次のフィールドがあります。
    • key: Metric オブジェクト内のラベルキー
    • valueType: STRING
    • description: 未設定
  • metricKind: デフォルトの指標の種類は GAUGE ですが、TimeSeries オブジェクトの metricKind パラメータを指定した場合、新しい指標はその種類になります。種類として指定できるのは GAUGECUMULATIVE だけです。
  • valueType: 値の型は、書き込まれる Point の型指定された値から取得されます。これは BOOLINT64DOUBLEDISTRIBUTIONのいずれかです。TimeSeriesvalueType フィールドで値の型を指定する場合は、その型が Point の型と一致している必要があります。
  • unit: 未設定
  • description: "Auto created custom metric."
  • displayName: 未設定

timeSeries.create の 1 回の呼び出しに、存在しない同じカスタム指標タイプを参照する TimeSeries オブジェクトを複数含めることができます。その場合、新しいタイプのフィールドは上記と同じように設定されますが、新しい指標記述子のラベルだけは、この create の呼び出しで指定されたすべての時系列内の Metric オブジェクトに含まれるすべてのラベルのユニオンになります。

次のステップ: 指標データの書き込みをご覧ください。

手動での指標記述子の作成

カスタム指標タイプを作成するために必要な情報を収集したら、metricDescriptors.create メソッドを呼び出して MetricDescriptor オブジェクトを渡します。詳細については、指標記述子の変更をご覧ください。

metricDescriptors.create を呼び出す際に既存のカスタム指標記述子と同じタイプ名を使用すると、通常はエラーになります。ただし、新しい MetricDescriptor オブジェクトのすべてのフィールドが既存の記述子のフィールドと完全に一致していればエラーにはなりません。しかし、このような呼び出しでは何も起きません。

次の例では、ゲージカスタム指標である custom.googleapis.com/stores/daily_sales を作成します。この指標には単一のディメンション ラベル store_id が付いています。

プロトコル

指標記述子を作成するには、metricDescriptors.create メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。

metricDescriptors.create のサンプル パラメータを次に示します。

  • 名前 (URL): projects/[PROJECT_ID]
  • リクエスト本文: 次のような MetricDescriptor オブジェクトを渡します。

    {
          "name": "",
          "description": "Daily sales records from all branch stores.",
          "displayName": "Sales",
          "type": "custom.googleapis.com/stores/sales",
          "metricKind": "CUMULATIVE",
          "valueType": "DOUBLE",
          "unit": "{USD}",
          "labels": [
            {
              "key": "store_id",
              "valueType": "STRING",
              "description": "The ID of the store."
            },
          ],
        }
        

[PROJECT_ID] の部分を実際のプロジェクト ID に置き換えて、これらの値をウィジェットのフィールドに入力します。

リクエスト本文を入力したこの API ダイアログを試し、指標記述子を作成します。

[Execute] ボタンをクリックしてメソッドを実行します。

試してみる

新しいカスタム指標を作成する際、MetricDescriptorname フィールドは無視され、省略できます。create メソッドから返される新しい指標記述子では、name フィールドに名前が設定されています。この例では、名前は次のようになります。

"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
    

たとえば、指標の記述子を取得する場合などに、この名前を使用します。

C#

        public static object CreateMetric(string projectId,
                string metricType = "custom.googleapis.com/stores/daily_sales")
            {
                // Create client.
                MetricServiceClient metricServiceClient = MetricServiceClient.Create();

                // Prepare custom metric descriptor.
                MetricDescriptor metricDescriptor = new MetricDescriptor();
                metricDescriptor.DisplayName = "Daily Sales";
                metricDescriptor.Description = "Daily sales records from all branch stores.";
                metricDescriptor.MetricKind = MetricKind.Gauge;
                metricDescriptor.ValueType = MetricDescriptor.Types.ValueType.Double;
                metricDescriptor.Type = metricType;
                metricDescriptor.Unit = "{USD}";
                LabelDescriptor labels = new LabelDescriptor();
                labels.Key = "store_id";
                labels.ValueType = LabelDescriptor.Types.ValueType.String;
                labels.Description = "The ID of the store.";
                metricDescriptor.Labels.Add(labels);
                CreateMetricDescriptorRequest request = new CreateMetricDescriptorRequest
                {
                    ProjectName = new ProjectName(projectId),
                };
                request.MetricDescriptor = metricDescriptor;
                // Make the request.
                MetricDescriptor response = metricServiceClient.CreateMetricDescriptor(request);
                Console.WriteLine("Done creating metric descriptor:");
                Console.WriteLine(JObject.Parse($"{response}").ToString());
                return 0;
            }

Go


    import (
    	"context"
    	"fmt"
    	"io"

    	monitoring "cloud.google.com/go/monitoring/apiv3"
    	"google.golang.org/genproto/googleapis/api/label"
    	"google.golang.org/genproto/googleapis/api/metric"
    	metricpb "google.golang.org/genproto/googleapis/api/metric"
    	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
    )

    // createCustomMetric creates a custom metric specified by the metric type.
    func createCustomMetric(w io.Writer, projectID, metricType string) (*metricpb.MetricDescriptor, error) {
    	ctx := context.Background()
    	c, err := monitoring.NewMetricClient(ctx)
    	if err != nil {
    		return nil, err
    	}
    	md := &metric.MetricDescriptor{
    		Name: "Custom Metric",
    		Type: metricType,
    		Labels: []*label.LabelDescriptor{{    			Key:         "environment",
    			ValueType:   label.LabelDescriptor_STRING,
    			Description: "An arbitrary measurement",
    		}},
    		MetricKind:  metric.MetricDescriptor_GAUGE,
    		ValueType:   metric.MetricDescriptor_INT64,
    		Unit:        "s",
    		Description: "An arbitrary measurement",
    		DisplayName: "Custom Metric",
    	}
    	req := &monitoringpb.CreateMetricDescriptorRequest{
    		Name:             "projects/" + projectID,
    		MetricDescriptor: md,
    	}
    	m, err := c.CreateMetricDescriptor(ctx, req)
    	if err != nil {
    		return nil, fmt.Errorf("could not create custom metric: %v", err)
    	}

    	fmt.Fprintf(w, "Created %s\n", m.GetName())
    	return m, nil
    }
    

Java

// Your Google Cloud Platform project ID
    String projectId = System.getProperty("projectId");
    String metricType = CUSTOM_METRIC_DOMAIN + "/" + type;

    final MetricServiceClient client = MetricServiceClient.create();
    ProjectName name = ProjectName.of(projectId);

    MetricDescriptor descriptor = MetricDescriptor.newBuilder()
        .setType(metricType)
        .addLabels(LabelDescriptor
            .newBuilder()
            .setKey("store_id")
            .setValueType(LabelDescriptor.ValueType.STRING))
        .setDescription("This is a simple example of a custom metric.")
        .setMetricKind(MetricDescriptor.MetricKind.GAUGE)
        .setValueType(MetricDescriptor.ValueType.DOUBLE)
        .build();

    CreateMetricDescriptorRequest request = CreateMetricDescriptorRequest.newBuilder()
        .setName(name.toString())
        .setMetricDescriptor(descriptor)
        .build();

    client.createMetricDescriptor(request);

Node.js

// Imports the Google Cloud client library
    const monitoring = require('@google-cloud/monitoring');

    // Creates a client
    const client = new monitoring.MetricServiceClient();

    /**
     * TODO(developer): Uncomment and edit the following lines of code.
     */
    // const projectId = 'YOUR_PROJECT_ID';

    const request = {
      name: client.projectPath(projectId),
      metricDescriptor: {
        description: 'Daily sales records from all branch stores.',
        displayName: 'Daily Sales',
        type: 'custom.googleapis.com/stores/daily_sales',
        metricKind: 'GAUGE',
        valueType: 'DOUBLE',
        unit: '{USD}',
        labels: [
          {
            key: 'store_id',
            valueType: 'STRING',
            description: 'The ID of the store.',
          },
        ],
      },
    };

    // Creates a custom metric descriptor
    const [descriptor] = await client.createMetricDescriptor(request);
    console.log('Created custom Metric:\n');
    console.log(`Name: ${descriptor.displayName}`);
    console.log(`Description: ${descriptor.description}`);
    console.log(`Type: ${descriptor.type}`);
    console.log(`Kind: ${descriptor.metricKind}`);
    console.log(`Value Type: ${descriptor.valueType}`);
    console.log(`Unit: ${descriptor.unit}`);
    console.log('Labels:');
    descriptor.labels.forEach(label => {
      console.log(`  ${label.key} (${label.valueType}) - ${label.description}`);
    });

PHP

use Google\Cloud\Monitoring\V3\MetricServiceClient;
    use Google\Api\LabelDescriptor;
    use Google\Api\LabelDescriptor_ValueType;
    use Google\Api\MetricDescriptor;
    use Google\Api\MetricDescriptor_MetricKind;
    use Google\Api\MetricDescriptor_ValueType;

    /**
     * Create a new metric in Stackdriver Monitoring.
     * Example:
     * ```
     * create_metric($projectId);
     * ```
     *
     * @param string $projectId Your project ID
     */
    function create_metric($projectId)
    {
        $metrics = new MetricServiceClient([
            'projectId' => $projectId,
        ]);

        $projectName = $metrics->projectName($projectId);

        $descriptor = new MetricDescriptor();
        $descriptor->setDescription('Daily sales records from all branch stores.');
        $descriptor->setDisplayName('Daily Sales');
        $descriptor->setType('custom.googleapis.com/stores/daily_sales');
        $descriptor->setMetricKind(MetricDescriptor_MetricKind::GAUGE);
        $descriptor->setValueType(MetricDescriptor_ValueType::DOUBLE);
        $descriptor->setUnit('{USD}');
        $label = new LabelDescriptor();
        $label->setKey('store_id');
        $label->setValueType(LabelDescriptor_ValueType::STRING);
        $label->setDescription('The ID of the store.');
        $labels = [$label];
        $descriptor->setLabels($labels);

        $descriptor = $metrics->createMetricDescriptor($projectName, $descriptor);
        printf('Created a metric: ' . $descriptor->getName() . PHP_EOL);
    }

Python

client = monitoring_v3.MetricServiceClient()
    project_name = client.project_path(project_id)
    descriptor = monitoring_v3.types.MetricDescriptor()
    descriptor.type = 'custom.googleapis.com/my_metric' + str(uuid.uuid4())
    descriptor.metric_kind = (
        monitoring_v3.enums.MetricDescriptor.MetricKind.GAUGE)
    descriptor.value_type = (
        monitoring_v3.enums.MetricDescriptor.ValueType.DOUBLE)
    descriptor.description = 'This is a simple example of a custom metric.'
    descriptor = client.create_metric_descriptor(project_name, descriptor)
    print('Created {}.'.format(descriptor.name))

Ruby

client = Google::Cloud::Monitoring::Metric.new
    project_name = Google::Cloud::Monitoring::V3::MetricServiceClient.project_path project_id

    descriptor = Google::Api::MetricDescriptor.new(
      type:        "custom.googleapis.com/my_metric#{random_suffix}",
      metric_kind: Google::Api::MetricDescriptor::MetricKind::GAUGE,
      value_type:  Google::Api::MetricDescriptor::ValueType::DOUBLE,
      description: "This is a simple example of a custom metric."
    )

    result = client.create_metric_descriptor project_name, descriptor
    p "Created #{result.name}"
    p result

問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。

次のステップ: 指標データの書き込みをご覧ください。

指標の削除

カスタム指標を削除するには、その指標記述子を削除します。 カスタム指標から時系列データを削除することはできませんが、指標記述子を削除するとデータにアクセスできなくなります。データは期限切れになり、データ保持ポリシーに従って削除されます。

カスタム指標記述子を削除するには、metricDescriptors.delete メソッドを呼び出します。

プロトコル

指標記述子を削除するには、metricDescriptors.delete メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。

削除できるのはカスタム指標タイプのみです。

手動での指標記述子の作成で作成したカスタム指標 stores/daily_sales を削除するには、次を実行します。

  1. [reference page for timeSeries.delete] の [timeSeries.delete] に移動します。
  2. 指標記述子の名前を API Explorer ウィジェットに入力します。

    名前: projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales

  3. [Execute] ボタンをクリックします。

試してみる

C#

public static object DeleteMetric(string projectId, string metricType)
    {
        // Create client.
        MetricServiceClient metricServiceClient = MetricServiceClient.Create();
        // Initialize request argument(s).
        MetricDescriptorName name = new MetricDescriptorName(projectId, metricType);
        // Make the request.
        metricServiceClient.DeleteMetricDescriptor(name);
        Console.WriteLine($"Done deleting metric descriptor: {name}");
        return 0;
    }

Go


    import (
    	"context"
    	"fmt"
    	"io"

    	monitoring "cloud.google.com/go/monitoring/apiv3"
    	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
    )

    // deleteMetric deletes the given metric. name should be of the form
    // "projects/PROJECT_ID/metricDescriptors/METRIC_TYPE".
    func deleteMetric(w io.Writer, name string) error {
    	ctx := context.Background()
    	c, err := monitoring.NewMetricClient(ctx)
    	if err != nil {
    		return err
    	}
    	req := &monitoringpb.DeleteMetricDescriptorRequest{
    		Name: name,
    	}

    	if err := c.DeleteMetricDescriptor(ctx, req); err != nil {
    		return fmt.Errorf("could not delete metric: %v", err)
    	}
    	fmt.Fprintf(w, "Deleted metric: %q\n", name)
    	return nil
    }
    

Java

String projectId = System.getProperty("projectId");
    final MetricServiceClient client = MetricServiceClient.create();
    MetricDescriptorName metricName = MetricDescriptorName.of(projectId, name);
    client.deleteMetricDescriptor(metricName);
    System.out.println("Deleted descriptor " + name);

Node.js

// Imports the Google Cloud client library
    const monitoring = require('@google-cloud/monitoring');

    // Creates a client
    const client = new monitoring.MetricServiceClient();

    /**
     * TODO(developer): Uncomment and edit the following lines of code.
     */
    // const projectId = 'YOUR_PROJECT_ID';
    // const metricId = 'custom.googleapis.com/stores/daily_sales';

    const request = {
      name: client.projectMetricDescriptorPath(projectId, metricId),
    };

    // Deletes a metric descriptor
    const [result] = await client.deleteMetricDescriptor(request);
    console.log(`Deleted ${metricId}`, result);
    

PHP

use Google\Cloud\Monitoring\V3\MetricServiceClient;

    /**
     * Example:
     * ```
     * delete_metric($projectId, $databaseId);
     * ```
     *
     * @param string $projectId Your project ID
     * @param string $metricId  The ID of the Metric Descriptor to delete
     */
    function delete_metric($projectId, $metricId)
    {
        $metrics = new MetricServiceClient([
            'projectId' => $projectId,
        ]);

        $metricPath = $metrics->metricDescriptorName($projectId, $metricId);
        $ret = $metrics->deleteMetricDescriptor($metricPath);

        printf('Deleted a metric: ' . $metricPath . PHP_EOL);
    }

Python

client = monitoring_v3.MetricServiceClient()
    client.delete_metric_descriptor(descriptor_name)
    print('Deleted metric descriptor {}.'.format(descriptor_name))

Ruby

client = Google::Cloud::Monitoring::Metric.new
    client.delete_metric_descriptor descriptor_name
    p "Deleted metric descriptor #{descriptor_name}."

問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。

指標データの書き込み

データを書き込むことができるのは、カスタム指標タイプに対してのみです。データを書き込むには、timeSeries.createメソッドを使用します。時系列がすでに存在する場合、このメソッドは既存の時系列に新しいデータポイントを追加します。時系列が存在しない場合、このメソッドは時系列を作成してデータを追加します。

データポイントを書き込むには、TimeSeries オブジェクトのリストを timeSeries.create に渡します。リストの最大サイズは 200 で、リスト内の各オブジェクトに異なる時系列を指定する必要があります。

  • 各時系列は、TimeSeries オブジェクトの metric フィールドと resource フィールドによって識別されます。これらのフィールドは、データの収集されたデータと監視対象リソースの指標タイプを表します。
  • metricKind フィールドと valueType フィールドは省略します。データポイントを書き込むときには無視されます。
  • TimeSeries オブジェクトには Point オブジェクトを 1 つだけ含める必要があります。

    • ポイントの値と時間間隔は指標タイプの定義と一致していなければなりません。さまざまな指標の種類の時間間隔については、値の型と指標の種類をご覧ください。
    • ポイントの時間間隔は、時系列にすでに存在するすべてのポイントより後である必要があります。
    • 期間の終了時刻は、過去 24 時間以上または未来 5 分以上でなければなりません。
  • 同じ時系列に複数のポイントを書き込む場合は、 timeSeries.createメソッドを呼び出します。呼び出しの速度は毎分 1 回よりも速くならないようにしてください。異なる時系列にデータポイントを追加する場合は、追加する速度の制限はありません。

プロトコル

指標データを書き込むには、timeSeries.create メソッドを使用します。このメソッドは、メソッドのリファレンス ページにある API Explorer ウィジェットを使用して実行できます。詳細については、API Explorer をご覧ください。

手動での指標記述子の作成で作成したカスタム指標 stores/daily_sales にポイントを書き込むには:

  1. [reference page for timeSeries.create] の [timeSeries.create] に移動します。
  2. 下記のパラメータを API Explorer ウィジェットに入力します。
  3. [Execute] ボタンをクリックします。

次のサンプル パラメータを使用します。

  • 名前: projects/[PROJECT_ID]
  • リクエスト本文: TimeSeries オブジェクトのリストを含めます。次のサンプルでは、リストに時系列が 1 つだけ含まれています。

    {
         "timeSeries": [
          {
           "metric": {
            "type": "custom.googleapis.com/my_metric",
            "labels": {
             "my_label": "my_value"
            }
           },
           "resource": {
            "type": "gce_instance",
            "labels": {
             "project_id": "[PROJECT_ID]",
             "instance_id": "1234567890123456789",
             "zone": "us-central1-f"
            }
           },
           "points": [
            {
             "interval": {
              "endTime": "2018-06-01T10:00:00-04:00"
             },
             "value": {
              "doubleValue": 123.45
             }
            }
           ]
          }
         ]
        }
        

試してみる

C#

        public static object WriteTimeSeriesData(string projectId)
            {
                // Create client.
                MetricServiceClient metricServiceClient = MetricServiceClient.Create();
                // Initialize request argument(s).
                ProjectName name = new ProjectName(projectId);
                // Prepare a data point.
                Point dataPoint = new Point();
                TypedValue salesTotal = new TypedValue();
                salesTotal.DoubleValue = 123.45;
                dataPoint.Value = salesTotal;
                Timestamp timeStamp = new Timestamp();
                timeStamp.Seconds = (long)(DateTime.UtcNow - s_unixEpoch).TotalSeconds;
                TimeInterval interval = new TimeInterval();
                interval.EndTime = timeStamp;
                dataPoint.Interval = interval;

                // Prepare custom metric.
                Metric metric = new Metric();
                metric.Type = "custom.googleapis.com/stores/daily_sales";
                metric.Labels.Add("store_id", "Pittsburgh");

                // Prepare monitored resource.
                MonitoredResource resource = new MonitoredResource();
                resource.Type = "global";
                resource.Labels.Add("project_id", projectId);

                // Create a new time series using inputs.
                TimeSeries timeSeriesData = new TimeSeries();
                timeSeriesData.Metric = metric;
                timeSeriesData.Resource = resource;
                timeSeriesData.Points.Add(dataPoint);

                // Add newly created time series to list of time series to be written.
                IEnumerable<TimeSeries> timeSeries = new List<TimeSeries> { timeSeriesData };
                // Write time series data.
                metricServiceClient.CreateTimeSeries(name, timeSeries);
                Console.WriteLine("Done writing time series data:");
                Console.WriteLine(JObject.Parse($"{timeSeriesData}").ToString());
                return 0;
            }

Go


    // writeTimeSeriesValue writes a value for the custom metric created
    func writeTimeSeriesValue(projectID, metricType string) error {
    	ctx := context.Background()
    	c, err := monitoring.NewMetricClient(ctx)
    	if err != nil {
    		return err
    	}
    	now := &timestamp.Timestamp{
    		Seconds: time.Now().Unix(),
    	}
    	req := &monitoringpb.CreateTimeSeriesRequest{
    		Name: "projects/" + projectID,
    		TimeSeries: []*monitoringpb.TimeSeries{{    			Metric: &metricpb.Metric{
    				Type: metricType,
    				Labels: map[string]string{
    					"environment": "STAGING",
    				},
    			},
    			Resource: &monitoredres.MonitoredResource{
    				Type: "gce_instance",
    				Labels: map[string]string{
    					"instance_id": "test-instance",
    					"zone":        "us-central1-f",
    				},
    			},
    			Points: []*monitoringpb.Point{{    				Interval: &monitoringpb.TimeInterval{
    					StartTime: now,
    					EndTime:   now,
    				},
    				Value: &monitoringpb.TypedValue{
    					Value: &monitoringpb.TypedValue_Int64Value{
    						Int64Value: rand.Int63n(10),
    					},
    				},
    			}},
    		}},
    	}
    	log.Printf("writeTimeseriesRequest: %+v\n", req)

    	err = c.CreateTimeSeries(ctx, req)
    	if err != nil {
    		return fmt.Errorf("could not write time series value, %v ", err)
    	}
    	return nil
    }
    

Java

String projectId = System.getProperty("projectId");
    // Instantiates a client
    MetricServiceClient metricServiceClient = MetricServiceClient.create();

    // Prepares an individual data point
    TimeInterval interval = TimeInterval.newBuilder()
        .setEndTime(Timestamps.fromMillis(System.currentTimeMillis()))
        .build();
    TypedValue value = TypedValue.newBuilder()
        .setDoubleValue(123.45)
        .build();
    Point point = Point.newBuilder()
        .setInterval(interval)
        .setValue(value)
        .build();

    List<Point> pointList = new ArrayList<>();
    pointList.add(point);

    ProjectName name = ProjectName.of(projectId);

    // Prepares the metric descriptor
    Map<String, String> metricLabels = new HashMap<>();
    Metric metric = Metric.newBuilder()
        .setType("custom.googleapis.com/my_metric")
        .putAllLabels(metricLabels)
        .build();

    // Prepares the monitored resource descriptor
    Map<String, String> resourceLabels = new HashMap<>();
    resourceLabels.put("instance_id", "1234567890123456789");
    resourceLabels.put("zone", "us-central1-f");

    MonitoredResource resource = MonitoredResource.newBuilder()
        .setType("gce_instance")
        .putAllLabels(resourceLabels)
        .build();

    // Prepares the time series request
    TimeSeries timeSeries = TimeSeries.newBuilder()
        .setMetric(metric)
        .setResource(resource)
        .addAllPoints(pointList)
        .build();

    List<TimeSeries> timeSeriesList = new ArrayList<>();
    timeSeriesList.add(timeSeries);

    CreateTimeSeriesRequest request = CreateTimeSeriesRequest.newBuilder()
        .setName(name.toString())
        .addAllTimeSeries(timeSeriesList)
        .build();

    // Writes time series data
    metricServiceClient.createTimeSeries(request);
    System.out.println("Done writing time series value.");

Node.js

// Imports the Google Cloud client library
    const monitoring = require('@google-cloud/monitoring');

    // Creates a client
    const client = new monitoring.MetricServiceClient();

    /**
     * TODO(developer): Uncomment and edit the following lines of code.
     */
    // const projectId = 'YOUR_PROJECT_ID';

    const dataPoint = {
      interval: {
        endTime: {
          seconds: Date.now() / 1000,
        },
      },
      value: {
        doubleValue: 123.45,
      },
    };

    const timeSeriesData = {
      metric: {
        type: 'custom.googleapis.com/stores/daily_sales',
        labels: {
          store_id: 'Pittsburgh',
        },
      },
      resource: {
        type: 'global',
        labels: {
          project_id: projectId,
        },
      },
      points: [dataPoint],
    };

    const request = {
      name: client.projectPath(projectId),
      timeSeries: [timeSeriesData],
    };

    // Writes time series data
    const result = await client.createTimeSeries(request);
    console.log(`Done writing time series data.`, result);
    

PHP

use Google\Api\Metric;
    use Google\Api\MonitoredResource;
    use Google\Cloud\Monitoring\V3\MetricServiceClient;
    use Google\Cloud\Monitoring\V3\Point;
    use Google\Cloud\Monitoring\V3\TimeInterval;
    use Google\Cloud\Monitoring\V3\TimeSeries;
    use Google\Cloud\Monitoring\V3\TypedValue;
    use Google\Protobuf\Timestamp;

    /**
     * Example:
     * ```
     * write_timeseries($projectId);
     * ```
     *
     * @param string $projectId Your project ID
     */
    function write_timeseries($projectId)
    {
        $metrics = new MetricServiceClient([
            'projectId' => $projectId,
        ]);

        $projectName = $metrics->projectName($projectId);

        $endTime = new Timestamp();
        $endTime->setSeconds(time());
        $interval = new TimeInterval();
        $interval->setEndTime($endTime);

        $value = new TypedValue();
        $value->setDoubleValue(123.45);

        $point = new Point();
        $point->setValue($value);
        $point->setInterval($interval);
        $points = [$point];

        $metric = new Metric();
        $metric->setType('custom.googleapis.com/stores/daily_sales');
        $labels = ['store_id' => 'Pittsburg'];
        $metric->setLabels($labels);

        $resource = new MonitoredResource();
        $resource->setType('global');
        $labels = ['project_id' => $projectId];
        $resource->setLabels($labels);

        $timeSeries = new TimeSeries();
        $timeSeries->setMetric($metric);
        $timeSeries->setResource($resource);
        $timeSeries->setPoints($points);

        $result = $metrics->createTimeSeries(
            $projectName,
            [$timeSeries]);

        printf('Done writing time series data.' . PHP_EOL);
    }

Python

client = monitoring_v3.MetricServiceClient()
    project_name = client.project_path(project_id)

    series = monitoring_v3.types.TimeSeries()
    series.metric.type = 'custom.googleapis.com/my_metric' + str(uuid.uuid4())
    series.resource.type = 'gce_instance'
    series.resource.labels['instance_id'] = '1234567890123456789'
    series.resource.labels['zone'] = 'us-central1-f'
    point = series.points.add()
    point.value.double_value = 3.14
    now = time.time()
    point.interval.end_time.seconds = int(now)
    point.interval.end_time.nanos = int(
        (now - point.interval.end_time.seconds) * 10**9)
    client.create_time_series(project_name, [series])

Ruby

client = Google::Cloud::Monitoring::Metric.new
    project_name = Google::Cloud::Monitoring::V3::MetricServiceClient.project_path project_id

    # Random suffix for metric type to avoid collisions with other runs
    random_suffix = rand(36**10).to_s(36)

    series = Google::Monitoring::V3::TimeSeries.new
    metric = Google::Api::Metric.new type: "custom.googleapis.com/my_metric#{random_suffix}"
    series.metric = metric

    resource = Google::Api::MonitoredResource.new type: "gce_instance"
    resource.labels["instance_id"] = "1234567890123456789"
    resource.labels["zone"] = "us-central1-f"
    series.resource = resource

    point = Google::Monitoring::V3::Point.new
    point.value = Google::Monitoring::V3::TypedValue.new double_value: 3.14
    now = Time.now
    end_time = Google::Protobuf::Timestamp.new seconds: now.to_i, nanos: now.usec
    point.interval = Google::Monitoring::V3::TimeInterval.new end_time: end_time
    series.points << point

    client.create_time_series project_name, [series]
    p "Time series created : #{metric.type}"

問題がある場合は、API 呼び出しのトラブルシューティングをご覧ください。

指標記述子の変更

また、 timeSeries.create新しいラベルをカスタム指標に追加します。カスタム指標記述子にラベルを追加するには、それらのラベルを時系列データに含めます。

書き込もうとしているラベルが有効で、なおかつ指標記述子のラベル数が上限の 10 個を超えない場合は、ラベルが追加されます。その後は、あたかもそのラベルが最初から存在していたかのように時系列データが書き込まれます。

新しいラベルを追加する以上の変更を加える場合は、指標記述子を削除して再作成する必要があります。この場合、それまでに収集された古い指標記述子の時系列データはすべて失われます。詳細については、指標の削除をご覧ください。

指標の名前を変更することはできません。