建立自訂指標

如要定義自訂指標,請使用 metricDescriptors.create API 方法建立自訂指標描述元。雖然可以為您的指標直接寫入時間序列資料,並讓 Monitoring 自動建立指標描述元,但您應該瞭解會將哪些資訊送入指標定義。建立新的自訂指標描述元之後,您可以將指標與指標描述元 API 方法以及時間序列 API 方法搭配使用。您也可以在 Monitoring 中針對圖表與快訊使用指標。

自訂指標名稱

建立自訂指標時,您可以指派一個在 GCP 專案的自訂指標中不重複的自訂指標類型名稱。這個類型名稱必須以 custom.googleapis.com/ 開頭,後面是一個簡單名稱或路徑名稱。路徑名稱可協助您整理自訂指標,但會像簡單名稱一樣處理。詳情請參閱命名規則一文。以下是兩種類型名稱的範例:

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 物件,以指定關於指標的各種資訊。以下是您將需要的資訊:

  • 如前一節所述,為自訂指標選擇類型名稱。

  • 選擇用來定義自訂指標並寫入指標時間序列資料的專案。AWS 的自訂指標應在 AWS 帳戶的 AWS 連接器專案中建立。您選擇的專案也必須是您監控指標所在的工作區成員。如果您在多個專案中需要相同的指標,請在每個專案中對指標進行相同的定義。

  • 選擇指標的顯示名稱與說明。顯示名稱會用於 Monitoring 的使用者介面。

  • 選擇指標的種類、值類型與 (選擇性) 單位。自訂指標並不支援所有的值類型與指標種類。請參閱指標種類

  • 選擇指標的標籤,也就是名稱、值類型與說明。

  • 選擇您將包含在指標時間序列資料點中的受控資源物件。您應該在建立指標描述元之前就考慮到這一點。您使用的受控資源類型會影響需要的指標標籤。例如,如果您將 VM 執行個體物件包含在資料中,則不需要指標標籤來指定執行個體。詳情請參閱選擇受控資源類型

如要進一步瞭解如何選擇,請瀏覽內建指標,並查看指標時間序列資料

選擇受控資源類型

您的每個指標資料點都必須包含受控資源物件。來自不同受控資源物件的資料點保存在不同的時間序列中。

您只能在自訂指標中使用下列受控資源類型。

常見做法是使用代表執行應用程式程式碼之實體資源的受控資源物件。這個做法有多個優點:

  • 相較於使用單一資源類型,您會獲得更好的效能。
  • 您可以避免因將多個程序寫入相同時間序列而導致資料變得雜亂無章。
  • 您的自訂指標資料可以與相同資源中的其他指標資料分組在一起。

global 與一般資源的比較

在沒有更適當的具體資源類型可用的情況下,generic_taskgeneric_node 就會變得相當實用。generic_task 類型適用於定義類似工作的資源 (如應用程式)。generic_node 類型適用於定義類似節點的資源 (如虛擬機器)。兩種 generic_* 類型都有幾個可用於定義專屬資源物件的常用標籤,方便您在指標篩選條件中用來執行匯總和縮減作業。

相比之下,global 資源類型只有 project_idlocation 這兩個標籤。如果專案中有很多指標來源,使用相同的 global 資源物件可能會造成指標資料發生衝突或遭到覆寫。

呼叫 create 方法

在您做出選擇之後,請呼叫 metricDescriptors.create 方法,傳入 MetricDescriptor 物件,或者參閱自動建立指標描述元。您只能以有限的方式變更現有的描述元。詳情請參閱修改指標描述元

一般而言,使用與現有自訂指標描述元相同的類型名稱來呼叫 metricDescriptors.create 是錯誤的做法。但是,如果新 MetricDescriptor 物件的所有欄位都與現有描述元的欄位完全相符,則這類呼叫並非錯誤,但卻會無效。

建立指標描述元

在下列範例中,您會建立一個取樣自訂指標 custom.googleapis.com/stores/daily_sales。這個指標擁有單一維度標籤 store_id

通訊協定

如要建立指標描述元,請使用 metricDescriptors.create 方法。您可以使用方法參考資料頁面上的 API Explorer 小工具來執行這個方法。詳情請參閱 API Explorer

