cloud-logging-query-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Logging Query Language queries

生成Logging Query Language查询语句

Use this skill to generate correct Logging Query Language (LQL) queries for Cloud Logging.

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

Core rules

核心规则

Strict syntax requirements:
- Always use double quotes (
  "
  ) for string literals. Do not use single quotes (
```
'
```
  ).
- Write boolean operators in all capitals:
```
AND
```
  ,
```
OR
```
  ,
```
NOT
```
  .
- Always use parentheses to group terms and explicitly enforce precedence.
Common pitfalls:
- Instance ID vs. Instance Name: For the
```
gce_instance
```
  resource type, do NOT compare instance names to instance IDs. Instance names are strings (for example,
```
my-instance
```
  ). Instance IDs are numeric. If you only have the name, then search by instance name,
```
SEARCH("my-instance")
```
  , or use
```
resource.labels.instance_name
```
  if that label is available for the resource.
- Resource Type Accuracy: Do not guess resource types. You must look up the correct
```
resource.type
```
  value in the service-specific reference files. For example, use
```
internal_http_lb_rule
```
  for Internal HTTP(S) Load Balancer rules when filtering by forwarding rule name or region (instead of
```
http_load_balancer
```
  ).
Output format and placeholders:
- Output only the raw LQL query text. Do not include conversational filler. Do not wrap the query in markdown code blocks unless explicitly requested by the user. Valid LQL comments (using
```
--
```
  ) are allowed, and are the ONLY acceptable way to include explanations or warnings.
- Never block on missing variables. If the user's request lacks specific identifiers (like a project ID, instance name, or IP address), do not ask them for clarification. Instead, insert uppercase placeholder strings wrapped in angle brackets (for example,
```
"<PROJECT_ID>"
```
  ,
```
"<YOUR_SERVICE_NAME>"
```
  ) directly into the query.
Preferred fields:
- Include
```
resource.type
```
  and
```
log_id
```
  restrictions when the query targets specific Google Cloud services or resources. Global queries (for example, "latest error logs") do not require these restrictions.

严格的语法要求：
- 字符串字面量必须使用双引号（
  "
  ），不得使用单引号（
```
'
```
  ）。
- 布尔运算符需全部大写：
```
AND
```
  、
```
OR
```
  、
```
NOT
```
  。
