カスタム指標の作成

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

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

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

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

Stackdriver Monitoring で指標記述子を作成するには、単に指標に対する時系列データを書き込むと、Stackdriver Monitoring が、書き込まれたデータに基づいて記述子を作成します。自動作成には制限があるため、どの情報が指標定義に含まれるか知っておくと便利です。

新しいカスタム指標記述子を作成すると、自分で作成したか Monitoring が作成したかにかかわらず、指標記述子 API メソッド時系列 API メソッドでその指標記述子を使用できます。

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

カスタム指標名

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

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

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

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 オブジェクトを提供する必要があります。Stackdriver Monitoring はこれを自動的に作成できます。詳しくは、指標記述子の自動作成をご覧ください。

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

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

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

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

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

  • 指標の表示名と説明を選択します。表示名は Monitoring のコンソールで使用されます。

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

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

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

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

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

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

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

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

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

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

  • aws_ec2_instance: Amazon EC2 インスタンス。
  • dataflow_job: Dataflow ジョブ。
  • gce_instance: Google Compute Engine インスタンス。
  • gke_container: Kubernetes Engine コンテナ インスタンス。
  • generic_node: ユーザー指定のコンピューティング ノード。
  • generic_task: ユーザー定義のタスク。
  • global: 他に適切なリソースタイプがない場合はこのリソースを使用します。ほとんどのケースでは、global よりも generic_node または generic_task の方が適切です。
  • 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 が Stackdriver 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 のサンプル パラメータを次に示します。

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

    {
      "name": "",
      "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."
        },
      ],
    }
    

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

指標記述子の作成

[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)
    .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' + RANDOM_SUFFIX
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. metricDescriptors.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.metricDescriptorPath(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. 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);
    $filter = 'metric.type="compute.googleapis.com/instance/cpu/utilization"';

    $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' + RANDOM_SUFFIX
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 個を超えない場合は、ラベルが追加されます。その後は、あたかもそのラベルが最初から存在していたかのように時系列データが書き込まれます。

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

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

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

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

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