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

LogQL 是 Grafana Loki 的查询语言，语法上受 PromQL 和 SQL 启发，但专门针对日志数据设计。理解 LogQL 的核心语法是构建蓝绿发布门禁日志查询接口的基础。本章将系统讲解 LogQL 的四大核心组件：日志流选择器、行过滤器、标签过滤器以及管道阶段（Parser, Line Format, Unwrap, Label Filter）。

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

日志流选择器是 LogQL 查询的起点，用于从 Loki 中筛选出特定的日志流。它使用花括号 {} 包裹，内部包含一组键值对标签（Label）匹配条件，语法与 PromQL 的标签选择器完全一致。

在蓝绿发布场景中，通常使用 deploy_env 或 version 标签来区分蓝绿环境：

{app="order-service", deploy_env="blue"}
{app="order-service", deploy_env="green", version="v2.1.0"}

3.2 行过滤器（Line Filter）

行过滤器用于在日志流选择器的基础上，对日志行内容进行文本级别的快速过滤。它使用管道符 | 连接，支持四种操作符：

// 查询蓝色环境订单服务的所有 5xx 错误日志
{app="order-service", deploy_env="blue"} |= "ERROR" |~ "5[0-9]{2}"

// 排除健康检查日志后的所有日志
{app="api-gateway"} != "/healthz"

3.3 标签过滤器（Label Filter）

标签过滤器作用于日志流中已有的标签（包括原始标签和通过管道阶段提取的标签），支持数值和字符串的比较操作。它使用 | 连接，语法为 标签名 操作符 值。

// 查询绿色环境响应时间超过 2 秒的请求
{app="order-service", deploy_env="green"} | json | duration > 2.0

// 查询蓝色环境非 200 状态码的请求
{app="order-service", deploy_env="blue"} | json | status_code != 200

3.4 管道阶段（Pipeline Stages）

管道阶段是 LogQL 最强大的特性，允许对匹配的日志行进行解析、格式化、提取和计算。每个阶段通过 | 串联，形成处理流水线。本节重点介绍四种核心管道阶段：Parser、Line Format、Unwrap 和 Label Filter。

3.4.1 Parser 阶段

Parser 阶段将非结构化的日志行解析为结构化的标签（Label），使得后续阶段可以按字段名引用。Loki 内置了多种解析器：

// JSON 解析示例
{app="order-service"} |= "ERROR" | json
// 原始日志: {"level":"error","status":500,"path":"/api/order","duration":1.23}
// 提取标签: level="error", status=500, path="/api/order", duration=1.23

// 正则解析示例
{app="gateway"} | regexp "(?P<method>\\w+) (?P<path>[\\w/]+) (?P<status>\\d+)"
// 原始日志: POST /api/order 200
// 提取标签: method="POST", path="/api/order", status="200"

3.4.2 Line Format 阶段

Line Format 阶段用于重新格式化日志行的输出内容，常用于日志脱敏、简化显示或添加上下文信息。它使用 Go 模板语法，通过 __line__ 引用原始行，通过标签名引用解析后的字段。

// 只保留关键字段，脱敏敏感信息
{app="order-service"} | json | line_format "{{.level}} | {{.path}} | status={{.status}}"

// 原始日志: {"level":"error","status":500,"path":"/api/order","user":"john"}
// 输出: error | /api/order | status=500

// 添加固定前缀
{app="gateway"} | line_format "[BLUE-DEPLOY] {{.__line__}}"

3.4.3 Unwrap 阶段

Unwrap 阶段从标签中提取数值字段，使其可用于后续的数学运算、聚合函数（如 rate、avg、sum）或标签过滤中的数值比较。Unwrap 是连接日志查询与指标计算的桥梁。

// 计算绿色环境最近 5 分钟的平均响应时间
avg_over_time(
  {app="order-service", deploy_env="green"} | json | unwrap duration [5m]
)

// 统计蓝色环境 5xx 错误率
rate(
  {app="order-service", deploy_env="blue"} | json | status_code >= 500 [1m]
)

3.4.4 Label Filter 阶段（管道内）

在管道阶段中，Label Filter 可以基于解析后的标签值进行过滤，支持数值比较和字符串正则匹配。与日志流选择器中的标签过滤不同，管道内的 Label Filter 可以引用通过 Parser 阶段动态提取的标签。

// 管道内标签过滤完整示例
{app="order-service", deploy_env="green"}
  | json
  | status_code != 200                          // 过滤非 200 状态码
  | duration > 2.0                              // 过滤慢请求
  | line_format "{{.status_code}} | {{.duration}}s | {{.__line__}}"

3.5 综合示例：蓝绿发布门禁日志查询

将上述语法组合，构建一个完整的蓝绿发布门禁日志查询：

// 查询绿色环境最近 10 分钟的 5xx 错误率
sum(
  rate(
    {app="order-service", deploy_env="green"}
      | json
      | status_code >= 500
      | unwrap status_code
      [10m]
  )
) / sum(
  rate(
    {app="order-service", deploy_env="green"}
      | json
      | unwrap status_code
      [10m]
  )
) * 100 > 1.0

// 如果结果 > 1.0，表示错误率超过 1%，门禁应阻止流量切换

3.6 本章小结