MCP Tools Reference: monitoring.googleapis.com

工具：list_timeseries

列出 Google Cloud Monitoring API 中的时序数据

以下示例演示了如何使用 curl 调用 list_timeseries MCP 工具。

Curl 请求 
                  
curl --location 'https://monitoring.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_timeseries",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

ListTimeSeries 请求。

ListTimeSeriesRequest

JSON 表示法 
{
  "name": string,
  "filter": string,
  "interval": {
    object (TimeInterval)
  },
  "aggregation": {
    object (Aggregation)
  },
  "secondaryAggregation": {
    object (Aggregation)
  },
  "orderBy": string,
  "view": enum (TimeSeriesView),
  "pageSize": integer,
  "pageToken": string
}
字段
name

string

必需。执行请求的项目、组织或文件夹。格式为：

projects/[PROJECT_ID_OR_NUMBER]
organizations/[ORGANIZATION_ID]
folders/[FOLDER_ID]
filter

string

必需。用于指定应返回哪些时序的监控过滤条件。过滤条件必须指定单个指标类型，并且还可以指定指标标签和其他信息。例如：

metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = "my-instance-name"
interval

object (TimeInterval)

必需。应返回结果的时间间隔。响应中仅包含在指定时间间隔内包含数据点的时序。
aggregation

object (Aggregation)

指定各个时序中数据点的对齐方式，以及如何跨指定标签组合检索到的时序。

默认情况下（如果未明确指定 aggregation），系统会返回原始时序数据。
secondaryAggregation

object (Aggregation)

在应用 aggregation 后应用第二次聚合。只有在指定了 aggregation 时才能指定。
orderBy

string

不支持：必须留空。目前，每个时序中的点均以反向时间顺序（从最新到最旧）返回。
view

enum (TimeSeriesView)

必需。指定返回哪些有关时序的信息。
pageSize

integer

一个正数，表示要返回的结果数上限。如果 page_size 为空或超过 10 万个结果，则有效 page_size 为 10 万个结果。如果 view 设置为 FULL，则这是返回的 Points 数上限。如果 view 设置为 HEADERS，则这是返回的 TimeSeries 数上限。
pageToken

string

如果此字段不为空，则必须包含之前调用此方法返回的 nextPageToken 值。使用此字段会导致该方法返回之前方法调用中的其他结果。

TimeInterval

JSON 表示法 
{
  "endTime": string,
  "startTime": string
}
字段
endTime

string (Timestamp format)

必需。时间间隔的结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
startTime

string (Timestamp format)

可选。时间间隔的开始时间。开始时间的默认值为结束时间。开始时间不得晚于结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 到 253402300799 之间（含边界值），对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代项。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

聚合

JSON 表示法 
{
  "alignmentPeriod": string,
  "perSeriesAligner": enum (Aligner),
  "crossSeriesReducer": enum (Reducer),
  "groupByFields": [
    string
  ]
}
字段
alignmentPeriod

string (Duration format)

alignment_period 指定一个时间间隔（以秒为单位），用于将所有 time series 中的数据划分为一致的时间块。此操作将在应用序列对齐器之前完成。

该值必须至少为 60 秒。如果指定了除 ALIGN_NONE 以外的每个序列对齐器，则此字段是必需的，否则系统会返回错误。如果未指定任何每个序列对齐器，或者指定了对齐器 ALIGN_NONE，则系统会忽略此字段。

对于图表，alignment_period 的最大值为 104 周（2 年）；对于提醒政策，最大值为 90,000 秒（25 小时）。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
perSeriesAligner

enum (Aligner)

Aligner 用于描述如何使单个时序中的数据点在时间上保持一致。除了 ALIGN_NONE 之外，所有对齐方式都会使 alignment_period 中的所有数据点在数学上分组在一起，从而为每个 alignment_period 生成一个数据点，其结束时间戳位于相应时间段的末尾。

并非所有对齐操作都可应用于所有时序。有效选项取决于原始时序的 metric_kind 和 value_type。对齐可以更改时序的 metric_kind 或 value_type。

时序数据必须对齐，才能执行跨时序缩减。如果指定了 cross_series_reducer，则必须指定 per_series_aligner，且 per_series_aligner 不得等于 ALIGN_NONE，并且必须指定 alignment_period；否则，系统会返回错误。
crossSeriesReducer

