MCP Tools Reference: clouderrorreporting.googleapis.com

工具：list_group_stats

请仅使用此工具查找和分析应用中重复出现的堆栈轨迹。它会汇总类似的堆栈轨迹，并提供发生次数和受影响的用户数量等统计信息。请勿使用此工具进行常规错误搜索或查看单个错误日志。对于要求“查找错误”或“显示错误”的查询，您必须使用 list_log_entries 工具。严重：对于有关错误的常规问题，默认使用其他工具。

以下代码示例展示了如何使用 curl 调用 list_group_stats MCP 工具。

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

输入架构

指定要返回的一组 ErrorGroupStats。

下一个 ID：19

ListGroupStatsRequest

JSON 表示法 
{
  "projectName": string,
  "groupId": [
    string
  ],
  "serviceFilter": {
    object (ServiceContextFilter)
  },
  "timeRange": {
    object (QueryTimeRange)
  },
  "timedCountDuration": string,
  "alignment": enum (TimedCountAlignment),
  "alignmentTime": string,
  "order": enum (ErrorGroupOrder),
  "pageSize": integer,
  "pageToken": string
}
字段
projectName

string

必需。Google Cloud Platform 项目的资源名称。以 projects/{projectID} 或 projects/{projectNumber} 的形式写入，其中 {projectID} 和 {projectNumber} 可在 Google Cloud 控制台中找到。它还可以包含位置信息，例如 projects/{projectID}/locations/{location}，其中 {location} 是云区域。

示例：projects/my-project-123、projects/5551234、projects/my-project-123/locations/us-central1、projects/5551234/locations/us-central1。

如需查看支持的位置列表，请参阅支持的区域。如果未指定，则默认值为 global。使用 - 作为通配符，请求所有区域的群组统计信息。
groupId[]

string

可选。列出具有这些 ID 的所有 ErrorGroupStats。group_id 是特定错误组的唯一标识符。该标识符源自错误日志内容的关键部分，并被视为服务数据。如需了解服务数据的处理方式，请参阅 Google Cloud 隐私权声明。
serviceFilter

object (ServiceContextFilter)

可选。仅列出属于与过滤条件匹配的服务上下文的 ErrorGroupStats。如果未指定此字段，则返回所有服务上下文的数据。
timeRange

object (QueryTimeRange)

可选。列出指定时间范围内的数据。如果未设置，系统将使用默认时间范围。响应中的 time_range_begin 字段将指定此时间范围的开始时间。系统只会返回指定时间范围内数量不为零的 ErrorGroupStats，除非请求包含明确的 group_id 列表。如果提供的是 group_id 列表，则还会返回出现次数为零的 ErrorGroupStats。
timedCountDuration

string (Duration format)

可选。单个返回的 TimedCount 的首选时长。如果未设置，则不返回任何定时计数。

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

enum (TimedCountAlignment)

可选。要返回的定时统计信息的对齐方式。默认值为 ALIGNMENT_EQUAL_AT_END。
alignmentTime

string (Timestamp format)

可选。如果选择舍入对齐，则时间计数应与之对齐。默认值为 00:00 UTC。

采用 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"。
order

enum (ErrorGroupOrder)

可选。返回结果的排序顺序。默认值为 COUNT_DESC。
pageSize

integer

可选。每个响应返回的结果数上限。默认值为 20。
pageToken

string

可选。之前响应提供的 next_page_token。如需查看更多结果，请传递此令牌，并使用与第一个请求相同的查询参数。

ServiceContextFilter

JSON 表示法 
{
  "service": string,
  "version": string,
  "resourceType": string
}
字段
service

string

可选。要与 ServiceContext.service 进行匹配的确切值。
version

string

可选。要与 ServiceContext.version 进行匹配的确切值。
resourceType

string

可选。要与 ServiceContext.resource_type 进行匹配的确切值。

QueryTimeRange

JSON 表示法 
{
  "period": enum (Period)
}
字段
period

enum (Period)

将查询限制为指定的时间范围。

时长

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

string (int64 format)

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

integer

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

时间戳

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 之间（含边界值）。

时段

支持的时间范围。

枚举
PERIOD_UNSPECIFIED 请勿使用。
PERIOD_1_HOUR 检索过去一小时的数据。建议的最短定时数数时长：1 分钟。
PERIOD_6_HOURS 检索过去 6 小时的数据。建议的最短定时数数时长：10 分钟。
PERIOD_1_DAY 检索过去一天的数据。建议的最短定时计数时长：1 小时。
PERIOD_1_WEEK 检索上周的数据。建议的最短定时计数时长：6 小时。
PERIOD_30_DAYS 检索过去 30 天的数据。建议的最短定时计数时长：1 天。

TimedCountAlignment

指定如何对齐错误组计数的各个时间段。

枚举
ERROR_COUNT_ALIGNMENT_UNSPECIFIED 未指定对齐方式。
ALIGNMENT_EQUAL_ROUNDED

