--- title: "HTTP 请求跟踪包含配置" date: 2026-03-19 lastmod: 2026-03-19 description: "http.tracer.include 配置项用于控制哪些 HTTP 请求需要被记录到跟踪日志中。" tags: ["HTTP", "请求跟踪", "日志调试", "性能监控"] summary: "配置项作用 # 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: [] 建议: 保持默认。生产环境通常不需要启用跟踪。" --- ## 配置项作用 `http.tracer.include` 配置项用于指定**需要被跟踪记录的 HTTP 请求 URI 模式列表**。 当启用 HTTP 请求跟踪时，只有匹配此配置中任一模式的请求才会被记录到 TRACE 级别的日志中。 ## 配置项属性 - **配置路径**: `http.tracer.include` - **数据类型**: `List`（字符串列表） - **默认值**: `[]`（空列表，表示不限制） - **是否可选**: 是 - **作用域**: 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 匹配规则: - 大小写敏感 - 支持 * 通配符 - 可以组合多个模式 ``` ## 配置建议 ## 不启用跟踪（默认） ```yaml http: tracer: include: [] # 默认值，不限制 exclude: [] ``` **建议**: 保持默认。生产环境通常不需要启用跟踪。 ## 跟踪特定 API ```yaml http: tracer: include: - "indices:*" - "cluster:*" exclude: - "*health*" ``` **建议**: 只跟踪关键 API。用于调试特定功能。 ## 跟踪所有请求 ```yaml http: tracer: include: ["*"] exclude: [] ``` **建议**: 仅用于开发和调试。会产生大量日志。 ## 跟踪慢查询 ```yaml http: tracer: include: - "*_search" - "*_count" exclude: [] ``` **建议**: 只跟踪搜索和计数操作。用于性能分析。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml http: tracer: include: ["indices:*", "cluster:*"] ``` ## 开发环境完整配置 ```yaml http: tracer: include: ["*"] exclude: ["_cat/*", "*health*"] ``` ## 生产环境调试配置 ```yaml http: tracer: include: - "indices:admin/*" - "cluster:admin/*" exclude: - "*health*" - "*stats*" ``` ## API 调试配置 ```yaml 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" } } ``` ## 动态更新 ```yaml # 通过 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: 处理时间 ``` ## 注意事项 1. **日志级别**: 只有当日志级别设置为 TRACE 时，跟踪才会生效。 2. **性能影响**: 启用跟踪会带来性能开销，生产环境谨慎使用。 3. **日志量**: 使用 `["*"]` 会产生大量日志，可能导致磁盘空间不足。 4. **模式匹配**: 模式匹配是大小写敏感的。 5. **动态更新**: 支持运行时动态更新，立即生效。 6. **与 exclude 配合**: 先检查 include，再检查 exclude。 7. **空列表含义**: `include` 为空时，匹配所有请求（除非 `exclude` 有限制）。 8. **存储考虑**: 确保有足够的磁盘空间存储跟踪日志。 9. **日志轮转**: 配置适当的日志轮转策略，避免单个日志文件过大。 10. **敏感信息**: 跟踪日志可能包含敏感信息，注意日志安全管理。