enum (Reducer)

用于将多个时序合并为单个时序的缩减操作，其中结果时序中每个数据点的值是输入时序中所有已对齐的值的函数。

并非所有缩减器操作都可以应用于所有时序。有效选择取决于原始时序的 metric_kind 和 value_type。缩减可能会生成与输入时序具有不同 metric_kind 或 value_type 的时序。

时序数据必须先进行校准（请参阅 per_series_aligner），然后才能执行跨时序缩减。如果指定了 cross_series_reducer，则必须指定 per_series_aligner，且不得为 ALIGN_NONE。还必须指定 alignment_period；否则，系统会返回错误。
groupByFields[]

string

指定 cross_series_reducer 时要保留的字段集。group_by_fields 用于确定在应用聚合操作之前如何将时序划分为子集。每个子集都包含在每个分组字段中具有相同值的时序。每个时序都恰好属于一个子集。cross_series_reducer 应用于每个时序子集。无法跨不同资源类型进行缩减，因此此字段隐式包含 resource.type。未在 group_by_fields 中指定的字段会被聚合掉。如果未指定 group_by_fields 且所有时序都具有相同的资源类型，则这些时序会聚合为单个输出时序。如果未定义 cross_series_reducer，则系统会忽略此字段。

时长

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

时间跨度的有符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些边界值是通过以下计算得出的：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10,000 年
nanos

integer

时间跨度的有符号秒数小数部分（以纳秒为单位）。小于 1 秒的时长用 0 seconds 字段和正或负 nanos 字段表示。对于时长为 1 秒或更长时间的视频，nanos 字段的非零值必须与 seconds 字段的符号相同。必须介于 -999,999,999 到 +999,999,999 之间（含边界值）。

校准器

Aligner 用于指定将应用于时序中每个校准时间段内的数据点的操作。除了 ALIGN_NONE（指定不应用任何操作）之外，每种校准操作都会将每个校准时间段内的一组数据值替换为一个值，即对数据值应用相应操作的结果。校准后的时序在每个 alignment_period 结束时都只有一个数据值。

对齐操作也可以更改值的数据类型。例如，如果您对布尔值应用计数操作，原始时序中的数据 value_type 为 BOOLEAN，但对齐结果中的 value_type 为 INT64。

枚举
ALIGN_NONE 不进行对齐。返回原始数据。如果请求了跨序列缩减，则此值无效。结果的 value_type 与输入的 value_type 相同。
ALIGN_DELTA

对齐并转换为 DELTA。输出为 delta = y1 - y0。

此对齐方式适用于 CUMULATIVE 和 DELTA 指标。如果所选的对齐周期导致某些周期没有数据，则通过插值创建相应周期的对齐值。对齐结果的 value_type 与输入的 value_type 相同。
ALIGN_RATE

校准并转换为速率。结果计算为 rate = (y1 - y0)/(t1 - t0)，即“随时间变化的增量”。可以将此校准器视为提供通过 alignment_period 开头和结尾处的值的直线的斜率。

此校准器适用于具有数值的 CUMULATIVE 和 DELTA 指标。如果所选的对齐周期导致某些周期没有数据，则系统会通过插值来创建相应周期的对齐值。输出是一个 GAUGE 指标，其值为 value_type DOUBLE。

