参加 2021 年 DevOps 现状问卷调查，塑造软件运维的未来，让我们了解您的想法。

创建自定义指标

自定义指标是用户定义的指标。本页面介绍了如何为自定义指标创建指标描述符，以及如何编写自定义指标数据。

自定义指标使用的元素与内置 Cloud Monitoring 指标相同：

  • 一组数据点。
  • 指标类型信息，用于说明数据点代表什么。
  • 受监控的资源信息，用于说明数据点的来源。

自定义指标的使用方式与内置指标相同。也就是说，您可以为自定义指标数据创建图表和提醒。

准备工作

如果您不熟悉所有指标的底层结构，请参阅指标、时间序列和资源。

自定义指标使用入门

要使用自定义指标，您必须有新指标类型的指标描述符。指标描述符定义数据的组织方式。在开始写入自定义指标数据之前，请确定您希望如何使用收集的数据，并确保数据组织支持这些目标。

创建指标描述符

Cloud Monitoring 可以自动为您创建指标描述符，也可以使用 Monitoring API 中的 metricDescriptors.create 方法自行创建指标描述符。您不能使用 Google Cloud Console for Monitoring 操纵指标描述符。

要让 Cloud Monitoring 为您创建指标描述符，您只需为指标写入时间序列数据，然后 Cloud Monitoring 会根据您写入的数据创建描述符。如需了解详情，请参阅自动创建指标描述符。自动创建存在限制，因此了解指标定义中包含哪些信息会很有帮助。获得新的自定义指标描述符后（无论是由您还是由 Monitoring 创建），您都可以将指标描述符用于指标描述符 API 方法和时间序列 API 方法。

无论您是明确创建指标描述符，还是让 Monitoring 根据您的数据为您创建指标描述符，您都需要确保数据的组织方式与您要查询这些数据的方式匹配。

组织数据

假设您有一个在单台机器上运行的程序，并且此程序调用辅助程序 A 和 B。您希望计算程序 A 和 B 的调用频率。您还想在程序 A 的调用频率超过每分钟 10 次，以及程序 B 的调用频率超过每分钟 5 次的时候收到提醒。

为了简化讨论，假设您有一个 Google Cloud 项目并且计划使用 global 受监控的资源。如需详细了解此选择，请参阅自定义指标的受监控资源。

考虑以下方法：

  • 使用两个自定义指标：Metric-type-A 计算对程序 A 的调用，Metric-type-B 计算对程序 B 的调用。此时，Metric-type-A 包含 1 个时间序列，Metric-type-B 包含 1 个时间序列。

    使用此数据模型时，您可以创建一个包含两个条件的提醒政策，也可以创建两个提醒政策，每个提醒包含一个条件。一个提醒政策可以支持多个条件，但对于通知渠道仅支持一个配置。

    如果您对受监控活动的数据之间的相似性不感兴趣，则此模型可能是合适的。在此示例中，活动为程序 A 和 B 的调用率。

  • 您可以使用一个自定义指标并使用标签来存储程序标识符。例如，标签可以存储值 A 或 B。由于 Monitoring 会为每个唯一的标签组合创建一个时间序列，因此该指标类型有两个时间序列。

    与上一个模型一样，您可以创建一个提醒政策或两个提醒政策。但是，提醒政策的条件更为复杂。要创建在程序 A 的调用率超过阈值时生成突发事件的条件，条件需要包含一个过滤器，该过滤器包括标签值为 A 的数据点并排除所有其他数据点。

    此模型的一个优势是计算比率很简单。例如，您可以确定总数中有多大比例是对 A 的调用。

  • 您可以使用一个自定义指标来计算调用次数，但不能使用标签记录调用了哪个程序。此模型有一个时间序列，其中结合了两个程序的数据。但是，您无法创建符合您目标的提醒政策，因为两个程序的数据无法分开。

命名自定义指标

