3. LogQL v1 入门：标签匹配、行过滤器与管道解析

LogQL v1 是 Loki 的原始查询语言，其设计哲学可概括为“先缩小范围，再精确过滤”。与 PromQL 不同，LogQL 不直接操作指标，而是操作日志流。理解 LogQL v1 的三大核心构件——标签匹配器、行过滤器与管道表达式——是掌握版本漂移校准的基础，因为后续 v2/v3 的语法变更均围绕这些构件展开。

3.1 标签匹配器：缩小日志流范围

标签匹配器（Label Matchers）是 LogQL 查询的起点，用于从 Loki 的索引中筛选出特定的日志流。其语法直接继承自 PromQL，支持四种匹配操作符：

标签匹配器必须用花括号包裹，且至少包含一个匹配条件。多个条件之间用逗号分隔，逻辑关系为 AND：

{job="nginx", environment="production", method=~"GET|POST"}

上述查询仅返回同时满足三个条件的日志流。这是 LogQL 中最基础、最高效的过滤手段，因为 Loki 的倒排索引直接基于标签构建。

3.2 行过滤器：在日志内容中搜索

行过滤器（Line Filter）作用于标签匹配器筛选出的日志流内部，对日志行的文本内容进行搜索。它使用管道符 | 引入，支持四种过滤操作：

一个完整的 LogQL v1 查询通常先通过标签匹配器缩小流范围，再通过行过滤器精确匹配日志内容：

{job="api-server", namespace="prod"} |= "500" |~ "timeout|refused"

3.3 管道解析：提取与转换日志字段

管道解析（Pipeline Expressions）是 LogQL v1 中最具扩展性的部分，允许在行过滤器之后对日志行进行结构化处理。v1 版本支持三种内置解析器：

• | json：将 JSON 格式的日志行解析为字段，字段名直接作为标签名使用。
• | logfmt：解析 logfmt（key=value）格式的日志行，适用于 Go 生态的日志库。
• | regexp "<pattern>"：使用命名捕获组正则表达式提取字段。

解析后的字段可以用于后续的标签过滤或指标计算。以下是一个典型的管道解析示例：

{job="api-server"} |= "ERROR"
| json
| status_code = "500"
| duration > 1.5

在这个查询中：

1. 标签匹配器筛选出 api-server 的日志流。
2. 行过滤器保留包含 ERROR 的行。
3. | json 解析器将日志行（假设为 JSON 格式）解析为结构化字段。
4. 后续的 status_code 和 duration 是对解析后字段的过滤条件。

3.4 完整查询结构：从流到行到字段

LogQL v1 的完整查询结构可以抽象为以下流程：

上述流程体现了 LogQL v1 的“分层过滤”思想：每一层都在上一层的基础上缩小数据量，从而提升整体查询效率。在实际的版本漂移校准场景中，理解这一流程有助于定位不同版本间的行为差异——例如，v1 的管道解析器在遇到非 JSON 行时会直接丢弃，而 v2 的非严格模式则保留原始行，这可能导致同一查询在两个版本中返回不同的结果集。

3.5 实战示例：调试 API 500 错误

假设我们需要排查生产环境中 API 返回 500 错误的根因，使用 LogQL v1 可以构建如下查询：

{job="api-server", namespace="prod"} |= "500"
| json
| duration > 2.0
| path =~ "/api/v2/orders"

查询分解：

• 标签匹配：仅查询 api-server 在 prod 命名空间的日志流。
• 行过滤：只保留包含 500 字符串的行。
• JSON 解析：将日志行解析为结构化字段（如 duration、path、method 等）。
• 字段过滤：筛选出响应时间大于 2 秒且路径匹配 /api/v2/orders 的请求。

3.6 版本漂移校准清单

针对 LogQL v1 的标签匹配、行过滤与管道解析，以下清单总结了版本漂移的关键校准点：