cloud-logging-query-generation

生成 Logging Query Language 查询

使用此技能为 Cloud Logging 生成正确的 Logging Query Language（LQL）查询。

署名

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须先阅读 使用署名。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中），请在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-logging-query-generation)" ，并在 User-Agent 标头中追加 agent-skills/1.0 (skill:cloud-logging-query-generation)。

核心规则

1. 严格的语法要求：

   • 字符串字面量始终使用双引号（"）。不要使用单引号（'）。
   • 布尔运算符一律使用大写：AND、OR、NOT。
   • 始终使用括号对表达式分组，并明确指定优先级。

2. 常见问题：

   • 实例 ID 与实例名称： 对于 gce_instance 资源类型，不要将实例名称与实例 ID 比较。实例名称是字符串（例如 my-instance），实例 ID 是数字。如果只有实例名称，请按实例名称搜索：SEARCH("my-instance")；或者，如果该资源提供 resource.labels.instance_name 标签，则使用该标签。
   • 资源类型准确性： 不要猜测资源类型。必须在特定服务的参考文件中查找正确的 resource.type 值。例如，按转发规则名称或区域过滤内部 HTTP(S) 负载均衡器规则时，应使用 internal_http_lb_rule，而不是 http_load_balancer。

3. 输出格式和占位符：

   • 只输出原始 LQL 查询文本。不要添加对话中的填充内容。除非用户明确要求，否则不要将查询放入 Markdown 代码块中。允许使用有效的 LQL 注释（使用 --），且这是唯一可用于添加说明或警告的方式。
   • 绝不要因缺少变量而中断。 如果用户的请求缺少特定标识符（例如项目 ID、实例名称或 IP 地址），不要要求用户澄清。如果变量是查询有效运行所必需的（例如区域日志所需的日志存储桶名称），请插入用尖括号括起来的大写占位符字符串（例如 "<PROJECT_ID>"）。重要提示：如果为用户未提供的变量添加占位符，它会成为明确的过滤条件，导致部分日志被漏掉。因此，如果字段并非严格必需，必须省略包含占位符的整个过滤条件或行。例如，如果用户未指定实例，必须完全省略 resource.labels.instance_id="..."；但如果要构造区域日志存储桶查询，而项目 ID 是必需的，则必须在 logName=".../projects/<PROJECT_ID>/..." 中包含占位符。

4. 首选字段：

   • 如果查询针对特定的 Google Cloud 服务或资源，请添加 resource.type 和 log_id 限制。全局查询（例如“最新错误日志”）无需添加这些限制。

详细参考

关于 LQL 语法规则（包括运算符、NULL 处理、SEARCH 和 Regex），请参阅 references/api_reference.md。

服务参考文件

生成查询之前，必须先阅读对应服务的示例。 LQL 架构和 resource.type 值因服务而异。找到文件中的 Base Schema 后，不要停止阅读。必须确认架构块下方的段落或具体查询示例中，是否详细说明了状态跟踪（例如 previousState）或特定资源的日志 ID 要求。

对于以下服务，请阅读所列的确切文件：

• App Engine
• BigQuery
• Cloud Deployment Manager
• Cloud Functions
• Cloud Observability（Monitoring、Logging、Trace）
• Cloud Run
• Cloud Source Repositories
• Cloud Spanner
• Cloud SQL
• Cloud Storage
• Cloud Tasks
• Compute Engine（GCE）
• Dataflow
• Dataproc
• Kubernetes Engine（GKE）
• IAM 和 Service Accounts
• Networking（VPC、Load Balancing 等）
• Security（审计日志）
• Service Usage（启用/停用 API、配额）
• Third Party（例如 Nginx、Apache）

对于未列出的 Google Cloud 服务： 如果服务未列在上方，请根据你的常识编写 LQL 查询。

查询生成规则

1. 资源类型： 针对特定服务编写查询时，请明确指定 resource.type。某些查询可能需要跨多个类型搜索（例如 resource.type=("bigquery_project" OR "bigquery_dataset")）。
2. 审计日志和管理日志： 如果用户请求审计日志、管理日志、API 日志，或有关谁创建、更新、删除、读取或访问了某项资源的日志：
   • 必须阅读 references/query_audit_logs.md，了解正确的 protoPayload 架构路径和常见示例。
   • 如果其中未列出具体示例，请结合服务和动词猜测 protoPayload.methodName。猜测时，必须使用范围限定的 SEARCH() 函数（例如 SEARCH(protoPayload.methodName, "compute.instances.insert")），而不是精确匹配运算符（=），以避免版本前缀不匹配。请勿使用冒号运算符（:），因为它可能造成子串误匹配。
   • 对于通用 API 启用/停用事件（例如某项服务被停用），始终使用 resource.type="audited_resource"。
3. 处理未知架构（至关重要）： 如果用户要求按特定字段或条件进行过滤，而你在参考文件中找不到匹配的示例或架构，则必须使用全局搜索生成查询。
   • 只有在确定字段的确切名称时，才指定 jsonPayload.* 或 protoPayload.* 字段结构。
   • 使用 SEARCH() 函数在正确的 resource.type 中全局搜索关键字。
   • 必须添加 LQL 注释： 返回使用 SEARCH 的查询时，必须在查询顶部添加 LQL 注释（使用 --），说明由于参考资料中没有确切架构，因此使用了全局关键字搜索。请勿输出对话内容，严格遵守输出格式规则。

相关链接

• Cloud Logging 查询语言文档
• 监控资源类型目录
• Cloud Logging 查询库