cloud-monitoring-list-time-series-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Monitoring ListTimeSeries Request Generator

Cloud Monitoring ListTimeSeries 请求生成器

Use this skill to translate any Cloud Monitoring metric descriptor into valid, production-ready

ListTimeSeries

REST API query parameters (

name

filter

interval.startTime

interval.endTime

aggregation.*

view

使用此技能可将任意Cloud Monitoring指标描述符转换为有效的、可用于生产环境的

ListTimeSeries

REST API查询参数（

name

、

filter

、

interval.startTime

、

interval.endTime

、

aggregation.*

、

view

）。

CRITICAL RULES

核心规则

Mandatory Project ID Clarification: You MUST ensure the GCP Project ID is present in the user prompt, input payload, or environment context (such as via
```
gcloud config get-value project
```
). If the Project ID is missing and cannot be resolved, you MUST ask the user to clarify it before generating or executing
```
ListTimeSeries
```
requests. Do NOT use placeholders for project names.

必填项目ID确认：必须确保GCP项目ID存在于用户提示、输入负载或环境上下文（例如通过
```
gcloud config get-value project
```
获取）中。如果项目ID缺失且无法确定，必须先请求用户明确提供，再生成或执行
```
ListTimeSeries
```
请求。请勿使用占位符代替项目名称。

Workflow

工作流程

Inspect Metric Metadata

检查指标元数据

Use Provided Metric Metadata First: If the user's prompt already includes metric metadata such as
```
metric.type
```
,
```
metricKind
```
,
```
valueType
```
, resource types, or label keys, use those values directly instead of calling API tools.
Discover Missing Metadata: If exact metric descriptors including
```
metric.type
```
,
```
metricKind
```
, and
```
valueType
```
are missing or underspecified, resolve the target metric's descriptor using one of these paths:
- Vague Query: If the prompt is vague, such as asking for VM CPU usage, use the
```
cloud-monitoring-metric-selection
```
  skill first to identify the specific metric type.
- Known Metric Type: If you already have the specific metric type name such as
```
compute.googleapis.com/instance/cpu/utilization
```
  , but need its descriptor, call the
```
list_metric_descriptors
```
  MCP tool. If the tool is missing, refer to the
```
cloud-monitoring-metric-selection
```
  skill to configure the Cloud Monitoring MCP server.
- Fallback: If the MCP tool cannot be configured, fall back to making a direct Cloud Monitoring API call.
Identify Key Fields: From the retrieved descriptor, identify key schema attributes:
- type
  : The Cloud Monitoring metric type string.
- metricKind
  :
```
GAUGE
```
  ,
```
DELTA
```
  , or
```
CUMULATIVE
```
  .
- valueType
  :
```
INT64
```
  ,
```
DOUBLE
```
  ,
```
DISTRIBUTION
```
  , or
```
BOOL
```
  .
- monitoredResourceTypes
  : Compatible
```
resource.type
```
  strings, for example
```
["cloudsql_database", "cloudsql_instance"]
```
  . If multiple resource types are listed, select the specific
```
resource.type
```
  that matches the target granularity of the user's request.

优先使用提供的指标元数据：如果用户提示中已包含指标元数据，如
```
metric.type
```
、
```
metricKind
```
、
```
valueType
```
、资源类型或标签键，请直接使用这些值，无需调用API工具。
发现缺失的元数据：如果缺少或未明确指定精确的指标描述符（包括
```
metric.type
```
、
```
metricKind
```
和
```
valueType
```
），请通过以下途径之一获取目标指标的描述符：
- 模糊查询：如果提示较为模糊（例如查询VM CPU使用率），请先使用
```
cloud-monitoring-metric-selection
```
  技能确定具体的指标类型。
- 已知指标类型：如果已知道具体的指标类型名称（如
```
compute.googleapis.com/instance/cpu/utilization
```
  ）但需要其描述符，请调用
```
list_metric_descriptors
```
  MCP工具。如果该工具不可用，请参考
```
cloud-monitoring-metric-selection
```
  技能配置Cloud Monitoring MCP服务器。
- 备选方案：如果无法配置MCP工具，请直接调用Cloud Monitoring API。
识别关键字段：从获取的描述符中识别关键架构属性：
- type
  ：Cloud Monitoring指标类型字符串。
- metricKind
  ：
```
GAUGE
```
  、
```
DELTA
```
  或
```
CUMULATIVE
```
  。
- valueType
  ：
```
INT64
```
  、
```
DOUBLE
```
  、
```
DISTRIBUTION
```
  或
```
BOOL
```
  。
- monitoredResourceTypes
  ：兼容的
```
resource.type
```
  字符串，例如
```
["cloudsql_database", "cloudsql_instance"]
```
  。如果列出了多个资源类型，请选择与用户请求的目标粒度匹配的特定
```
resource.type
```
  。

Construct Monitoring Filter

构建监控过滤条件

The

filter

parameter is a mandatory string in Cloud Monitoring syntax that restricts the query to a single

metric.type

and optional resource and metric labels:

Single Metric Type Restriction: Every
```
filter
```
MUST specify exactly one
```
metric.type
```
clause using an equality operator. For example:
- ```
metric.type = "compute.googleapis.com/instance/cpu/utilization"
```
Monitored Resource Type Filter: MUST include the
```
resource.type
```
filter when the target resource granularity is known, preventing collisions across services that share metric types or sub-resources. For example:
- ```
metric.type = "cloudsql.googleapis.com/database/cpu/utilization" AND resource.type = "cloudsql_database"
```
Preserve User Literals and IDs: You MUST use literal resource names, IDs, zones, and project parameters provided by the user without alteration. Do NOT override or replace user-specified identifiers with active resources found during metric metadata discovery unless explicitly requested.
Label Type Prefixing:
- Prefix resource-level dimensions, such as instance ID, zone, project, database ID, or subscription ID, with the
```
resource.labels.
```
  prefix. For example:
  - ```
  resource.labels.instance_id = "123456789"
```
- ```
resource.labels.database_id = "my-project:my-instance"
```
- Prefix metric-level dimensions, such as state, command, response code, or instance name metadata when stored on the metric, with the
```
metric.labels.
```
  prefix. For example:
  - ```
  metric.labels.state != "free"
```
- ```
metric.labels.instance_name = "instance-1"
```
Resource Name versus ID Resolution:
- If the user specifies a human-readable GCE VM instance name such as
```
"instance-1"
```
  , but
```
resource.labels.instance_id
```
  expects a numeric ID, you MUST filter using either
```
metric.labels.instance_name = "instance-1"
```
  or
```
metadata.system_labels.name = "instance-1"
```
  .
- Do NOT use
```
resource.metadata.name
```
  or
```
resource.metadata.*
```
  . This prefix is invalid in Cloud Monitoring filter syntax.
- Do NOT assign a string instance name directly to
```
resource.labels.instance_id
```
  unless the resource type explicitly uses string IDs.
Database Identifier Labels: Database labels such as
```
database_id
```
for Cloud SQL and Spanner, or
```
dataset_id
```
for BigQuery, use composite keys formatted as
```
<project_id>:<instance_name>
```
. For example:
```
resource.labels.database_id = "my-project:foo"
```
.

Ops Agent Metrics State Label Filtering: For

agent.googleapis.com/memory/percent_used

and

agent.googleapis.com/disk/percent_used

metrics, you MUST use

metric.labels.state != "free"

. Do NOT filter by

metric.labels.state = "used"

filter

参数是Cloud Monitoring语法中的必填字符串，用于将查询限制为单个

metric.type

以及可选的资源和指标标签：

单一指标类型限制：每个
```
filter
```
必须使用相等运算符指定恰好一个
```
metric.type
```
子句。例如：
- ```
metric.type = "compute.googleapis.com/instance/cpu/utilization"
```
受监控资源类型过滤：当已知目标资源粒度时，必须包含
```
resource.type
```
过滤条件，以避免跨服务共享指标类型或子资源时产生冲突。例如：
- ```
metric.type = "cloudsql.googleapis.com/database/cpu/utilization" AND resource.type = "cloudsql_database"
```
保留用户提供的字面量和ID：必须使用用户提供的字面资源名称、ID、可用区和项目参数，不得修改。除非用户明确要求，否则请勿用指标元数据发现过程中找到的活跃资源覆盖或替换用户指定的标识符。
标签类型前缀：
- 资源级维度（如实例ID、可用区、项目、数据库ID或订阅ID）需添加
```
resource.labels.
```
  前缀。例如：
  - ```
  resource.labels.instance_id = "123456789"
```
- ```
resource.labels.database_id = "my-project:my-instance"
```
- 指标级维度（如状态、命令、响应码或存储在指标中的实例名称元数据）需添加
```
metric.labels.
```
  前缀。例如：
  - ```
  metric.labels.state != "free"
```
- ```
metric.labels.instance_name = "instance-1"
```
资源名称与ID的转换：
- 如果用户指定了GCE VM实例的可读名称（如
```
"instance-1"
```
  ），但
```
resource.labels.instance_id
```
  需要数字ID，则必须使用
```
metric.labels.instance_name = "instance-1"
```
  或
```
metadata.system_labels.name = "instance-1"
```
  进行过滤。
- 请勿使用
```
resource.metadata.name
```
  或
```
resource.metadata.*
```
  。该前缀在Cloud Monitoring过滤语法中无效。
- 除非资源类型明确使用字符串ID，否则请勿将字符串实例名称直接赋值给
```
resource.labels.instance_id
```
  。
数据库标识符标签：数据库标签（如Cloud SQL和Spanner的
```
database_id
```
，或BigQuery的
```
dataset_id
```
）使用复合键，格式为
```
<project_id>:<instance_name>
```
。例如：
```
resource.labels.database_id = "my-project:foo"
```
。

Ops Agent指标状态标签过滤：对于

agent.googleapis.com/memory/percent_used

和

agent.googleapis.com/disk/percent_used

指标，必须使用

metric.labels.state != "free"

。请勿使用

metric.labels.state = "used"

进行过滤。

Choose Aggregation Structure

选择聚合结构

Select the

perSeriesAligner

crossSeriesReducer

groupByFields

, and

alignmentPeriod

according to the metric properties and visualization goal:

Consult the Aggregations Reference: You MUST include both
```
perSeriesAligner
```
and
```
crossSeriesReducer
```
in the
```
aggregation
```
query parameters of every request. Read and follow the Cloud Monitoring ListTimeSeries Basic Aggregations Reference to select the exact
```
perSeriesAligner
```
and
```
crossSeriesReducer
```
combinations for your metric's Metric Kind and Value Type pairing, and to apply mandatory SRE rules for utilization metrics, counters, distributions, and state-based gauges such as memory filtered by
```
state != "free"
```
.
Grouping Fields and Resource Granularity: When
```
crossSeriesReducer
```
is specified as anything other than
```
REDUCE_NONE
```
, list the exact labels to preserve. When querying multi-instance resources like VMs, databases, or subscriptions, include the primary resource identifier in
```
groupByFields
```
. For example, use
```
resource.labels.instance_id
```
for VMs or
```
resource.labels.database_id
```
for databases. This prevents collapsing separate resource streams into a single global aggregate.
Alignment Period Determination: Calculate the query lookback duration from
```
endTime
```
minus
```
startTime
```
, ensuring
```
startTime
```
precedes
```
endTime
```
. If
```
endTime <= startTime
```
, flag an error before computing duration. Set
```
alignmentPeriod
```
according to Cloud Console default fine granularity standards:
- Duration <= 110 minutes: Set
```
alignmentPeriod = "60s"
```
  .
- Duration <= 23 hours: Set
```
alignmentPeriod = "300s"
```
  .
- Duration <= 6 days: Set
```
alignmentPeriod = "3600s"
```
  .
- Duration <= 23 days: Set
```
alignmentPeriod = "10800s"
```
  .
- Duration <= 80 days: Set
```
alignmentPeriod = "21600s"
```
  .
- Duration <= 180 days: Set
```
alignmentPeriod = "43200s"
```
  .
- Duration <= 350 days: Set
```
alignmentPeriod = "86400s"
```
  .
- Duration <= 500 days: Set
```
alignmentPeriod = "172800s"
```
  .
- Omission Rule:
```
alignmentPeriod
```
  is omitted only when
```
perSeriesAligner
```
  is set to
```
ALIGN_NONE
```
  .

根据指标属性和可视化目标选择

perSeriesAligner

、

crossSeriesReducer

、

groupByFields

和

alignmentPeriod

：

参考聚合文档：每个请求的
```
aggregation
```
查询参数中必须同时包含
```
perSeriesAligner
```
和
```
crossSeriesReducer
```
。请阅读并遵循Cloud Monitoring ListTimeSeries基础聚合参考，根据指标的Metric Kind和Value Type组合选择确切的
```
perSeriesAligner
```
和
```
crossSeriesReducer
```
组合，并针对利用率指标、计数器、分布以及基于状态的仪表盘（如按
```
state != "free"
```
过滤的内存指标）应用强制性SRE规则。
分组字段与资源粒度：当
```
crossSeriesReducer
```
设置为
```
REDUCE_NONE
```
以外的值时，列出需要保留的精确标签。查询多实例资源（如VM、数据库或订阅）时，请在
```
groupByFields
```
中包含主要资源标识符。例如，对VM使用
```
resource.labels.instance_id
```
，对数据库使用
```
resource.labels.database_id
```
。这样可以避免将独立的资源流合并为单个全局聚合。
对齐周期确定：根据
```
endTime
```
减去
```
startTime
```
计算查询回溯时长，确保
```
startTime
```
早于
```
endTime
```
。如果
```
endTime <= startTime
```
，请在计算时长前标记错误。根据Cloud Console默认的精细粒度标准设置
```
alignmentPeriod
```
：
- 时长 ≤ 110分钟：设置
```
alignmentPeriod = "60s"
```
  。
- 时长 ≤ 23小时：设置
```
alignmentPeriod = "300s"
```
  。
- 时长 ≤ 6天：设置
```
alignmentPeriod = "3600s"
```
  。
- 时长 ≤ 23天：设置
```
alignmentPeriod = "10800s"
```
  。
- 时长 ≤ 80天：设置
```
alignmentPeriod = "21600s"
```
  。
- 时长 ≤ 180天：设置
```
alignmentPeriod = "43200s"
```
  。
- 时长 ≤ 350天：设置
```
alignmentPeriod = "86400s"
```
  。
- 时长 ≤ 500天：设置
```
alignmentPeriod = "172800s"
```
  。
- 省略规则：仅当
```
perSeriesAligner
```
  设置为
```
ALIGN_NONE
```
  时，才省略
```
alignmentPeriod
```
  。

Format Valid Request

格式化有效请求

Present the generated

ListTimeSeries

REST query parameters. For example:

json

{
  "name": "projects/<project_id>",
  "filter": "metric.type = \"<metric_type>\" AND resource.type = \"<resource_type>\"",
  "interval": {
    "startTime": "<iso_8601_start>",
    "endTime": "<iso_8601_end>"
  },
  "aggregation": {
    "alignmentPeriod": "60s",
    "perSeriesAligner": "ALIGN_RATE",
    "crossSeriesReducer": "REDUCE_SUM",
    "groupByFields": [
      "resource.labels.zone"
    ]
  },
  "view": "FULL"
}

Aggregation Requirements: Populate the
```
aggregation
```
parameters with the
```
perSeriesAligner
```
,
```
crossSeriesReducer
```
,
```
alignmentPeriod
```
, and optional
```
groupByFields
```
values determined during aggregation selection.
Interval Requirements:
```
startTime
```
and
```
endTime
```
MUST be valid RFC 3339 and ISO 8601 timestamps such as
```
"YYYY-MM-DDTHH:MM:SSZ"
```
. If not explicitly provided by the user, dynamically compute a one-hour lookback interval ending at the current time, where
```
endTime
```
is the present moment and
```
startTime
```
is one hour prior. Do NOT hardcode static dates from examples.
Alignment Period Requirement: Determine
```
alignmentPeriod
```
from the lookback duration of
```
endTime
```
minus
```
startTime
```
using the mapping above. For the default one-hour lookback interval,
```
alignmentPeriod
```
is
```
"60s"
```
.
View Requirement: MUST default to
```
"FULL"
```
when time series data points are needed, or
```
"HEADERS"
```
when inspecting metadata and series identities only.

展示生成的

ListTimeSeries

REST查询参数。例如：

json

{
  "name": "projects/<project_id>",
  "filter": "metric.type = \"<metric_type>\" AND resource.type = \"<resource_type>\"",
  "interval": {
    "startTime": "<iso_8601_start>",
    "endTime": "<iso_8601_end>"
  },
  "aggregation": {
    "alignmentPeriod": "60s",
    "perSeriesAligner": "ALIGN_RATE",
    "crossSeriesReducer": "REDUCE_SUM",
    "groupByFields": [
      "resource.labels.zone"
    ]
  },
  "view": "FULL"
}

聚合要求：使用聚合选择阶段确定的
```
perSeriesAligner
```
、
```
crossSeriesReducer
```
、
```
alignmentPeriod
```
和可选的
```
groupByFields
```
值填充
```
aggregation
```
参数。
时间间隔要求：
```
startTime
```
和
```
endTime
```
必须是有效的RFC 3339和ISO 8601时间戳，例如
```
"YYYY-MM-DDTHH:MM:SSZ"
```
。如果用户未明确提供，请动态计算以当前时间为结束时间的一小时回溯间隔，其中
```
endTime
```
为当前时刻，
```
startTime
```
为一小时前。请勿硬编码示例中的静态日期。
对齐周期要求：根据
```
endTime
```
减去
```
startTime
```
的回溯时长，使用上述映射确定
```
alignmentPeriod
```
。对于默认的一小时回溯间隔，
```
alignmentPeriod
```
为
```
"60s"
```
。
视图要求：当需要时间序列数据点时，必须默认设置为
```
"FULL"
```
；仅当需要检查元数据和序列标识时，设置为
```
"HEADERS"
```
。

Validate Request via REST API

通过REST API验证请求

Always validate the generated request parameters against live Cloud Monitoring telemetry before returning the final output. DO NOT call the

list_timeseries

MCP tool. Perform an HTTP GET request directly to the Cloud Monitoring v3 REST API using

curl -s -H "Authorization: Bearer \$(gcloud auth print-access-token)" -G

with

--data-urlencode

for all query fields (

name

filter

interval.startTime

interval.endTime

aggregation.alignmentPeriod

aggregation.perSeriesAligner

aggregation.crossSeriesReducer

, and

view=HEADERS

). An HTTP 200 OK response confirms that your filter and aggregation settings are valid.

在返回最终输出前，始终根据实时Cloud Monitoring遥测数据验证生成的请求参数。请勿调用

list_timeseries

MCP工具。请使用

curl -s -H "Authorization: Bearer \$(gcloud auth print-access-token)" -G

直接向Cloud Monitoring v3 REST API发送HTTP GET请求，并使用

--data-urlencode

处理所有查询字段（

name

、

filter

、

interval.startTime

、

interval.endTime

、

aggregation.alignmentPeriod

、

aggregation.perSeriesAligner

、

aggregation.crossSeriesReducer

和

view=HEADERS

）。HTTP 200 OK响应表示过滤条件和聚合设置有效。

References

参考资料

Cloud Monitoring ListTimeSeries Basic Aggregations Reference
Cloud Monitoring Monitored Resource Types Reference
Cloud Monitoring Filter Syntax
Cloud Monitoring REST API Reference: projects.timeSeries.list

Cloud Monitoring ListTimeSeries基础聚合参考
Cloud Monitoring受监控资源类型参考
Cloud Monitoring过滤语法
Cloud Monitoring REST API参考：projects.timeSeries.list