创建自定义指标时，您可以定义表示指标类型的字符串标识符。此字符串在 Google Cloud 项目的自定义指标中必须是唯一的，并且必须使用将指标标记为用户定义的指标的前缀。对于 Monitoring，允许使用的前缀为 custom.googleapis.com/ 和 external.googleapis.com/prometheus。前缀后跟一个名称，用于描述您要收集的信息。如需详细了解命名自定义指标的推荐方法，请参阅命名规则。以下是两种指标类型的标识符示例：

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

所有指标类型都具有称为“资源名称”的全局唯一标识符。指标类型的资源名称结构为：

projects/[PROJECT_ID]/metricDescriptors/[METRIC_TYPE]

其中，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

名称还是类型？ 在指标描述符中，name 字段存储指标类型的资源名称，而 type 字段存储 METRIC_TYPE 字符串。

选择受监控的资源类型

将数据写入时间序列时，您必须指明数据的来源。为此，请选择一种受监控的资源类型，用于表示数据的来源，然后用它来描述特定来源。受监控的资源不属于指标类型；相反，您向其写入数据的时间序列包含对指标类型的引用（描述数据）和对受监控资源的引用（表示数据的来源）。

在创建指标描述符之前，请先考虑受监控的资源。您使用的受监控的资源类型会影响您需要在指标描述符中添加的标签。例如，如果您将虚拟机实例受监控资源与您的数据一起使用，那么您将不需要指标标签来指定实例。如需了解详情，请参阅自定义指标的受监控资源。

每个指标的数据点都必须与一个受监控的资源对象关联。不同受监控资源对象的数据点保存在不同的时间序列中。

自定义指标的受监控资源

您只能在自定义指标中使用以下受监控资源类型。

常见做法是使用表示运行应用代码的物理资源的受监控资源对象。这样做具有很多优势：

  • 与使用单一资源类型相比，您可以体验更好的性能。
  • 避免因多个进程向同一时间序列写入数据导致的数据无序。
  • 您的自定义指标数据可与来自同一资源的其他指标数据分为一组。

global 资源与通用资源

在某些情况下，如果没有更具体的资源类型适合使用，则 generic_task 和 generic_node 资源类型十分实用。generic_task 类型适用于定义类似任务的资源（如应用）。generic_node 类型适用于定义类似节点的资源（如虚拟机）。这两种 generic_* 类型都有多个可用于定义唯一资源对象的常见标签，让您可以轻松地在指标过滤条件中使用这些标签进行聚合和缩减。

相比之下，global 资源类型只有 project_id 和 location 标签。如果一个项目中有多个指标来源，则使用相同的 global 资源对象可能会导致您的指标数据发生冲突和被覆盖。

创建指标描述符

您为自定义指标收集的数据必须与 MetricDescriptor 对象关联，后者指定有关指标的各种信息。

您可以自行创建指标描述符，或者 Monitoring 可以为您创建指标描述符。

您可以通过有限的方式更改现有描述符；如需了解详情，请参阅修改指标描述符。

自动创建指标描述符

如果在自定义指标的指标描述符不存在时写入指标数据，则系统会自动创建指标描述符。但是，这个新的指标描述符可能不是您想要的；系统在自动创建指标描述符时会做出一些假设，并使用默认值。

具体而言，在调用 timeSeries.create 时，如果 TimeSeries 对象包含指定了不存在的指标类型名称的 Metric 对象，则 Cloud Monitoring 会创建一个具备以下字段的新 MetricDescriptor：

  • type：类型是从 Metric 对象的 type 字段中复制的。
  • name：名称是根据方法调用中的项目 ID 以及 Metric 对象中 type 的值创建的。
  • labels：标签是 Metric 对象中的标签。新指标描述符中的每个标签描述符都具备以下字段：
    • key：Metric 对象中的标签键。
    • valueType：STRING
    • description：未设置
  • metricKind：默认的指标种类为 GAUGE，但如果您指定 TimeSeries 对象的 metricKind 参数，则新指标将具备该参数指定的种类。您只能指定 GAUGE 和 CUMULATIVE 种类。
  • valueType：值类型取自写入的 Point 的值类型。必须为 BOOL、INT64、DOUBLE 或 DISTRIBUTION。如果您在 TimeSeries 的 valueType 字段中指定值类型，则该类型必须与 Point 的类型匹配。
  • unit：未设置
  • description："Auto created custom metric."。
  • displayName：未设置

