LogQL

Grafana Loki 使用的日志查询语言，用标签筛选加管道式过滤从海量日志中取出所需记录。

生产方式：人写签发：晓黎学习复核：2026年9月21日被 2 个词条引用

一句话定义

LogQL = Grafana Loki 的日志查询语言。语法接近 PromQL，用「标签选择器 + 管道过滤器」从日志流中筛出需要的记录。

为什么会出现

传统全文检索在处理海量日志时索引成本高。Loki 的选择是：只给标签建索引，日志正文不建索引，查询时用标签快速缩小范围，再对候选日志做管道式过滤。LogQL 就是这套模型的查询语言。

这个设计让存储成本大幅下降，代价是查询比全文检索慢。

基本结构

{app="api", env="prod"} |= "timeout" | json | duration > 1000

拆开看：

部分作用
{app="api", env="prod"}标签选择器，快速缩小日志流范围
|= "timeout"行过滤：包含该字符串
| json解析器：把 JSON 日志解析成字段
| duration > 1000标签过滤：对解析出的字段做条件筛选

常用的行过滤操作符：

操作符含义
|=包含
!=不包含
|~匹配正则
!~不匹配正则

与 PromQL 的关系

语言查询对象典型用途
LogQL日志找出「哪几条日志说明了问题」
PromQL指标找出「这个数值随时间怎么变」

两者常配合使用：先用 PromQL 发现异常指标，再用 LogQL 定位具体日志。

在 Agent Harness 中的位置

当 Agent 需要排查线上问题时，日志和指标是它的「外部感官」。OpenAI 的 Codex 实践把可观测性栈暴露给 Agent：

Agent 可以用 LogQL 查询日志，用 PromQL 查询指标。有了这些上下文，「确保服务在 800ms 内启动」或「这四个关键用户旅程中没有 span 超过 2 秒」这样的提示变成了可执行的。

这意味着：

关注点归属
查询语言本身观测后端能力
Agent 如何调用工具（第 06、07 讲）
查询结果如何进上下文Prompt 装配（第 03 讲）
查询过程如何审计可观测性（第 17 讲）

关键设计点

  1. 标签设计决定查询效率：标签基数过高会让日志流爆炸，查询变慢。
  2. 查询能力即权限：Agent 能查日志，就意味着能读到日志里的内容，需要与权限层（第 14 讲）配合。
  3. 结果需要裁剪：一次查询可能返回上万行，进上下文前必须截断或聚合。
  4. 查询也是被观测对象：Agent 发起了什么查询，本身应记录进追踪。

相关

来源

  • Grafana Labs. Loki 与 LogQL 官方文档。
  • OpenAI. "Harness Engineering: Leveraging Codex in an Agent-First World". 2026-02-11. 文中描述将日志、指标与 trace 暴露给 Codex，并将 LogQL/PromQL 查询转化为可执行的上下文。

互链

链接来自概念卡正文里的双链，编译时能解到本期词条集的才成为站内链接。

反链（2）

出现在哪些课时里（0）

判据与「课时正文里能不能点出来」是同一个：那一节确实提到了它。点课时走当前页跳转， 它是导航，不是词条链接。

还没有课时讲到这一条。它是词条跑在课程前面的那一部分，不是错链。

关联图

只画这一条与它直接相连的词条，边与上面两区同源。可拖拽、可缩放，点节点是新标签。

以列表方式看这 5 个节点

出处

路径是本地知识库（Obsidian 库）里的位置，正文与概念卡逐字对应。

  • 概念卡原文LogQL03_RESOURCES/概念/logql.md
  • 所属知识地图栏目概念页索引 · 可观测性与可靠性03_RESOURCES/概念/Index.md
  • 正文引用的知识库笔记第 17 讲 可观测性02_AREAS/AI开发/Harness Engineering/Agent Harness 课程/17-可观测性：如何知道系统正在发生什么.md

编译入库：2026年11月2日。词条由知识库编译而来， 修正要回到概念卡改，再重新编译。