如果您所说的“比率”是指“百分比变化”，请改用 ALIGN_PERCENT_CHANGE 对齐器。
ALIGN_INTERPOLATE 通过在校准时间段边界周围的相邻点之间插值来进行校准。此校准器适用于具有数值的 GAUGE 指标。校准结果的 value_type 与输入的 value_type 相同。
ALIGN_NEXT_OLDER 通过将校准时间段结束前的最近的数据点移动到校准时间段结束时的边界来校准数据点。此校准器适用于 GAUGE 指标。校准结果的 value_type 与输入的 value_type 相同。value_type
ALIGN_MIN 通过返回每个校准时间段中的最小值来校准时序。此校准器适用于具有数值的 GAUGE 和 DELTA 指标。对齐后结果的 value_type 与输入的 value_type 相同。
ALIGN_MAX 通过返回每个校准时间段中的最大值来校准时序。此校准器适用于具有数值的 GAUGE 和 DELTA 指标。对齐后结果的 value_type 与输入的 value_type 相同。
ALIGN_MEAN 通过返回每个校准时间段中的平均值来校准时序。此校准器适用于具有数值的 GAUGE 和 DELTA 指标。校准后结果的 value_type 为 DOUBLE。
ALIGN_COUNT 通过返回每个校准时间段中的值的数量来校准时序。此校准器适用于具有数值或布尔值的 GAUGE 和 DELTA 指标。校准后结果的 value_type 为 INT64。
ALIGN_SUM 通过返回每个校准时间段中的值之和来校准时序。此校准器适用于具有数值和分布值的 GAUGE 和 DELTA 指标。对齐后结果的 value_type 与输入的 value_type 相同。
ALIGN_STDDEV 通过返回每个校准时间段中的值的标准差来校准时序。此校准器适用于具有数值的 GAUGE 和 DELTA 指标。输出的 value_type 为 DOUBLE。
ALIGN_COUNT_TRUE 通过返回每个校准时间段中的 True 值数量来校准时序。此校准器适用于具有布尔值的 GAUGE 指标。输出的 value_type 为 INT64。
ALIGN_COUNT_FALSE 通过返回每个校准时间段中的 False 值数量来校准时序。此校准器适用于具有布尔值的 GAUGE 指标。输出的 value_type 为 INT64。
ALIGN_FRACTION_TRUE 通过返回每个校准时间段中 True 值数量与值总数的比率来校准时序。此校准器适用于具有布尔值的 GAUGE 指标。输出值在 [0.0, 1.0] 范围内，且具有 value_type DOUBLE。
ALIGN_PERCENTILE_99 使用百分位聚合校准时序。每个校准时间段内生成的数据点是该时间段内所有数据点的第 99 个百分位。此校准器适用于具有分布值的 GAUGE 和 DELTA 指标。输出是一个 GAUGE 指标，其值为 value_type DOUBLE。
ALIGN_PERCENTILE_95 使用百分位聚合校准时序。每个校准时间段内生成的数据点是该时间段内所有数据点的第 95 个百分位。此校准器适用于具有分布值的 GAUGE 和 DELTA 指标。输出是一个 GAUGE 指标，其值为 value_type DOUBLE。
ALIGN_PERCENTILE_50 使用百分位聚合校准时序。每个校准时间段内生成的数据点是该时间段内所有数据点的第 50 个百分位。此校准器适用于具有分布值的 GAUGE 和 DELTA 指标。输出是一个 GAUGE 指标，其值为 value_type DOUBLE。
ALIGN_PERCENTILE_05 使用百分位聚合校准时序。每个校准时间段内生成的数据点是该时间段内所有数据点的第 5 个百分位。此校准器适用于具有分布值的 GAUGE 和 DELTA 指标。输出是一个 GAUGE 指标，其值为 value_type DOUBLE。
ALIGN_PERCENT_CHANGE

对齐并转换为百分比变化。此校准器适用于具有数值的 GAUGE 和 DELTA 指标。此对齐方式会返回 ((current - previous)/previous) * 100，其中 previous 的值是根据 alignment_period 确定的。

如果 current 和 previous 的值均为 0，则返回的值为 0。如果只有 previous 为 0，则返回的值为无穷大。

在上述计算之前，系统会在校准周期的每个点计算 10 分钟移动平均值，以平滑指标并防止因非常短暂的峰值而出现误报。移动平均值仅适用于值为 >= 0 的数据。任何值为 < 0 的数据都会被视为缺失数据点并被忽略。虽然此校准接受 DELTA 指标，但应特别注意，该指标的值始终为正。输出是 GAUGE 指标，其中 value_type 为 DOUBLE。

缩减器

Reducer 操作描述了如何将多个时序中的数据点聚合为单个时序，其中结果序列中每个数据点的值是输入时序中所有已对齐的值的函数。