单次 timeSeries.create 调用可以包含多个引用同一个不存在的指标类型的 TimeSeries 对象。在这种情况下，系统会以相同的方式设置新类型的字段，只是新的指标描述符中的标签包含对 create 的本次调用中所有时间序列中的 Metric 对象的所有标签的集合。

下一步：请参阅写入指标数据。

手动创建指标描述符

本部分介绍如何为自定义指标创建指标描述符。

准备工作

请完成以下步骤：

  • 为自定义指标选择指标名称或标识符。

  • 选择指标的显示名和说明。显示名将在 Google Cloud Console 中使用。

  • 选择一个或多个项目，在其中定义您的自定义指标并写入其时间序列数据。如果您需要在多个项目中使用相同的指标，请在每个项目中为指标提供相同的定义。

    如需写入来自 AWS 帐号管理的资源的自定义指标，请在该帐号的 AWS 连接器项目中创建指标描述符。

  • 确定指标的种类、值类型和（可选）单位。并非所有值类型和指标种类都支持自定义指标。 如需详细了解这些字段，请参阅值类型和指标种类。

  • 选择指标的标签 - 其名称、值类型和说明。

如需获取有关如何进行上述选择的更多帮助，您可以浏览内置指标以及查看时间序列数据。

创建指标描述符

要创建自定义指标的描述符，请调用 metricDescriptors.create 方法，并传入 MetricDescriptor 对象。

使用与现有自定义指标描述符相同的类型名称调用 metricDescriptors.create 通常会导致错误。但是，如果新 MetricDescriptor 对象的所有字段都与现有描述符的字段完全匹配，则不会出现错误，但不会产生任何效果。

在以下示例中，您将创建一个衡量 (gauge) 自定义指标。

协议

要创建指标描述符，请使用 metricDescriptors.create 方法。您可以使用方法参考页面上的 API Explorer 微件来执行此方法。 如需了解详情，请参阅 API Explorer。

以下是 metricDescriptors.create 的示例参数：

  • 名称（网址）：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 ”对话框，用于创建指标描述符。

点击执行按钮以运行该方法。

试试看！

在创建新的自定义指标时，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
	}
	defer c.Close()
	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 = f"projects/{project_id}"
descriptor = ga_metric.MetricDescriptor()
descriptor.type = "custom.googleapis.com/my_metric" + str(uuid.uuid4())
descriptor.metric_kind = ga_metric.MetricDescriptor.MetricKind.GAUGE
descriptor.value_type = ga_metric.MetricDescriptor.ValueType.DOUBLE
descriptor.description = "This is a simple example of a custom metric."

labels = ga_label.LabelDescriptor()
labels.key = "TestLabel"
labels.value_type = ga_label.LabelDescriptor.ValueType.STRING
labels.description = "This is a test label"
descriptor.labels.append(labels)

descriptor = client.create_metric_descriptor(
    name=project_name, metric_descriptor=descriptor
)
print("Created {}.".format(descriptor.name))

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

descriptor = Google::Api::MetricDescriptor.new(
  type:        metric_type,
  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 name:              project_name,
                                         metric_descriptor: descriptor
p "Created #{result.name}"
p result

如果遇到困难，请参阅 API 调用问题排查。

下一步：请参阅写入指标数据。

删除指标

要删除自定义指标，请删除其指标描述符。 您无法删除存储在 Google Cloud 项目中的时间序列数据；但是，删除指标描述符会导致数据无法访问。数据会根据数据保留政策过期并被系统删除。

您无法删除内置指标的指标描述符。

要删除自定义指标描述符，请调用 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. 点击执行按钮。

试试看！

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
	}
	defer c.Close()
	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(name=descriptor_name)