时间段应是连续的，宽度应等于请求的时长，并且应与请求中提供的 alignment_time 对齐。

alignment_time 不必位于查询时段内，但即使位于查询时段外，也只会返回与查询时段重叠的时段。

舍入对齐通常会导致第一个或最后一个时间段的大小不同。
ALIGNMENT_EQUAL_AT_END 时间段应是连续的，宽度等于所请求的时长，并且在所请求的时间段结束时对齐。这可能会导致第一个时间段的大小不同。

ErrorGroupOrder

错误组的排序顺序。

枚举
GROUP_ORDER_UNSPECIFIED 未指定任何组顺序。
COUNT_DESC 指定时间窗口内的错误总数（按降序排列）。
LAST_SEEN_DESC 相应群组在指定时间窗口内最后一次出现的时间戳（按降序排列）。
CREATED_DESC 群组的创建时间戳（按降序排列）。
AFFECTED_USERS_DESC 指定时间范围内受影响的用户数（按降序排列）。

输出架构

包含一组请求的错误组统计信息。

ListGroupStatsResponse

JSON 表示法 
{
  "errorGroupStats": [
    {
      object (ErrorGroupStats)
    }
  ],
  "nextPageToken": string,
  "timeRangeBegin": string
}
字段
errorGroupStats[]

object (ErrorGroupStats)

与指定请求匹配的错误组统计信息。
nextPageToken

string

如果非空，则表示有更多结果。传递此令牌以及与第一个请求相同的查询参数，即可查看下一页结果。
timeRangeBegin

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"。

ErrorGroupStats

JSON 表示法 
{
  "group": {
    object (ErrorGroup)
  },
  "count": string,
  "affectedUsersCount": string,
  "timedCounts": [
    {
      object (TimedCount)
    }
  ],
  "firstSeenTime": string,
  "lastSeenTime": string,
  "affectedServices": [
    {
      object (ServiceContext)
    }
  ],
  "numAffectedServices": integer,
  "representative": {
    object (ErrorEvent)
  }
}
字段
group

object (ErrorGroup)

对独立于过滤条件的数据进行分组。
count

string (int64 format)

指定组中与过滤条件匹配的事件的大致总数。
affectedUsersCount

string (int64 format)

相应群组中符合过滤条件的大致受影响用户数。用户通过各个错误事件的 ErrorContext 中的数据来区分，例如登录名或 HTTP 请求中的远程 IP 地址。即使错误数量不为零，受影响的用户数也可能为零，前提是没有提供可用于推断受影响用户的数据。用户数量是根据错误报告中提供的请求上下文中的数据计算得出的。如果更多用户受到隐式影响（例如，由于整个服务崩溃），则此处不会反映出来。
timedCounts[]

object (TimedCount)

一段时间内的大致出现次数。ListGroups 返回的定时计数保证为：

  • 在请求的时间间隔内
  • 不重叠，并且
  • 按时间升序排列。
firstSeenTime

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"。
lastSeenTime

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"。
affectedServices[]

object (ServiceContext)

在给定过滤条件下的错误数不为零的服务上下文。如果多个服务受到影响，此列表可能会被截断。如需了解总数，请参阅 num_affected_services。
numAffectedServices

integer

在给定过滤条件下，错误计数不为零的服务总数。
representative

object (ErrorEvent)

被选为整个群组的代表的任意事件。代表性活动旨在用作整个群组的快速预览。组中的事件通常彼此足够相似，因此显示任意代表性事件都能让您了解整个组的特征。

ErrorGroup

JSON 表示法 
{
  "name": string,
  "groupId": string,
  "trackingIssues": [
    {
      object (TrackingIssue)
    }
  ],
  "resolutionStatus": enum (ResolutionStatus)
}
字段
name

string

群组资源名称。写为 projects/{projectID}/groups/{group_id} 或 projects/{projectID}/locations/{location}/groups/{group_id}

示例：projects/my-project-123/groups/my-group、projects/my-project-123/locations/us-central1/groups/my-group

在群组资源名称中，group_id 是特定错误群组的唯一标识符。该标识符源自错误日志内容的关键部分，并被视为服务数据。如需了解服务数据的处理方式，请参阅 Google Cloud 隐私权声明。

如需查看支持的位置列表，请参阅支持的区域。如果未指定，则默认值为 global。
groupId

string

群组的不透明标识符。此字段由 Error Reporting (与 Stackdriver 搭配使用时) 系统分配，并且始终填充。

在群组资源名称中，group_id 是特定错误群组的唯一标识符。该标识符源自错误日志内容的关键部分，并被视为服务数据。如需了解服务数据的处理方式，请参阅 Google Cloud 隐私权声明。
trackingIssues[]

object (TrackingIssue)

相关跟踪问题。
resolutionStatus

enum (ResolutionStatus)

错误组的解决状态。

未指定的解决状态将被解读为“开放”

TrackingIssue

JSON 表示法 
{
  "url": string
}
字段
url

string