枚举
REDUCE_NONE 无跨时序缩减。返回 Aligner 的输出。
REDUCE_MEAN 通过计算每个校准时间段内时序的平均值进行缩减。此缩减器适用于具有数值或分布值的 DELTA 和 GAUGE 指标。输出的 value_type 为 DOUBLE。
REDUCE_MIN 通过计算每个校准时间段内时序的最小值进行缩减。此精简器适用于具有数值的 DELTA 和 GAUGE 指标。输出的 value_type 与输入的 value_type 相同。
REDUCE_MAX 通过计算每个校准时间段内时序的最大值进行缩减。此精简器适用于具有数值的 DELTA 和 GAUGE 指标。输出的 value_type 与输入的 value_type 相同。
REDUCE_SUM 通过计算每个校准时间段的时序的总和进行缩减。此缩减器适用于具有数值和分布值的 DELTA 和 GAUGE 指标。输出的 value_type 与输入的 value_type 相同。
REDUCE_STDDEV 通过计算每个校准时间段的时序标准差进行缩减。此缩减器适用于具有数值或分布值的 DELTA 和 GAUGE 指标。输出的 value_type 为 DOUBLE。
REDUCE_COUNT 通过计算每个校准时间段内时序的数据点数量进行缩减。此缩减器适用于数值、布尔值、分布和字符串 value_type 的 DELTA 和 GAUGE 指标。输出的 value_type 为 INT64。
REDUCE_COUNT_TRUE 通过计算每个校准时间段内时序中 True 值数据点的数量进行缩减。此缩减器适用于布尔值 value_type 的 DELTA 和 GAUGE 指标。输出的 value_type 为 INT64。
REDUCE_COUNT_FALSE 通过计算每个校准时间段内时序中 False 值数据点的数量进行缩减。此缩减器适用于布尔值 value_type 的 DELTA 和 GAUGE 指标。输出的 value_type 为 INT64。
REDUCE_FRACTION_TRUE 通过计算每个校准时间段内值为 True 的数据点数量与数据点总数的比率进行缩减。此归约器适用于布尔值 value_type 的 DELTA 和 GAUGE 指标。输出值在 [0.0, 1.0] 范围内，且具有 value_type DOUBLE。
REDUCE_PERCENTILE_99 通过计算每个校准时间段内各个时序的数据点的第 99 百分位进行缩减。此缩减器适用于数值型和分布型 GAUGE 和 DELTA 指标。输出的值为 DOUBLE。
REDUCE_PERCENTILE_95 通过计算每个校准时间段内各时序的数据点的第 95 百分位进行缩减。此缩减器适用于数值型和分布型 GAUGE 和 DELTA 指标。输出的值为 DOUBLE。
REDUCE_PERCENTILE_50 通过计算每个校准时间段内各个时序的数据点的第 50 百分位进行缩减。此缩减器适用于数值型和分布型 GAUGE 和 DELTA 指标。输出的值为 DOUBLE。
REDUCE_PERCENTILE_05 通过计算每个校准时间段内各个时序的数据点的第 5 个百分位进行缩减。此缩减器适用于数值型和分布型 GAUGE 和 DELTA 指标。输出的值为 DOUBLE。

TimeSeriesView

控制 ListTimeSeries* 返回哪些字段。

枚举
FULL 返回指标、时序和时序数据的身份信息。
HEADERS 返回指标和时序资源的身份，但不返回时序数据。

输出架构

ListTimeSeries 的回答。

ListTimeSeriesResponse

JSON 表示法 
{
  "timeSeries": [
    {
      object (TimeSeries)
    }
  ],
  "nextPageToken": string,
  "executionErrors": [
    {
      object (Status)
    }
  ],
  "unit": string,
  "unreachable": [
    string
  ]
}
字段
timeSeries[]

object (TimeSeries)

与请求中包含的过滤条件匹配的一个或多个时序。
nextPageToken

string

如果结果数量超过已返回的结果数量，则此字段会设置为非空值。如需查看更多结果，请在下次调用此方法时将该值用作 page_token。
executionErrors[]

object (Status)

可能导致返回的时序数据不完整的查询执行错误。
unit

string

报告所有 time_series 点值时所用的单位。unit 遵循 UCUM 单位格式，如 https://unitsofmeasure.org/ucum.html 中所示。如果不同的 time_series 具有不同的单位（例如，因为它们来自不同的指标类型，或者缺少单位），则 unit 将为“{not_a_unit}”。
unreachable[]

string

无法访问的云区域，这可能导致返回的数据不完整。

TimeSeries

JSON 表示法 
{
  "metric": {
    object (Metric)
  },
  "resource": {
    object (MonitoredResource)
  },
  "metadata": {
    object (MonitoredResourceMetadata)
  },
  "metricKind": enum (MetricKind),
  "valueType": enum (ValueType),
  "points": [
    {
      object (Point)
    }
  ],
  "unit": string,
  "description": string
}
字段
metric

