Spring Boot应用中如何配置APM实现请求头的查询与可视化？

问题根源 #

尽管你的Spring Boot应用已经默认开启了APM请求头捕获，但捕获到的X-Tenant-Id字段大概率被标记为不可索引，或者被Elasticsearch的APM索引模板忽略，导致出现Unindexed fields or ignored values cannot be searched的提示。

具体解决步骤 #

1. 配置APM Agent明确保留目标请求头 #

在你的Spring Boot配置文件（application.properties或application.yml）中，指定要捕获并传递到APM Server的请求头：

• 用application.properties的写法：

# 仅保留X-Tenant-Id，若要保留默认捕获的其他头，用逗号分隔即可
elastic.apm.capture-headers=X-Tenant-Id

• 用application.yml的写法：

elastic:
  apm:
    capture-headers: X-Tenant-Id
    # 多字段示例：capture-headers: [X-Tenant-Id, User-Agent]

这个配置会让APM Agent把指定的请求头作为事务的字段发送出去，而不是仅捕获但不暴露为可查询字段。

2. 调整Elasticsearch索引模板，确保字段可索引 #

如果第一步配置后还是无法查询，需要检查APM的索引模板，把X-Tenant-Id对应的字段设为可索引：

1. 打开Kibana，进入Stack Management > Index Management > Index Templates
2. 找到APM事务相关的模板（比如apm-*-transaction）
3. 修改模板的映射规则，添加request.headers.x_tenant_id的配置（APM会自动把请求头的中横线转成下划线）：

"request": {
  "properties": {
    "headers": {
      "properties": {
        "x_tenant_id": {
          "type": "keyword",
          "index": true
        }
      }
    }
  }
}

设置type: keyword是因为租户ID是离散值，适合做聚合分析；index: true则允许该字段被搜索和聚合。

3. 验证配置是否生效 #

重启你的Spring Boot应用，发送几个带X-Tenant-Id的测试请求，然后在Kibana中验证：

• 进入APM的Transactions页面，尝试用request.headers.x_tenant_id作为筛选条件，看能否过滤出对应租户的请求
• 去Visualize Library创建饼图或柱状图，用request.headers.x_tenant_id作为分组维度，就能生成租户请求分布的可视化图表

为什么不推荐手动拦截请求更新事务？ #

这种方式需要编写额外的拦截器代码，不仅侵入业务逻辑，还会增加应用的性能开销，远不如直接通过Agent配置和索引模板调整来得高效、低维护。

内容的提问来源于stack exchange，提问作者Naman