XERJ 日志分析实战:单引擎用 Elasticsearch 聚合从原始日志到运维看板
XERJ 日志分析实战:单引擎用 Elasticsearch 聚合从原始日志到运维看板
本文基于 XERJ 仓库中的 log-analytics 配方文档 展开,演示如何在单个 XERJ 实例上完成一条完整的日志分析链路:为结构化日志建立显式 mapping、用 _bulk 批量摄入数百条合成日志事件,再用三条 Elasticsearch 风格的聚合查询回答 on-call 工程师最关心的三个问题——错误率是否在爬升、p95 延迟归因于哪个服务、谁在吃最多的流量。读完后你将掌握一套不依赖 Logstash、不依赖独立 metrics store、也不需要第二种查询语言的日志分析方案,并能结合源码理解 XERJ 聚合层的实际行为。
为什么 XERJ 可以直接承担日志分析
XERJ 说的是 Elasticsearch wire protocol,因此你已经在 ES 里用熟的聚合面可以直接工作:date_histogram、percentiles、terms、stats 以及 filter 子聚合全部开箱即用;摄入走 _bulk,查询走 _search。同一个 Rust 引擎同时负责日志文档、聚合计算,以及(如果以后需要)对同一批文档做全文检索与向量检索,没有 Logstash 与 metrics store 之间的运维切分。
从源码结构看,聚合的核心实现集中在 xerj-engine 的 aggs 模块,其中 run_date_histogram、run_percentiles、terms、stats 等都有独立实现分支;ES 兼容层则位于 xerj-api 的 es_compat 模块。仓库还在 engine/tests/es-compat-yaml 下维护了成体系的聚合兼容性测试,例如 date_histogram.yml 和 percentiles_bucket.yml,用于对照真实 ES 的输出语义做断言。
本篇配方中的所有数字与 JSON 都是对一台运行中的 XERJ 端到端执行后真实捕获的输出。
建索引:字段类型决定聚合行为
先给日志字段声明显式类型。@timestamp 必须是 date 才能喂给 date_histogram;latency_ms 与 status 必须是数值类型才能参与数学聚合;service/level 用 keyword 保证按精确值分桶而不被分析分词;message 保留 text 以便日后做全文过滤。
curl -XPUT localhost:9200/logs-app -H 'Content-Type: application/json' -d '{
"mappings": { "properties": {
"@timestamp": {"type": "date"},
"level": {"type": "keyword"},
"service": {"type": "keyword"},
"latency_ms": {"type": "integer"},
"status": {"type": "integer"},
"message": {"type": "text"}
}}
}'
各类型的取舍可以对照源码理解:aggs.rs 中 run_date_histogram(见 L6084)在计算分桶时直接消费字段的日期语义,同时接受 fixed_interval 与 calendar_interval 两种 ES 8.x 命名;而 keyword 字段走的是精确匹配路径,term 查询与 filter 子聚合不需要任何分词对齐。
用 _bulk 批量摄入日志
日志是成批到来的,因此用 bulk API:action 行与文档行交替的 NDJSON。配套示例脚本生成 600 条事件,分布在 6 小时、4 个服务(checkout、search、catalog、payments)上,每个服务有各自的基线延迟与出错倾向,让聚合结果能讲出一个真实的故事。一次 _bulk 调用即可全部送达:
POST /_bulk (Content-Type: application/x-ndjson)
{"index":{"_index":"logs-app"}}
{"@timestamp":"2026-07-06T08:14:03+00:00","level":"INFO","service":"search","latency_ms":61,"status":200,"message":"search handled request status=200"}
{"index":{"_index":"logs-app"}}
{"@timestamp":"2026-07-06T08:22:41+00:00","level":"ERROR","service":"payments","latency_ms":740,"status":503,"message":"payments handled request status=503"}
...
检查响应中的 errors 为 false,再调用 _refresh 使文档可搜索,最后 GET /logs-app/_count 确认 600 条全部落地。
一个值得注意的实现细节:从 es_compat.rs 的注释看,refresh=true|wait_for 参数会被接受但无需实际动作——XERJ 的 memtable 让写入的文档立即可见,_refresh 端点(见 refresh_index 实现)更多是作为兼容接口保留。也就是说在真实 ES 里需要等待的 refresh 周期,在这里基本不是问题。
Q1 — 错误率随时间的变化
用 date_histogram 按小时分桶,在每个桶内用 filter 子聚合统计 ERROR 事件数。errors.doc_count / doc_count 就是该小时的错误率——正是看板面板需要的数据形状。
POST /logs-app/_search
{
"size": 0,
"aggs": {
"per_hour": {
"date_histogram": { "field": "@timestamp", "fixed_interval": "1h" },
"aggs": {
"errors": { "filter": { "term": { "level": "ERROR" } } }
}
}
}
}
size: 0 表示"不返回 hits,只要聚合"。真实响应(前两个桶,took 单位为毫秒):
{
"took": 4,
"buckets": [
{ "key_as_string": "2026-07-06T08:00:00.000Z", "doc_count": 102,
"errors": { "doc_count": 7 } },
{ "key_as_string": "2026-07-06T09:00:00.000Z", "doc_count": 101,
"errors": { "doc_count": 3 } }
]
}
六个桶汇总后:
hour (UTC) total errors err_rate
08:00 102 7 6.9%
09:00 101 3 3.0%
10:00 106 5 4.7%
11:00 91 2 2.2%
12:00 93 2 2.2%
13:00 107 5 4.7%
08:00 一小时错误率最高(6.9%),其余时段稳定在 2%~5% 之间——这种"某个小时异常偏高"的形态,正是告警查询想抓住的信号。
Q2 — 延迟分位数(p50 / p95 / p99)
平均值会掩盖尾延迟,分位数不会。先取全队的分位数,再用 terms + percentiles 子聚合按服务拆出 p95,看谁在拖着尾部:
POST /logs-app/_search
{
"size": 0,
"aggs": {
"latency": { "percentiles": { "field": "latency_ms", "percents": [50, 95, 99] } },
"by_service": {
"terms": { "field": "service" },
"aggs": { "p95": { "percentiles": { "field": "latency_ms", "percents": [95] } } }
}
}
}
全队分位数按 ES 风格的 keyed 形式返回:
{ "latency": { "values": { "50.0": 56.0, "95.0": 321.15, "99.0": 565.22 } }
按服务的 p95 让"罪魁祸首"一目了然——checkout 和 payments 拖着尾部,catalog 和 search 保持平稳:
fleet-wide p50=56 p95=321 p99=565
service p95 latency
catalog 51
search 79
checkout 447
payments 529
为什么 p95 读起来是 321.15 这样的非整数值?这对应了源码中分位数算法的选择:run_percentiles 默认使用 tdigest 风格的近似算法,在排序后相邻值之间做线性插值(见 L7987-L7993),与 ES 的 close_to 语义对齐;如果传 hdr 参数则切换到 HdrHistogram 量化的最近秩路径。也就是说这些值是估计值而非精确顺序统计量,这一点与 ES 的语义一致。另外从同一函数可以看到,percents 不指定时的默认值是 [1, 5, 25, 50, 75, 95, 99],keyed 默认 true(对象 map 形式)。
Q3 — 按流量排名的 Top 服务(附带延迟统计)
一个 terms 聚合按事件量给服务排名;挂一个 stats 子聚合,在同一轮往返里把每个服务的 count/avg/min/max 延迟一并带回——排行榜和延迟画像一次查询全部拿到:
POST /logs-app/_search
{
"size": 0,
"aggs": {
"top_services": {
"terms": { "field": "service", "size": 10, "order": { "_count": "desc" } },
"aggs": { "lat": { "stats": { "field": "latency_ms" } } }
}
}
}
service volume avg_ms min max
catalog 190 35 15 118
search 187 51 22 114
checkout 150 167 60 590
payments 73 269 103 958
catalog 和 search 流量最大但很便宜;payments 流量最小但最坏情况最差(958 ms)。三次 _search 调用,triage 全貌就出来了。
自己动手复现
上文的表格就是下面这个脚本的确切捕获输出。数据集用固定种子生成(random.seed(7)),因此计数、错误率、分位数和按服务的表格都是确定性的——你会得到与这里完全相同的数字。唯一的运行间差异是 took(单查询延迟),保持在个位数毫秒(本次运行:Q1 took=4 ms,Q2 took=5 ms)。
# 1. 在默认端口(9200)启动 XERJ,insecure/local —— 无需任何配置
./engine/target/release/xerj --insecure --data-dir /tmp/xerj-logs &
# 2. 运行配方(纯标准库 —— 不装 pip 包、无第三方网络调用)
python3 docs/examples/log-analytics/log_analytics.py
客户端从 $XERJ_URL 读取服务器地址(默认 http://localhost:9200)。从 log_analytics.py 的源码看,地址解析顺序是:命令行第一个位置参数 > $XERJ_URL 环境变量 > 默认值,因此如果 XERJ 跑在别的端口可以直接传参覆盖,例如:
python3 docs/examples/log-analytics/log_analytics.py http://localhost:9483
脚本会创建 mapping、bulk 摄入 600 条事件、执行全部三条查询并打印上文表格,同时断言摄入计数为 600 且 _bulk 未报告错误——绿色运行即意味着聚合结果是真实的。绿色运行会打印三个按问题分组的表格,并以 All aggregations returned. 收尾;确定性核心数字汇总如下:
Ingested 600 log events into 'logs-app'
Q1 hourly error rate: 08:00 6.9% · 09:00 3.0% · 10:00 4.7% · 11:00 2.2% · 12:00 2.2% · 13:00 4.7%
Q2 fleet latency: p50=56 ms p95=321 ms p99=565 ms (per-service p95: catalog 51, search 79, checkout 447, payments 529)
Q3 top services: catalog 190 · search 187 · checkout 150 · payments 73 (payments worst-case 958 ms)
边界与诚实的限制
- 按需计算,没有后台 rollup。 这些聚合是每次查询时现算的——XERJ 不会跑持续 rollup 或后台作业。对临时看板和告警查询这恰是想要的行为;如果你需要在超高基数下预物化的 rollup,可以按调度周期聚合并把结果索引进另一个索引。
fixed_intervalvscalendar_interval。"1h"给出等间距桶;想要按日历边界(含 DST 处理)时使用calendar_interval("day"、"month"等)。aggs.rs 中的is_calendar_interval会识别 ES 的日历区间简写单位,两条命名路径在实现里被统一处理。- 分位数是近似值。 如 Q2 一节所述,tdigest 风格算法给出的是估计值而非精确顺序统计量,所以 p95 才读作
321.15而不是整数毫秒。 - 同一份文档、同一个引擎。 因为
message是text字段,可以在上述任何一条查询上追加match/match_phrase全文过滤(例如只对包含"timeout"的日志做聚合),数据不需要搬动到任何别处。
从聚合到检测:下一步可深入的方向
本配方解决了"描述性"问题;如果需要"检测性"能力,仓库内还有直接衔接的素材:
- anomaly-detection 示例:用
_ml统计检测器给指标/日志中的尖峰打标; - continuous-anomaly-datafeeds 示例:用带定时器的 datafeed 周期性对索引重新打分,并把新产生的异常记录持久化供轮询;
- log_anomaly.py:把 65.5 万条真实 OpenSSH 认证失败日志索引进 XERJ,用移动基线的 3σ 检测找出暴力破解攻击时段,再用普通
terms聚合归因到具体源 IP——同样是"先索引进来、聚合面直接问答"的模式; - 聚合行为本身的边界(如桶数量上限与内存预算)在 agg_bucket_cap.rs 等测试中有专门覆盖,可以作为扩展查询时的参考依据。
这套配方的整体思路可以一句话概括:结构化日志进 _bulk,运维问题用三条 _search 聚合回答,全文过滤留在同一份文档上——一个引擎、一种查询语言,覆盖从摄入到 triage 的完整路径。