print("Deleted metric descriptor {}.".format(descriptor_name))

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
metric_name = client.metric_descriptor_path project:           project_id,
                                            metric_descriptor: metric_type

client.delete_metric_descriptor name: metric_name
p "Deleted metric descriptor #{metric_name}."

如果遇到困难，请参阅 API 调用问题排查。

写入指标数据

您只能将数据写入自定义指标的指标类型。要写入数据，请使用 timeSeries.create 方法。如果时间序列已存在，则此方法会将新数据点附加到现有时间系列。如果时间序列不存在，则此方法将创建该时间序列并附加数据。

您可以通过将 TimeSeries 对象列表传递到 timeSeries.create 来写入数据点。列表大小上限为 200，列表中的每个对象都必须指定不同的时间序列：

  • 每个时间序列都由 TimeSeries 对象的 metric 和 resource 字段标识。这些字段表示数据的指标类型以及从中收集数据的受监控资源。
  • 省略字段 metricKind 和 valueType；写入数据点时，系统会忽略这两个字段。

  • 每个 TimeSeries 对象只能包含一个 Point 个对象：

    • 该点的值和时段必须与指标类型的定义一致。如需了解不同指标种类的时间间隔，请参阅 TimeInterval。
    • 该点的时段必须晚于时间序列中已有的点。
    • 时段的结束时间不得早于 25 小时之前，也不得晚于 5 分钟后。

  • 如果要向同一时间序列写入多个点，请对每个点分别使用 timeSeries.create 方法。请勿将数据写入速度超过每 10 秒 1 个数据点的单个时间序列。如果您要将数据点添加到不同的时间序列，则没有速率限制。

协议

要写入数据，请使用 timeSeries.create 方法。您可以使用方法参考页面上的 API Explorer 微件来执行此方法。 如需了解详情，请参阅 API Explorer。

要将数据点写入在手动创建指标描述符中创建的 stores/daily_sales 自定义指标，请执行以下操作：

  1. 转到 timeSeries.create 的参考页面。
  2. 将以下参数提供给 API Explorer 微件。
  3. 点击执行按钮。

使用以下示例参数：

  • 名称：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
	}
	defer c.Close()
	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 = f"projects/{project_id}"

series = monitoring_v3.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"
now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10 ** 9)
interval = monitoring_v3.TimeInterval(
    {"end_time": {"seconds": seconds, "nanos": nanos}}
)
point = monitoring_v3.Point({"interval": interval, "value": {"double_value": 3.14}})
series.points = [point]
client.create_time_series(name=project_name, time_series=[series])

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

series = Google::Cloud::Monitoring::V3::TimeSeries.new
series.metric = Google::Api::Metric.new type: metric_type

resource = Google::Api::MonitoredResource.new type: "global"
resource.labels["project_id"] = project_id
series.resource = resource

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

client.create_time_series name: project_name, time_series: [series]
p "Time series created."

如果遇到困难，请参阅 API 调用问题排查。

修改指标描述符

如需向现有自定义指标添加标签，请使用 timeSeries.create 方法，并包含新标签和时间序列数据的。如果您尝试写入的标签有效，并且不会导致指标描述符中的标签数超过标签限制（10 个），则标签将被添加。然后写入时间序列数据，就好像标签从一开始就存在一样。

如果您要执行添加新标签以外的操作，必须删除并重新创建指标描述符。在这种情况下，您将丢失先前为旧指标描述符收集的所有时间序列数据。如需详细了解，请参阅删除指标。

您无法重命名指标。

后续步骤