接入OpenTelemetry Trace和Metric数据

适配范围

当前仅支持OpenTelemetry Java语言探针数据采集，支持的探针版本2.0~2.21。
Collector：4.2.0.0 或更高版本，并启用Guanyun Collector模块。

Collector主机资源要求

最低资源规格：
- 操作系统：CentOS 7 或更高版本、Red Hat Enterprise Linux 7 或更高版本、Ubuntu 18 或更高版本。
- CPU：4 核及以上。
- 物理内存：8 GB 及以上。

说明

部署限制：在同一部署环境中，仅支持部署 1 台用于接入OpenTelemetry Trace的Collector，不支持通过多个Collector实例进行水平扩展。
容量参考：经测试验证，部署于 4 核CPU、8 GB内存主机上的Collector，可承载约1500 TPS 的OpenTelemetry Trace数据流量。
扩容建议：如果接入流量超过1500 TPS，建议对该Collector主机扩容，可按以下公式估算 CPU 与内存资源：
```
CPU 核数 = 4 * 一天内 TPS 的峰值 / 1500

内存(GB) = 8 * 一天内 TPS 的峰值 / 1500
```

配置防火墙策略

OpenTelemetry探针会在业务应用服务器上采集数据，并将数据上报至Collector所在服务器。因此，需要确保OpenTelemetry探针服务器与Collector服务器之间的网络连通性，以保证数据采集与传输的正常进行。

提示

下表为示例地址与端口。请结合实际项目的地址规划和端口配置进行调整后再实施。

源地址	目标地址	目标端口	说明
Collector所在服务器	观云平台	80	Collector安装，向观云平台上传数据
OpenTelemetry探针所在服务器	Collector所在服务器	7667(HTTP)	接收OpenTelemetry Agent上报数据

安装Collector

登录观云平台。
在左侧导航栏点击全部应用，在打开的轻应用列表中点击部署状态。
在部署状态页面上方点击Collectors管理页签。
点击列表右上角的新增按钮，在打开页面中配置Collector参数：
- 推荐关闭APM Collector：APM功能会消耗较高CPU资源，建议尽量减少APM功能与OpenTelemetry Trace之间的相互影响。
- 必须开启Guanyun Collector：用于接收OpenTelemetry产生的监控数据。
复制Collector安装脚本，在部署Collector的服务器上执行脚本完成安装。

配置Collector接收OpenTelemetry数据

进入Collector安装目录。
```
cd /opt/tingyun-collector/
```
开启OpenTelemetry模块（当前仅支持Java语言探针数据采集）。
```
cd conf.d/o11y
cp o11y-processor-exporter.yaml.example o11y-processor-exporter.yaml
```
服务间调用拓扑（ServiceGraph）的窗口时间默认设置为1分钟。如果同一条调用链中各服务的请求时间间隔超过1分钟，部分调用关系可能无法被正确关联。

如需延长窗口时间，请在o11y-processor-exporter.yaml中修改connectors.servicegraph.store.ttl配置项：
```
store:
  ttl: 1m
```
注意
增大该参数会增加Collector的内存占用，请根据实际负载谨慎调整。
重启Collector。

配置修改完成后，需要重启Collector：
```
sudo systemctl restart tingyun-collector
```

Java应用程序嵌入OpenTelemetry探针（示例）

下载并解压OpenTelemetry Java探针。以2.21.0版本为例：

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.21.0/opentelemetry-javaagent.jar

官方参考：OpenTelemetry官方文档

