OpenSearch Trace Analytics服务页为空 服务地图索引无数据排查

核心问题定位 #

raw trace能正常写入说明链路传输、基础权限配置没问题，故障集中在服务拓扑聚合层，属于OpenSearch 1.2 + Data Prepper 1.x版本栈的典型兼容+配置错误问题，具体修复方式如下： #

修复步骤 #

1. 对齐组件版本，解决OTLP协议兼容问题 #

当前使用的组件版本存在已知兼容缺陷：

• OTel Collector 0.55.0版本上报的span属性格式，和Data Prepper 1.x的service_map_stateful预处理组件不匹配，拓扑计算所需的span关联ID、peer属性会被静默丢弃，info级别日志不会打印任何报错。
• latest标签的OTel Java Agent会跟随上游更新OTLP协议版本，新版协议上报的span字段旧版Data Prepper无法识别。
  统一替换为官方验证兼容的版本：
• OTel Collector镜像固定为otel/opentelemetry-collector:0.66.0，直接修改docker-compose.yml中的镜像tag即可，原有Collector配置不需要调整。
• OTel Java Agent固定使用1.19.0版本，不要用latest滚动版本。

2. 修正Data Prepper管道配置 #

当前pipelines.yaml中服务拓扑管道配置有两个错误：

• delay参数设置为100ms远低于推荐值：该参数控制拓扑聚合窗口的等待时间，过短会导致同一个trace的span还没上报全就触发计算，不完整的拓扑数据会被直接丢弃，官方推荐值为10000ms（10秒）。
• 未显式配置service_map_stateful的窗口参数，默认窗口在低流量场景下不会触发刷写。
  替换service-map-pipeline配置为以下内容：

service-map-pipeline:
  delay: "10000"
  source:
    pipeline:
      name: "entry-pipeline"
  prepper:
    - service_map_stateful:
        window_duration: 10s
        enable_when_no_spans: false
  sink:
    - opensearch:
        hosts:
          [
            <AWS OPENSEARCH HOST>,
          ]
        aws_sigv4: true
        aws_region: <AWS_REGION>
        index_type: "trace-analytics-service-map"

3. 补全Java Agent启动参数 #

当前Tomcat的setenv.sh配置缺两个关键参数：

• 显式指定OTEL_TRACES_EXPORTER=otlp：部分版本的OTel Java Agent在手动设置metrics exporter为none后，会默认将trace exporter也置为none，导致部分关键span漏报。
• 补充service.namespace资源属性：避免Trace Analytics将同服务名的节点识别为临时节点，无法在服务列表展示。
  修改后的setenv.sh关键配置如下：

#!/bin/sh
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:<PATH_TO_JAVA_AGENT>"
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<OTEL_COLLECTOR_SERVER_IP>:4317
export OTEL_RESOURCE_ATTRIBUTES=service.name=<SERVICE_NAME>,service.namespace=prod
export OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING=<RDS_HOST_ENDPOINT>=Database-Service

验证流程 #

1. 按顺序重启OTel Collector、Data Prepper容器，确认两个服务日志无启动报错
2. 重启Tomcat服务，持续产生10分钟左右的正常业务流量（拓扑计算需要攒够一定量的trace数据才能生成服务节点）
3. 先查询otel-service-map-*索引确认有文档写入，再刷新Trace Analytics的Services标签页即可看到服务列表和拓扑图
   如果需要定位聚合过程的细节问题，可以在data-prepper-config.yaml中添加log_level: DEBUG，重启后就能看到span解析、拓扑计算的详细日志，快速定位是否存在字段缺失问题。

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