指向问题跟踪系统中相关条目的网址。示例：https://github.com/user/project/issues/4

TimedCount

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

string (int64 format)

指定时间段内的大致出现次数。
startTime

string (Timestamp format)

count 所指时间段的开始时间（含）。

采用 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"。
endTime

string (Timestamp format)

count 所指时间段的结束时间（不含）。

采用 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 之间（含边界值）。

ServiceContext

JSON 表示法 
{
  "service": string,
  "version": string,
  "resourceType": string
}
字段
service

string

服务的标识符，例如可执行文件、作业或 Google App Engine 服务的名称。与 version 不同，此字段的值数量预计较少，并且会随着时间的推移保持相对稳定，而可以在每次部署新代码时进行更改。

包含从 Google App Engine 日志中提取的错误报告的服务名称，如果使用 App Engine 默认服务，则为 default。
version

string

表示开发者提供的源代码版本，例如版本标签或 Git SHA-1 哈希。对于 App Engine 标准环境，版本设置为应用的相应版本。
resourceType

string

MonitoredResource 的类型。可能的值的列表：https://cloud.google.com/monitoring/api/resources

系统会自动为传入的错误设置值，报告错误时不得设置该值。

ErrorEvent

JSON 表示法 
{
  "eventTime": string,
  "serviceContext": {
    object (ServiceContext)
  },
  "message": string,
  "context": {
    object (ErrorContext)
  }
}
字段
eventTime

string (Timestamp format)

错误报告中提供的事件发生时间。如果报告不包含时间戳，则使用 Error Reporting (when used with Stackdriver) 系统收到错误的时间。

采用 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"。
serviceContext

object (ServiceContext)

报告此错误的 ServiceContext。
message

string

服务报告或记录的堆栈轨迹。
context

object (ErrorContext)

有关发生错误的上下文的数据。

ErrorContext

JSON 表示法 
{
  "httpRequest": {
    object (HttpRequestContext)
  },
  "user": string,
  "reportLocation": {
    object (SourceLocation)
  },
  "sourceReferences": [
    {
      object (SourceReference)
    }
  ]
}
字段
httpRequest

object (HttpRequestContext)

触发错误时处理的 HTTP 请求。
user

string

造成崩溃或受崩溃影响的用户。它可以是用户 ID、电子邮件地址，也可以是唯一标识用户的任意令牌。发送错误报告时，如果用户未登录，请将此字段留空。在这种情况下，Error Reporting 系统将使用其他数据（例如远程 IP 地址）来区分受影响的用户。请参阅 ErrorGroupStats 中的 affected_users_count。
reportLocation

object (SourceLocation)

源代码中作出报告错误决定的位置，通常是记录错误的位置。对于记录的异常，它将是记录异常的源行，通常靠近捕获异常的位置。
sourceReferences[]

object (SourceReference)

用于构建导致出现指定错误消息的可执行文件的源代码。

HttpRequestContext

JSON 表示法 
{
  "method": string,
  "url": string,
  "userAgent": string,
  "referrer": string,
  "responseStatusCode": integer,
  "remoteIp": string
}
字段
method

string

HTTP 请求的类型，例如 GET、POST 等。
url

string

请求的网址。
userAgent

string

随请求提供的用户代理信息。
referrer

string

随请求提供的引荐来源信息。
responseStatusCode

integer

请求的 HTTP 响应状态代码。
remoteIp

string

发出请求的 IP 地址。它可以是 IPv4、IPv6，也可以是从 IP 地址派生的令牌，具体取决于错误报告中提供的数据。

SourceLocation

JSON 表示法 
{
  "filePath": string,
  "lineNumber": integer,
  "functionName": string
}
字段
filePath

string

源代码文件名，可以包含截断的相对路径，也可以是从生产机器开始的完整路径。
lineNumber

integer

从 1 开始。0 表示未知行号。
functionName

string

函数或方法的人类可读名称。该值可以包含可选上下文，如类或软件包名称。例如，如果使用的是 Java，则为 my.package.MyClass.method。

SourceReference

JSON 表示法 
{
  "repository": string,
  "revisionId": string
}
字段
repository

string

可选。用于标识代码库的 URI 字符串。示例：“https://github.com/GoogleCloudPlatform/kubernetes.git”
revisionId

string

已部署修订版本的规范且持久的标识符。示例 (git)："0035781c50ec7aa23385dc841529ce8a4b70db1b"

ResolutionStatus

错误组的解决状态。

枚举
RESOLUTION_STATUS_UNSPECIFIED 状态未知。如果在请求中未指定，则视为 OPEN。
OPEN 相应错误组未得到处理。这是新群组的默认设置。它还用于标记为“已解决”后再次出现的错误。
ACKNOWLEDGED 手动确认的错误组，可以附加问题链接。
RESOLVED 错误组已手动解决，预计不会再出现此组的更多事件。
MUTED 在群组统计信息请求中，错误组默认处于静音状态并被排除。

工具注释

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