XERJ 日志分析实战:单引擎用 Elasticsearch 聚合从原始日志到运维看板

原创2026-10-16 14:18:172,192 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

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_interval vs calendar_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 的完整路径。

登录后查看全文
xerj