- 必须使用括号对术语进行分组，明确优先级。
常见误区：
- 实例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
```
  ）。
输出格式与占位符：
- 仅输出原始LQL查询文本，不得包含对话式填充内容。除非用户明确要求，否则请勿将查询包裹在Markdown代码块中。允许使用LQL注释（通过
```
--
```
  ），这是添加解释或警告的唯一可接受方式。
- 切勿因缺失变量而停滞： 如果用户的请求缺少特定标识符（如项目ID、实例名称或IP地址），请勿要求用户澄清。相反，直接将大写占位符字符串（例如
```
"<PROJECT_ID>"
```
  、
```
"<YOUR_SERVICE_NAME>"
```
  ）插入查询中。
推荐字段：
- 当查询针对特定Google Cloud服务或资源时，需包含
```
resource.type
```
  和
```
log_id
```
  限制条件。全局查询（例如“最新错误日志”）无需这些限制。

Detailed reference

详细参考

Refer to

references/api_reference.md

for LQL syntax rules, including Operators, NULL handling, SEARCH, and Regex.

请参考

references/api_reference.md

获取LQL语法规则，包括运算符、NULL处理、SEARCH和正则表达式相关内容。

Service reference files

服务参考文件

Before generating a query, you MUST read the examples for the specific service. LQL schemas and

resource.type

values are service-specific.

For the following services, read the exact file listed:

App Engine
BigQuery
Cloud Functions
Cloud Observability (Monitoring, Logging, Trace)
Cloud Run
Cloud Source Repositories
Cloud SQL
Cloud Storage
Cloud Tasks
Compute Engine (GCE)
Dataflow
Dataproc
Deployment Manager
Kubernetes Engine (GKE)
IAM & Service Accounts
Networking (VPC, Load Balancing, and others)
Security (Audit logging)
Service Usage (Enable/Disable API, Quotas)
Spanner
Third Party (for example, Nginx, Apache)

For Google Cloud services that aren't listed: If the service is not listed above, write the LQL query based on your general knowledge.

生成查询前，您必须阅读对应特定服务的示例。LQL模式和

resource.type

值是服务特定的。

以下服务请阅读指定文件：

App Engine
BigQuery
Cloud Functions
Cloud Observability (Monitoring, Logging, Trace)
Cloud Run
Cloud Source Repositories
Cloud SQL
Cloud Storage
Cloud Tasks
Compute Engine (GCE)
Dataflow
Dataproc
Deployment Manager
Kubernetes Engine (GKE)
IAM & Service Accounts
Networking (VPC, Load Balancing, and others)
Security (Audit logging)
Service Usage (Enable/Disable API, Quotas)
Spanner
Third Party (for example, Nginx, Apache)

对于未列出的Google Cloud服务： 如果服务未在上述列表中，请基于通用知识编写LQL查询。

Query generation rules

查询生成规则

Resource Types: Explicitly define the
```
resource.type
```
in your queries when focusing on specific services. For some queries, you may need to search across multiple types (for example,
```
resource.type=("bigquery_project" OR "bigquery_dataset")
```
).
Audit and admin logs: Google Cloud Audit logs (Admin Activity, Data Access) always follow a standard structure inside
```
protoPayload
```
. If the user asks for logs about who created, updated, or deleted a resource, or an API being called:
- Do NOT fall back to
```
SEARCH()
```
  . Instead, use
```
protoPayload.methodName
```
  .
- Construct the method name by guessing the service and the verb. Example:
```
protoPayload.methodName:"compute.instances.insert"
```
  .
- Always use the colon operator (
  :
  ) instead of equals (
```
=
```
  ) for
```
methodName
```
  . The colon operator results in substring matching, which is the only feasible option when the exact API string isn't known.
- For generic API enable/disable events, use
```
resource.type="audited_resource"
```
  .
Handling Unknown Schemas (Crucial): If the user asks to filter by a specific field or condition, and if you cannot find a matching example or schema in the reference files, then you must generate a query using global search.
- Only specify
```
jsonPayload.*
```
  or
```
protoPayload.*
```
  field structures when you are certain of their exact name.
- Use the
```
SEARCH()
```
  function to find the keyword globally within the correct
```
resource.type
```
  .
- Agent Prompt to User: When delivering a query that uses
```
SEARCH
```
  , you MUST add an LQL comment (using
```
--
```
  ) at the top of the query indicating you used a global keyword search because the exact schema wasn't in your references. Do NOT output conversational text, strictly adhere to the Output Format rule.

资源类型： 当聚焦特定服务时，需在查询中明确定义
```
resource.type
```
。部分查询可能需要跨多种类型搜索（例如
```
resource.type=("bigquery_project" OR "bigquery_dataset")
```
）。
审计与管理日志： Google Cloud审计日志（管理活动、数据访问）在
```
protoPayload
```
内始终遵循标准结构。如果用户询问关于谁创建、更新或删除资源，或调用API的日志：
- 请勿退而使用
```
SEARCH()
```
  ，而是使用
```
protoPayload.methodName
```
  。
- 通过猜测服务和动词构造方法名称。示例：
```
protoPayload.methodName:"compute.instances.insert"
```
  。
- **必须使用冒号运算符（
```
:
```
  ）**而非等号（
```
=
```
  ）来匹配
```
methodName
```
  。冒号运算符会进行子字符串匹配，这是在未知确切API字符串时唯一可行的选项。
- 对于通用API启用/禁用事件，使用
```
resource.type="audited_resource"
```
  。
处理未知模式（关键）： 如果用户要求按特定字段或条件过滤，且您在参考文件中找不到匹配的示例或模式，则必须使用全局搜索生成查询。
- 仅当您确定
```
jsonPayload.*
```
  或
```
protoPayload.*
```
  字段结构的确切名称时，才指定这些结构。
- 使用
```
SEARCH()
```
  函数在正确的
```
resource.type
```
  内全局查找关键字。
- Agent给用户的提示： 当交付使用
```
SEARCH
```
  的查询时，必须在查询顶部添加LQL注释（通过
```
--
```
  ），说明由于参考文件中没有确切模式，您使用了全局关键字搜索。请勿输出对话式文本，严格遵守输出格式规则。