以下是 metricDescriptors.create 的範例參數:

  • 名稱 (網址):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."
        },
      ],
    }
    

使用您的專案 ID 取代 [PROJECT_ID],將這些值提供給小工具中的欄位:

建立指標描述元

按一下 [Execute] (執行) 按鈕來執行這個方法。

試做看看!

建立新自訂指標時,MetricDescriptor 中的 name 欄位會遭到忽略,且可以省略。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 物件的 metricresource 欄位識別。
  • 省略欄位 metricKindvalueType;寫入資料點時,會忽略這兩個欄位。
  • 每個 TimeSeries 物件都只能包含單一資料點物件:

    • 資料點的值與時間間隔必須與指標類型的定義保持一致。如要瞭解不同指標種類的時間間隔,請參閱指標種類
    • 資料點的時間間隔必須晚於已在時間序列中的任何資料點。
    • 間隔的結束時間在過去不得超過 24 小時,在未來不得超過五分鐘。
  • 如果您想要將多個資料點寫入相同的時間序列,請針對每個資料點單獨呼叫 timeSeries.create 方法。每分鐘請勿呼叫超過一次。如果您要將資料點新增至不同的時間序列,則沒有頻率限制。

通訊協定

如要寫入指標資料,請使用 timeSeries.create 方法。您可以使用方法參考資料頁面上的 API Explorer 小工具來執行這個方法。詳情請參閱 API Explorer

如要將資料點寫入在建立指標描述元一節中建立的 stores/daily_sales 自訂指標,請按照下列步驟操作:

  1. 前往 timeSeries.create 參考資料頁面
  2. 將下列參數提供給 API Explorer 小工具。
  3. 按一下 [Execute] (執行) 按鈕

使用下列範例參數:

  • 名稱projects/[PROJECT_ID]
  • 要求主體:包含 TimeSeries 物件的清單。下列範例清單中只包含一個時間序列。

    {
     "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 期間,如果 TimeSeries 物件包含的指標物件指定了不存在的指標類型名稱,那麼 Stackdriver Monitoring 就會建立含有下列欄位的新 MetricDescriptor

  • type:系統會從指標物件的 type 欄位複製類型。
  • name:系統會從方法呼叫中的專案 ID 與 Metric 物件中的 type 值來建立名稱。
  • labels:這些標籤就是顯示在 Metric 物件中的標籤。新指標描述元中的每個標籤描述元都有下列欄位:
    • keyMetric 物件中的標籤鍵
    • valueTypeSTRING
    • description:未設定
  • metricKind:預設指標種類為 GAUGE,但如果您指定 TimeSeries 物件的 metricKind 參數,則新指標會含有這個種類。您只能指定 GAUGECUMULATIVE 種類。
  • valueType:值類型會從要寫入資料點的輸入值取得,這些類型必須為 BOOLINT64DOUBLEDISTRIBUTION。如果您在 TimeSeriesvalueType 欄位中指定值類型,則這個類型必須與資料點的類型相符。
  • unit:未設定。
  • description"Auto created custom metric."
  • displayName:未設定。

在單一 timeSeries.create 呼叫中,您可以納入多個參照同一種不存在的自訂指標類型的 TimeSeries 物件。在這種情況下,系統會以相同方式設定新類型的欄位,但新指標描述元中的標籤會由 create 呼叫的所有時間序列中指標物件內的所有標籤聯集所組成。

修改指標描述元

您也可以使用 timeSeries.create 呼叫來將新標籤新增到自訂指標中。只要把標籤包含在時間序列資料中,就可以將這些標籤新增到您的自訂指標描述元。

如果您嘗試寫入的標籤有效,而且不會導致指標描述元中的標籤數量超過上限 (10 個),您就可以順利新增標籤。接著,就像一開始就有標籤一樣,系統會寫入時間序列資料。

如要執行新增標籤之外的其他操作,則必須刪除並重新建立指標描述元。在這種情況下,您會遺失之前針對舊指標描述元收集的所有時間序列資料。詳情請參閱刪除指標

您無法重新命名指標。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Monitoring
需要協助嗎?請前往我們的支援網頁