配置项作用 #
http.tracer.include 配置项用于指定需要被跟踪记录的 HTTP 请求 URI 模式列表。
当启用 HTTP 请求跟踪时，只有匹配此配置中任一模式的请求才会被记录到 TRACE 级别的日志中。
配置项属性 #
- 配置路径:
http.tracer.include - 数据类型:
List<String>（字符串列表） - 默认值:
[]（空列表，表示不限制） - 是否可选: 是
- 作用域: NodeScope（节点级别）
- 动态配置: 是（支持运行时更新）
配置项详解 #
工作机制 #
HTTP 请求跟踪决策流程
HTTP 请求到达
│
↓
检查日志级别是否为 TRACE
│
├──────── 不是 TRACE ──→ 不跟踪 ❌
│
└──────── 是 TRACE
↓
检查 include 配置
│
├──────── include 为空 ──→ 跟踪所有请求 ✅
│
└──────── include 不为空
↓
检查 URI 是否匹配任一模式
│
├──────── 匹配 ──→ 继续检查 exclude
│ ↓
│ 不在 exclude 中 ✅
│ ↓
│ 记录到日志
│
└──────── 不匹配 ──→ 不跟踪 ❌
与 exclude 的配合 #
include 和 exclude 的协同工作
配置示例:
include: ["indices:*", "cluster:*"]
exclude: ["*health*", "*stats*"]
决策逻辑:
请求: GET /_cluster/health
↓
匹配 include: "cluster:*" ✅
↓
匹配 exclude: "*health*" ✅
↓
结果: 不跟踪 ❌
请求: GET /my_index/_search
↓
匹配 include: "indices:*" ✅
↓
匹配 exclude: "*health*" ❌
↓
结果: 跟踪 ✅
请求: GET /_cat/nodes
↓
匹配 include: "cluster:*" ❌
↓
结果: 不跟踪 ❌
模式匹配语法 #
支持的通配符模式:
* → 匹配任意数量的任意字符
示例:
"index*" → 匹配以 "index" 开头的 URI
/_index, /index1, /index_test
"*search" → 匹配以 "search" 结尾的 URI
/_search, /my_search
"*cat*" → 匹配包含 "cat" 的 URI
/_cat/indices, /_cat/nodes
"*admin*get*" → 匹配包含 "admin" 和 "get" 的 URI
/indices:admin/get, /_cluster/admin/get
匹配规则:
- 大小写敏感
- 支持 * 通配符
- 可以组合多个模式
配置建议 #
不启用跟踪（默认） #
http:
tracer:
include: [] # 默认值，不限制
exclude: []
建议: 保持默认。生产环境通常不需要启用跟踪。
跟踪特定 API #
http:
tracer:
include:
- "indices:*"
- "cluster:*"
exclude:
- "*health*"
建议: 只跟踪关键 API。用于调试特定功能。
跟踪所有请求 #
http:
tracer:
include: ["*"]
exclude: []
建议: 仅用于开发和调试。会产生大量日志。
跟踪慢查询 #
http:
tracer:
include:
- "*_search"
- "*_count"
exclude: []
建议: 只跟踪搜索和计数操作。用于性能分析。
代码示例 #
easysearch.yml 基础配置 #
http:
tracer:
include: ["indices:*", "cluster:*"]
开发环境完整配置 #
http:
tracer:
include: ["*"]
exclude: ["_cat/*", "*health*"]
生产环境调试配置 #
http:
tracer:
include:
- "indices:admin/*"
- "cluster:admin/*"
exclude:
- "*health*"
- "*stats*"
API 调试配置 #
http:
tracer:
include:
- "*_search"
- "*_bulk"
- "*_update"
exclude: []
相关配置 #
| 配置项 | 作用 | 默认值 |
|---|---|---|
http.tracer.include | 包含模式列表 | [] |
http.tracer.exclude | 排除模式列表 | [] |
transport.tracer.include | 传输层包含模式 | [] |
transport.tracer.exclude | 传输层排除模式 | [“internal:*"] |
Easysearch API 模式 #
常见 API 路径模式 #
索引管理:
"indices:admin/create" → 创建索引
"indices:admin/delete" → 删除索引
"indices:admin/get*" → 获取索引信息
"indices:data/write/*" → 写入文档
集群管理:
"cluster:admin/*" → 所有集群管理 API
"cluster:monitor/*" → 集群监控 API
"cluster:state" → 获取集群状态
搜索相关:
"*_search" → 所有搜索 API
"*_count" → 所有计数 API
"*_msearch" → 多搜索 API
文档操作:
"indices:data/read/*" → 读取文档
"indices:data/write/*" → 写入文档
按功能分类的模式 #
监控相关:
include: ["*health*", "*stats*", "*info"]
→ 跟踪健康检查和统计信息
数据操作:
include: ["*_search", "*_bulk", "*_index", "*_update"]
→ 跟踪数据增删改查
管理操作:
include: ["*:admin/*", "cluster:*"]
→ 跟踪所有管理操作
排除频繁请求:
exclude: ["_cat/*", "*health*"]
→ 排除高频的监控请求
使用场景 #
推荐使用 include 的场景 #
- 特定功能调试: 只需要调试特定的 API 功能
- 性能问题排查: 跟踪某些 API 的性能问题
- 安全审计: 记录特定的敏感操作
- 开发测试: 跟踪特定功能的请求详情
推荐保持默认的场景 #
- 生产环境: 通常不需要详细的 HTTP 跟踪
- 高流量系统: 日志量会非常大
- 性能敏感: 跟踪会带来性能开销
日志级别配置 #
启用 TRACE 日志级别
log4j2.properties:
logger.http.name = org.easysearch.http
logger.http.level = trace
或通过 API 动态设置:
PUT /_cluster/settings
{
"transient": {
"logger.org.easysearch.http": "TRACE"
}
}
动态更新 #
# 通过 API 动态更新跟踪配置
PUT /_cluster/settings
{
"transient": {
"http.tracer.include": ["indices:*", "cluster:*"],
"http.tracer.exclude": ["*health*"]
}
}
# 禁用跟踪
PUT /_cluster/settings
{
"transient": {
"http.tracer.include": [],
"http.tracer.exclude": []
}
}
跟踪日志示例 #
TRACE 日志输出示例:
[TRACE][request-id][user-id][GET][/my_index/_search] received request from [192.168.1.100]
[TRACE][request-id][user-id][GET][/my_index/_search] request processed in [45ms]
日志内容包含:
- Request ID: 请求唯一标识
- User ID: 用户标识（如果有）
- Method: HTTP 方法
- URI: 请求路径
- Source: 客户端地址
- Processing Time: 处理时间
注意事项 #
日志级别: 只有当日志级别设置为 TRACE 时，跟踪才会生效。
性能影响: 启用跟踪会带来性能开销，生产环境谨慎使用。
日志量: 使用
["*"]会产生大量日志，可能导致磁盘空间不足。模式匹配: 模式匹配是大小写敏感的。
动态更新: 支持运行时动态更新，立即生效。
与 exclude 配合: 先检查 include，再检查 exclude。
空列表含义:
include为空时，匹配所有请求（除非exclude有限制）。存储考虑: 确保有足够的磁盘空间存储跟踪日志。
日志轮转: 配置适当的日志轮转策略，避免单个日志文件过大。
敏感信息: 跟踪日志可能包含敏感信息，注意日志安全管理。