object (Metric)

关联的指标。用于标识时序的完整指定指标。
resource

object (MonitoredResource)

关联的受监控资源。自定义指标在其时序数据中只能使用特定的受监控资源类型。如需了解详情，请参阅自定义指标的受监控资源。
metadata

object (MonitoredResourceMetadata)

仅限输出。关联的受监控资源元数据。在读取时序时，此字段将包含在归约中显式命名的元数据标签。在创建时序时，此字段会被忽略。
metricKind

enum (MetricKind)

时序的指标种类。 在列出时序时，如果该时序是其他时序的对齐或归约结果，则此指标种类可能与关联指标的种类不同。

在创建时序时，此字段是可选的。如果存在，它必须与关联指标的指标种类相同。如果必须自动创建关联指标的描述符，则此字段指定新描述符的指标种类，且必须是 GAUGE（默认值）或 CUMULATIVE。
valueType

enum (ValueType)

时序的值类型。 在列出时序时，如果该时序是其他时序的对齐或归约结果，则此值类型可能与关联指标的值类型不同。

在创建时序时，此字段是可选的。如果存在，它必须与 points 字段中的数据类型相同。
points[]

object (Point)

此时序的数据点。列出时序时，各点以反向时间顺序返回。

创建时序时，此字段必须仅包含一个点，并且该点的类型必须与关联指标的值类型相同。如果必须自动创建关联指标的描述符，则描述符的值类型由该点的类型决定，必须是 BOOL、INT64、DOUBLE 或 DISTRIBUTION。
unit

string

报告指标值时所用的单位。仅当 value_type 为 INT64、DOUBLE 或 DISTRIBUTION 时适用。unit 定义了存储的指标值的表示形式。仅当此字段为空时，才能通过 CreateTimeSeries 进行更改。
description

string

仅限输入。与指标的 google.api.MetricDescriptor 关联的时序的详细说明。一旦设置，此字段无法通过 CreateTimeSeries 进行更改。

指标

JSON 表示法 
{
  "type": string,
  "labels": {
    string: string,
    ...
  }
}
字段
type

string

现有指标类型，请参阅 google.api.MetricDescriptor。例如 custom.googleapis.com/invoice/paid/amount。
labels

map (key: string, value: string)

可唯一标识相应指标的一组标签值。必须为 MetricDescriptor 中列出的所有标签分配值。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

LabelsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

MonitoredResource

JSON 表示法 
{
  "type": string,
  "labels": {
    string: string,
    ...
  }
}
字段
type

string

必需。受监控的资源类型。此字段必须与 MonitoredResourceDescriptor 对象的 type 字段匹配。例如，Compute Engine 虚拟机实例的类型为 gce_instance。如需查看类型列表，请参阅监控资源类型和日志记录资源类型。
labels

map (key: string, value: string)

必需。关联的受监控资源描述符中列出的所有标签的值。例如，Compute Engine 虚拟机实例使用标签 "project_id"、"instance_id" 和 "zone"。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

LabelsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

MonitoredResourceMetadata

JSON 表示法 
{
  "systemLabels": {
    object
  },
  "userLabels": {
    string: string,
    ...
  }
}
字段
systemLabels

object (Struct format)

仅限输出。预定义系统元数据标签的值。系统标签是 Google 提取的一种元数据，包括“machine_image”、“vpc”、“subnet_id”、“security_group”、“name”等。系统标签值只能是字符串、布尔值或字符串列表。例如：

{ "name": "my-test-instance",
  "security_group": ["a", "b", "c"],
  "spot_instance": false }
userLabels

map (key: string, value: string)

仅限输出。用户定义的元数据标签的映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

无序的动态类型值映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。此类型也无法表示较大的 Int64 值，因为 JSON 格式通常不支持在其数字类型中使用这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

UserLabelsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

点

JSON 表示法 
{
  "interval": {
    object (TimeInterval)
  },
  "value": {
    object (TypedValue)
  }
}
字段
interval

object (TimeInterval)

该数据点适用的时间间隔。对于 GAUGE 指标，开始时间是可选的，但如果提供了开始时间，则必须等于结束时间。对于 DELTA 指标，开始时间和结束时间应指定一个非零间隔，后续点指定连续和非重叠的间隔。对于 CUMULATIVE 指标，开始时间和结束时间应指定一个非零间隔，后续点指定相同的开始时间并增加结束时间，直到事件将累积值重置为零，并为以下各点设置新的开始时间。
value