修改Java应用程序启动脚本。
```
java -javaagent:path/to/opentelemetry-javaagent.jar \
 -Dotel.service.name=your-service-name \ #应用名称
 -Dotel.traces.exporter=otlp \ #设置Traces导出器到Collector
 -Dotel.metrics.exporter=otlp \ #设置metric导出器到Collector
 -Dotel.exporter.otlp.protocol=http/protobuf \ #设置导出器到Collector协议类型,grpc暂不支持
 -Dotel.exporter.otlp.endpoint=http://192.168.1.2:7667 \ #Collector地址:端口
 -Dotel.resource.attributes=service.port=8080,host.ip=192.168.1.8 \ #添加自定义属性
 -jar your-application.jar
```
参数说明：
- Dotel.service.name：服务名称，建议设置为应用名称，便于在报表中识别。
- Dotel.exporter.otlp.endpoint：Collector地址，默认端口为7667。
- Dotel.resource.attributes：自定义属性，可添加多个属性，便于在报表中筛选：
  - service.port：应用端口（OpenTelemetry Java Agent无法自动采集应用端口，建议按需补充；添加后在一台机器部署多个应用时更易区分）。
  - host.ip：应用所在服务器IP（OpenTelemetry Java Agent无法自动采集主机IP，建议按需补充；添加后在不同机器部署多个应用时更易区分）。

验证Collector端OpenTelemetry功能是否正常。

tail -f /opt/tingyun-collector/logs/guanyun/collector.log
# 使用以下命令查看日志是否包含`Setting up own telemetry`：
grep "Setting up own telemetry" collector.log

查看报表

进入观云平台实体管理轻应用，模型选择应用与微服务 > 应用，按应用名称过滤your-service-name。

进入观云平台应用轻应用，按应用名称过滤your-service-name。

问题排查

如果在报表中看不到数据，可按以下方式排查。

注意

排查完成后请恢复配置，避免影响正常运行与性能。

方法1：打开监控端口，通过curl确认是否有数据接收

修改Collector配置文件，临时开启Prometheus监控端口（以8888为例）。如果端口被占用，可以修改配置文件替换为其它可用端口。

编辑配置文件：

vim /opt/tingyun-collector/conf/guanyun/collector.yaml

在service.telemetry.metrics.readers下增加pull/prometheus配置；如存在level: none，请临时注释掉：

service:
  telemetry:
    logs:
      level: INFO
      output_paths: ${env:TINGYUN_COLLECTOR_HOME}/logs/guanyun/collector.log
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: "0.0.0.0"
                port: 8888
      # level: none

重启Collector：

sudo systemctl restart tingyun-collector

查看聚合的指标的数量是否增加（增加通常表示数据接收正常）：
```
curl http://127.0.0.1:8888/metrics | grep "sent_metric_points"
```

方法2：输出指标到临时文件，查看明细数据

通过file exporter将指标临时落盘，便于查看明细数据（排查完成后请移除该配置）。

编辑Collector主配置，增加file exporter：

vim /opt/tingyun-collector/conf/guanyun/collector.yaml

exporters:
  debug:
    verbosity: "${env:TINGYUN_GUANYUN_LOGLEVEL}"
  file:
    path: /opt/tingyun-collector/guanyun-collector.json

编辑Pipeline配置，将file加入metrics/o11y的exporters列表：

vim /opt/tingyun-collector/conf.d/o11y/o11y-processor-exporter.yaml

service:
  pipelines:
    traces/o11y:
      receivers: [otlp]
      processors: [groupbytrace/o11y, groupbyattrs/o11y]
      exporters: [servicegraph, otlphttp/default]
    metrics/servicegraph:
      receivers: [servicegraph]
      processors: [filter/servicegraph, cumulativetodelta/o11y/sg]
      exporters: [otlphttp/default]
    metrics/o11y:
      receivers: [otlp]
      processors: [filter/o11y, transform/o11y, cumulativetodelta/o11y/metric]
      exporters: [file, otlphttp/default]

重启Collector：

sudo systemctl restart tingyun-collector

查看临时文件是否有数据输出：

tail -f /opt/tingyun-collector/guanyun-collector.json

适配范围​

Collector主机资源要求​

配置防火墙策略​

安装Collector​

配置Collector接收OpenTelemetry数据​

Java应用程序嵌入OpenTelemetry探针（示例）​

查看报表​

问题排查​