octopus-log-query

name	octopus-log-query
description	Octopus 日志搜索与分析指南，涵盖日志搜索语法（字段搜索/全文搜索/逻辑运算/模糊匹配）、绘图分析（count/avg/max/min/sum/percentile/heatmap + group by）、请求总览、日志生成指标、日志生命周期、数据管理、保留字段、全文检索分词策略。用于指导在 Octopus 平台进行日志查询、分析和指标生成。
version	1.0.0
tags	["octopus","log","search","query","analytics"]

Octopus 日志搜索与分析

一、日志搜索语法

支持字段搜索和全文搜索，支持逻辑运算和模糊匹配。

1.1 字段搜索

查询某个字段（key）为特定取值（value）的日志。

匹配符	含义	举例
=	等于	env=online
!=	不等于	env!=online
>	大于	duration > 20
>=	大于等于	duration >= 20
<	小于	duration < 20
<=	小于等于	duration <= 20
in	包含	host in (host1, host2)
not in	不包含	host not in (host1, host2)

注意：

• key 和 value 严格区分大小写，匹配符大小写不敏感
• 仅分析字段支持 >/>=/</<=
• issue_id 无法使用大小比较和模糊匹配

1.2 全文搜索

直接输入关键字搜索日志正文。全文搜索大小写敏感。

示例：

• 查询包含 addCart 的日志
• 查询同时包含 addCart 和 fail 的日志
• 查询包含 "hello word" 的日志（精准匹配用双引号）

1.3 逻辑运算

运算符	说明	举例
AND	满足所有条件	service=payment AND env=online AND fail
OR	满足任一条件	level=ERROR OR "mission fail"
NOT	不满足该条件	NOT "mission fail"

注意：

• 优先级：NOT > AND > OR，可用括号 () 提升
• 基础模式下默认 AND，无需指定
• 查询包含 AND/OR/NOT 的日志需用双引号包裹
• 运算符大小写不敏感

1.4 模糊匹配

仅适用于字段搜索，严格区分大小写。

匹配符	说明	举例
*	匹配任意字符任意多次	service=web*

1.5 特殊字符

包括 = > < ~ ' " * + ? ( ) [ ] { } ! ^ | / % \ 及空格。

• 含特殊字符的值需用双引号包裹："customCode=123"
• 双引号和反斜杠需额外 \ 转义："I say:\"Hello\\world!\""
• 示例：browser IN (safari, "safari mobile")

1.6 两种模式

• 基础模式（推荐）：图形化输入，提供输入建议，不支持 OR
• 高级模式：文本输入，支持完整搜索语法

---

二、绘图分析

将搜索命中的日志做分类统计。

2.1 计算能力

类型	支持函数
所有日志	count(*)
维度类字段	count_distinct(field)
度量类字段	avg、min、max、sum、分位数（pxx）、heatmap

2.2 分组聚合

支持 group by 按字段分组统计。

限制：只有「分析字段」才可用于绘图分析。

---

三、请求总览

将搜索到的日志按"请求"分组（如 by trace_id、session_id、user_id），展示完整请求链路上的日志和 trace 数据。

用途：

1. 快速找到有问题的请求 - 搜索用户 id 后查看每个请求中有无错误日志
2. 找到异常请求的共性 - 搜索错误日志后查看每个请求的入口

---

四、日志生成指标

将日志数据（log）转成指标数据（metric），通过计数统计或数值计算得到时序数据。

优势

• 比直接使用日志成本更低，可观测更长周期（日志 30 天 vs 指标 15 个月）
• 支持复杂计算（周环比、QPS 等）
• 多处引用时避免重复填写复杂日志条件

新建指标

1. 指标名称 - 以字母开头，只含字母、数字和 ._-:，不超过 40 字符
2. 日志范围 - 查询语法与日志搜索语法一致
3. 统计对象 - 默认 * 统计条数，或对度量字段计算 avg/min/max/sum/分位数
4. 标签键 - 配置 group by 字段

创建后约一分钟可用，默认采集间隔 10s。指标名称创建后不可修改。

---

五、保留字段

系统中具有特殊产品含义的字段，分三类：

5.1 资源类（resources）

不随日志原文变更的字段（如 service、host、env），从采集器配置文件获取。

5.2 日志类（attributes）

从日志原文解析的字段（如 level、trace_id）。

5.3 日志原文

octopus.message 是特殊的日志原文字段。

冲突处理

• 资源类：通过解析规则得到的值与已有值不同时视为冲突字段 conflict.xxxx
• 日志类：按步骤顺序第一个解析出的为保留字段，后续不同值视为冲突字段
• 日志原文：始终处理为 conflict.octopus.message
• 可通过字段映射规则强制修改冲突字段为保留字段

全站使用符号 R 标志保留字段。

---

六、全文检索分词策略

基于 Unicode UTS#29 标准实现分词。

关键规则

规则	说明	示例
字母	连续字母合并为一个词	hello → ["hello"]
数字	连续数字合并	12345 → ["12345"]
字母间单引号/下划线	保留	don't → ["don't"]，don_t → ["don_t"]
字母间连字符	分词	don-t → ["don", "t"]
数字间逗号	保留	1,000 → ["1,000"]
数字间句号	分词	100.1 → ["100", "1"]
数字与字母间下划线	保留	1_dont → ["1_dont"]
汉字	逐字切分	中文 → ["中", "文"]

查询能力边界

• 支持：基于完整词单元的精确匹配
• 不支持：SQL LIKE %closing repl% 类模糊匹配

---

七、数据管理

数据处理入口：https://octopus.zhenguanyu.com/#/dataManagement/configure?tabKey=rule

功能：

• 日志数据处理（结构化为 key-value）
• 分析字段管理

八、日志生命周期

日志默认存储 30 天。有特殊需求可联系 Octopus 团队。