object (TypedValue)

数据点的值。

TimeInterval

JSON 表示法 
{
  "endTime": string,
  "startTime": string
}
字段
endTime

string (Timestamp format)

必需。时间间隔的结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
startTime

string (Timestamp format)

可选。时间间隔的开始时间。开始时间的默认值为结束时间。开始时间不得晚于结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 到 253402300799 之间（含边界值），对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代项。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

TypedValue

JSON 表示法 
{

  // Union field value can be only one of the following:
  "boolValue": boolean,
  "int64Value": string,
  "doubleValue": number,
  "stringValue": string,
  "distributionValue": {
    object (Distribution)
  }
  // End of list of possible types for union field value.
}
字段
联合字段 value。类型值字段。value 只能是下列其中一项：
boolValue

boolean

布尔值：true 或 false。
int64Value

string (int64 format)

64 位整数。其范围约为 ±9.2x1018。
doubleValue

number

64 位双精度浮点数。其数量级约为 ±10±300，并具有 16 位有效数字的精度。
stringValue

string

长度可变的字符串值。
distributionValue

object (Distribution)

分布值。

分布

JSON 表示法 
{
  "count": string,
  "mean": number,
  "sumOfSquaredDeviation": number,
  "range": {
    object (Range)
  },
  "bucketOptions": {
    object (BucketOptions)
  },
  "bucketCounts": [
    string
  ],
  "exemplars": [
    {
      object (Exemplar)
    }
  ]
}
字段
count

string (int64 format)

总体中值的数量。必须为非负数。 如果提供了直方图，则此值必须等于 bucket_counts 中的值之和。
mean

number

总体中值的算术平均值。如果 count 为零，则此字段必须为零。
sumOfSquaredDeviation

number

总体中各值与平均值的平方差之和。对于值 x_i，方法为：

Sum[i=1..n]((x_i - mean)^2)

Knuth 的《计算机程序设计艺术》第 2 卷第 232 页（第 3 版）介绍了 Welford 的方法，该方法可在一次遍历中累积此总和。

如果 count 为零，则此字段必须为零。
range

object (Range)

如果指定，则包含总体值的范围。如果数量为零，则不得包含此字段。Cloud Monitoring API v3 目前会忽略此字段。
bucketOptions

object (BucketOptions)

在 Cloud Monitoring API v3 中是必需的。用于定义直方图分桶边界。
bucketCounts[]

string (int64 format)

在 Cloud Monitoring API v3 中是必需的。bucket_options 中指定的每个分桶的值。bucketCounts 中各值的总和必须等于 Distribution 对象的 count 字段中的值。分桶计数的顺序遵循针对三种分桶类型描述的编号方案。下溢分桶的编号为 0；有限分桶（如果有）的编号为 1 到 N-2；上溢分桶的编号为 N-1。bucket_counts 的大小不得大于 N。如果大小小于 N，则剩余的桶会被分配零值。
exemplars[]

object (Exemplar)

必须按 value 字段以递增顺序排列。

范围

JSON 表示法 
{
  "min": number,
  "max": number
}
字段
min

number

总体值的最小值。
max

number

总体值的最大值。

BucketOptions

JSON 表示法 
{

  // Union field options can be only one of the following:
  "linearBuckets": {
    object (Linear)
  },
  "exponentialBuckets": {
    object (Exponential)
  },
  "explicitBuckets": {
    object (Explicit)
  }
  // End of list of possible types for union field options.
}
字段
联合字段 options。以下三个字段中，必须且只能设置一个。options 只能是下列其中一项：
linearBuckets

object (Linear)

线性分桶。
exponentialBuckets

object (Exponential)

指数分桶。
explicitBuckets

object (Explicit)

显式分桶。

线性

JSON 表示法 
{
  "numFiniteBuckets": integer,
  "width": number,
  "offset": number
}
字段
numFiniteBuckets

integer

必须大于 0。
width

number

必须大于 0。
offset

number

第一个分桶的下限。

指数

JSON 表示法 
{
  "numFiniteBuckets": integer,
  "growthFactor": number,
  "scale": number
}
字段
numFiniteBuckets

