| 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 数据。
用途：
- 快速找到有问题的请求 - 搜索用户 id 后查看每个请求中有无错误日志
- 找到异常请求的共性 - 搜索错误日志后查看每个请求的入口
四、日志生成指标
将日志数据（log）转成指标数据（metric），通过计数统计或数值计算得到时序数据。
优势
- 比直接使用日志成本更低，可观测更长周期（日志 30 天 vs 指标 15 个月）
- 支持复杂计算（周环比、QPS 等）
- 多处引用时避免重复填写复杂日志条件
新建指标
- 指标名称 - 以字母开头，只含字母、数字和
._-:，不超过 40 字符
- 日志范围 - 查询语法与日志搜索语法一致
- 统计对象 - 默认
* 统计条数，或对度量字段计算 avg/min/max/sum/分位数
- 标签键 - 配置 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 团队。
