3. LogQL 基础语法速览：日志流选择器、行过滤器、标签过滤器、管道阶段

LogQL 是 Loki 的专用查询语言，语法上受 PromQL 和 SQL 启发，但专为日志数据设计。理解 LogQL 的四个核心构成——日志流选择器、行过滤器、标签过滤器和管道阶段——是编写高效查询、降低查询延迟和资源消耗的基础。

3.1 日志流选择器（Log Stream Selector）

日志流选择器是 LogQL 查询的第一段，用于从 Loki 中筛选出特定的日志流。它通过花括号 {} 包裹一组标签键值对来定义，语法与 PromQL 的标签匹配器完全一致。

3.2 行过滤器（Line Filter）

行过滤器紧跟在日志流选择器之后，使用管道符 | 连接，用于对日志行内容进行快速文本匹配。行过滤器不解析日志结构，只做子串或正则匹配，是 LogQL 中最高效的过滤手段。

{job="nginx"} |= "ERROR"          // 包含子串 "ERROR"
{job="nginx"} != "healthcheck"     // 不包含子串 "healthcheck"
{job="nginx"} |~ "5[0-9][0-9]"    // 正则匹配 5xx 状态码
{job="nginx"} !~ "GET /static/"   // 正则排除静态资源请求

3.3 标签过滤器（Label Filter）

标签过滤器用于对日志流中已提取的标签进行数值或字符串比较。它通常出现在管道阶段中，使用 | 连接，语法类似 PromQL 的比较操作。

{job="api-server"} | logfmt | status >= 500 | duration > 2.0

3.4 管道阶段（Pipeline Stage）

管道阶段是 LogQL 中最灵活、最强大的部分，允许对日志行进行解析、提取、转换、过滤和聚合。每个阶段通过 | 串联，形成一条处理流水线。

3.4.1 常用管道阶段一览

3.4.2 管道阶段串联示例

{job="gateway"} 
| json 
| status >= 400 
| line_format "{{.method}} {{.path}} -> {{.status}}" 
| label_format method_upper="{{.method | upper}}"

上述查询的执行流程：

1. 日志流选择器：只查询 job="gateway" 的日志流。
2. 行过滤器：无（此处省略，但可前置添加 |= "ERROR" 加速）。
3. JSON 解析器：将每行 JSON 日志解析为结构化标签。
4. 标签过滤器：只保留 status >= 400 的日志行。
5. 行格式化：将日志行内容重写为更简洁的格式。
6. 标签格式化：将 method 标签转为大写并重命名。

3.5 LogQL 查询结构总览

下图展示了 LogQL 查询的完整结构，从日志流选择到最终输出，每个阶段都可以按需组合。

3.6 查询优化黄金法则

• 先窄后宽：先用日志流选择器缩小范围，再用行过滤器快速排除无关行，最后用解析器和标签过滤器做精细处理。
• 避免过度解析：如果只需要简单的子串匹配，不要使用 | json 或 | regexp，行过滤器效率高得多。
• 标签基数控制：不要在管道阶段中动态创建高基数标签（如 trace_id、user_ip），会导致索引膨胀和查询变慢。
• 使用 rate 而非 count_over_time：在指标查询中，rate 能自动处理计数器重置，且计算效率更高。