integer

必须大于 0。
growthFactor

number

必须大于 1。
scale

number

必须大于 0。

显式

JSON 表示法 
{
  "bounds": [
    number
  ]
}
字段
bounds[]

number

值必须单调递增。

Exemplar

JSON 表示法 
{
  "value": number,
  "timestamp": string,
  "attachments": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
value

number

范例点的值。此值用于确定范例属于哪个分桶。
timestamp

string (Timestamp format)

上述值的观测（采样）时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
attachments[]

object

有关示例值的上下文信息。示例包括：

跟踪记录：type.googleapis.com/google.monitoring.v3.SpanContext

字面量字符串：type.googleapis.com/google.protobuf.StringValue

在汇总期间丢弃的标签：type.googleapis.com/google.monitoring.v3.DroppedLabels

一个范例中只能包含一个指定消息类型的附件，这是由系统强制执行的。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

不限

JSON 表示法 
{
  "typeUrl": string,
  "value": string
}
字段
typeUrl

string

通过 URI 引用（由以斜杠结尾的前缀和完全限定的类型名称组成）标识序列化 Protobuf 消息的类型。

示例：type.googleapis.com/google.protobuf.StringValue

此字符串必须包含至少一个 / 字符，并且最后一个 / 后面的内容必须是规范形式的完全限定类型名称，不带前导点。请勿在这些 URI 引用中写入方案，以免客户端尝试联系它们。

前缀是任意的，Protobuf 实现应仅剥离最后一个 / 之前（包括最后一个 /）的所有内容，以标识类型。type.googleapis.com/ 是某些旧版实现所需的常见默认前缀。此前缀不指示类型的来源，包含此前缀的 URI 不应响应任何请求。

所有类型网址字符串都必须是合法的 URI 引用，并且（对于文本格式）还必须满足以下额外限制：引用的内容只能包含字母数字字符、百分号编码的转义字符以及以下集合中的字符（不包括外侧的反引号）：/-.~_!$&()*+,;=。尽管我们允许使用百分比编码，但实现不应对其进行转义，以免与现有解析器混淆。例如，应拒绝 type.googleapis.com%2FFoo。

在 Any 的原始设计中，曾考虑过在这些类型网址上启动类型解析服务的可能性，但 Protobuf 从未实现过此类服务，并且认为联系这些网址存在问题，可能会导致安全问题。请勿尝试联系类型网址。
value

string (bytes format)

包含由 type_url 描述的类型的 Protobuf 序列化。

使用 base64 编码的字符串。

状态

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
code

integer

状态代码，应为 google.rpc.Code 的枚举值。
message

string

面向开发者的错误消息（应采用英语）。任何向用户显示的错误消息都应进行本地化并通过 google.rpc.Status.details 字段发送，或者由客户端进行本地化。
details[]

object

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。

可以包含任意类型字段的对象。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

NullValue

表示 JSON null。

NullValue 是一个标记，使用仅包含一个值的枚举来表示 Value 类型联合的 null 值。

如果类型为 NullValue 的字段的值不是 0，则视为无效。大多数 ProtoJSON 序列化程序都会发出一个 Value，并将 null_value 设置为 JSON null，无论整数值是多少，因此都会往返于 0 值。

枚举
NULL_VALUE Null 值。

MetricKind

测量种类。它描述了如何报告数据。 如需了解如何根据 MetricKind 设置开始时间和结束时间，请参阅 TimeInterval。

枚举
METRIC_KIND_UNSPECIFIED 请勿使用此默认值。
GAUGE 值的瞬时测量。
DELTA 某个时间间隔内值的变化。
CUMULATIVE 某个时间间隔内累积的值。时间序列中的累积测量应具有相同的开始时间和递增的结束时间，直到某个事件将累积值重置为零并为后续的点设置新的开始时间为止。

ValueType

指标的值类型。

枚举
VALUE_TYPE_UNSPECIFIED 请勿使用此默认值。
BOOL 该值是布尔值。仅当指标种类是 GAUGE 时，才能使用此值类型。
INT64 该值是有符号的 64 位整数。
DOUBLE 该值是双精度浮点数。
STRING 该值是文本字符串。仅当指标种类是 GAUGE 时，才能使用此值类型。
DISTRIBUTION 该值为 Distribution。
MONEY 该值是金额。

工具注释

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