OpenTelemetry Java Agent 对接 Webfunny APM平台详细文档

一只会飞的鱼儿 1小时前 ⋅ 3 阅读
ad

一、对接概述

1. 文档目的

本文档详细说明 Java 应用通过 OpenTelemetry Java Agent 对接 Webfunny 监控平台的完整流程，包括 Agent 下载、配置参数、多环境启动方式、监控验证及问题排查，适用于需要采集链路追踪、SQL 调用、HTTP 请求等数据并上报至 Webfunny 的 Java 项目（支持 Spring Boot、Spring MVC、MyBatis、Redis 等主流框架组件）。

2. 核心优势

  • 零代码侵入：无需修改业务代码，通过启动参数附加 Agent 即可实现全链路监控；
  • 自动采集范围广：支持 HTTP 请求、JDBC/SQL 操作、Redis 调用、消息队列等基础设施监控；
  • 灵活扩展：可结合注解增强关键业务方法监控，支持混合使用模式；
  • 配置简单：通过环境变量或启动参数快速配置，生产环境可灵活调整采样率、排除无关端点。

3. 支持的监控内容

监控类型
具体内容
采集信息
HTTP 接口
Spring MVC、Spring WebFlux、RestTemplate 等
URL、请求方法、状态码、响应时间、异常堆栈
数据库操作
JDBC、MyBatis、JPA 等
SQL 语句、执行参数、连接信息、执行耗时
缓存操作
Redis 客户端调用
命令类型、Key 值、执行时间
消息队列
Kafka、RabbitMQ 等
队列名称、消息发送 / 消费状态、耗时
业务方法
自定义注解标注的方法
方法名称、参数、执行时间、异常信息
系统组件
线程池、定时任务
任务名称、执行状态、耗时

二、前置准备

1. 环境要求

  • Java 版本：JDK 8 及以上
  • 项目类型：Java 后端项目（Spring Boot、Spring MVC 等）
  • 依赖管理：Maven/Gradle（本文以 Maven 为例）

2. 核心文件下载

下载 OpenTelemetry Java Agent 探针 Jar 包，支持以下两种方式：
# 方式 1：使用 wget 下载最新版本
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
 
# 方式 2：使用 curl 下载最新版本
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
  • 下载后建议存放至项目根目录或服务器固定路径（如 /opt/opentelemetry/），记录路径用于后续配置。

三、核心配置参数说明

1. 必选配置

配置参数
说明
示例值
-javaagent:
指定 OpenTelemetry Agent Jar 包绝对路径
/opt/opentelemetry/opentelemetry-javaagent.jar
otel.service.name
服务名称（Webfunny 平台区分不同应用的标识）
webfunny-manage（需自定义，与项目名称一致）
otel.traces.exporter
追踪数据导出器（对接 Webfunny 需指定 otlp）
otlp
otel.exporter.otlp.endpoint
Webfunny 提供的 OTLP 数据接收端点
http://xxx.webfunny.cn:4317（需替换为实际地址）

2. 可选配置

配置参数
说明
可选值
示例值
otel.exporter.otlp.protocol
数据上报协议
grpc（默认）、http/protobuf
grpc
otel.metrics.exporter
指标数据导出器（无需采集指标时设为 none）
otlp、none
none
otel.logs.exporter
日志数据导出器（无需采集日志时设为 none）
otlp、none
none
otel.traces.sampler
采样策略（生产环境推荐按需配置）
always_on（全采）、always_off（不采）、traceidratio（按比例采）
traceidratio
otel.traces.sampler.arg
采样率（仅 traceidratio 策略生效）
0.0~1.0（0.1 表示 10%）
0.1
otel.instrumentation.*.exclude-patterns
排除无需监控的端点（支持通配符）
接口路径，多个用逗号分隔
/actuator/**,/health,/ping
otel.javaagent.logging.level
Agent 日志级别
INFO、DEBUG、WARN、ERROR
INFO

四、多场景启动配置

1. 命令行直接启动（推荐生产环境）

适用于服务器部署场景，通过命令行参数指定 Agent 及配置：
java -javaagent:/opt/opentelemetry/opentelemetry-javaagent.jar \
-Dotel.service.name=webfunny-manage \
-Dotel.traces.exporter=otlp \
-Dotel.exporter.otlp.endpoint=http://xxx.webfunny.cn:4317 \
-Dotel.metrics.exporter=none \
-Dotel.logs.exporter=none \
-Dotel.traces.sampler=traceidratio \
-Dotel.traces.sampler.arg=0.1 \
-Dotel.instrumentation.spring-webmvc.exclude-patterns="/actuator/**,/health" \
-jar target/webfunny_manage-2.0.jar
  • 说明：-javaagent 后需替换为实际的 Agent 路径；采样率和排除端点可根据业务需求调整。

2. Maven 启动（开发环境）

修改项目 pom.xml 文件，在 spring-boot-maven-plugin 中配置 Agent 及系统参数，支持 mvn spring-boot:run 直接启动：
<build>
>
 
.boot aven-plugin （项目根目录下） -->
 
.basedir}/opentelemetry-javaagent.jar>
 
Telemetry 系统参数 -->
>
.name>webfunny-manage
ces.exporter>otlp</otel.traces.exporter>
.exporter.otlp.endpoint>http://xxx.webfunny.cn:4317.otlp.endpoint>
.exporter>none.metrics.exporter>
porter>nones.exporter>
ampler>always_on</otel.traces.sampler> 全采 -->
</systemPropertyVariables>
</configuration>
</plugin>
>
启动命令：
mvn clean package -Dmaven.test.skip=true
mvn spring-boot:run

3. IDEA 开发环境启动

适用于本地调试，通过 IDEA 启动配置添加 VM 参数：
  1. 打开 IDEA → Run/Debug Configurations → 选择当前项目的启动类；
  1. 在「VM options」中添加以下配置：
-javaagent:/Users/xxx/project/webfunny-manage/opentelemetry-javaagent.jar
-Dotel.service.name=webfunny-manage
-Dotel.traces.exporter=otlp
-Dotel.exporter.otlp.endpoint=http://xxx.webfunny.cn:4317
-Dotel.metrics.exporter=none
-Dotel.logs.exporter=none
-Dotel.traces.sampler=always_on
-Dotel.javaagent.logging.level=DEBUG
  • 说明：-javaagent 后替换为本地 Agent 路径；DEBUG 级别日志可辅助排查本地对接问题。

4. 脚本启动（生产环境运维推荐）

创建启动脚本 start_with_otel.sh，包含启动、停止、重启逻辑，方便运维管理：
#!/bin/bash
 
# 应用名称
APP_NAME="webfunny-manage"
# JAR 包路径
JAR_PATH="target/webfunny_manage-2.0.jar"
# Agent 路径
AGENT_PATH="/opt/opentelemetry/opentelemetry-javaagent.jar"
# Webfunny OTLP 端点
OTLP_ENDPOINT="http://xxx.webfunny.cn:4317"
# 服务名称
SERVICE_NAME="webfunny-manage"
 
# 启动函数
start() {
echo "正在启动 $APP_NAME 并加载 OpenTelemetry Agent..."
nohup java -javaagent:"$AGENT_PATH" \
-Dotel.service.name="$SERVICE_NAME" \
-Dotel.traces.exporter=otlp \
-Dotel.exporter.otlp.endpoint="$OTLP_ENDPOINT" \
-Dotel.metrics.exporter=none \
-Dotel.logs.exporter=none \
-Dotel.traces.sampler=traceidratio \
-Dotel.traces.sampler.arg=0.1 \
-Dotel.instrumentation.spring-webmvc.exclude-patterns="/actuator/**,/health" \
-jar "$JAR_PATH" > app.log 2>&1 &
echo "$APP_NAME 启动成功，日志输出至 app.log"
}
 
# 停止函数
stop() {
echo "正在停止 $APP_NAME..."
PID=$(ps -ef | grep "$APP_NAME" | grep -v grep | awk '{print $2}')
if [ -n "$PID" ]; then
kill -9 "$PID"
echo "$APP_NAME 已停止（PID: $PID）"
else
echo "$APP_NAME 未运行"
fi
}
 
# 重启函数
restart() {
stop
sleep 2
start
}
 
# 命令分发
case "$1" in
start)
start
;;
stop)
stop
;;
restart)
restart
;;
*)
echo "使用方法: $0 {start|stop|restart}"
exit 1
;;
esac
脚本使用：
# 添加执行权限
chmod +x start_with_otel.sh
 
# 启动
./start_with_otel.sh start
 
# 停止
./start_with_otel.sh stop
 
# 重启
./start_with_otel.sh restart

五、注解增强监控（可选，混合使用模式）

OpenTelemetry Java Agent 支持结合注解监控关键业务方法，实现 “基础设施自动监控 + 业务方法精准监控” 的混合模式，步骤如下：

1. 添加依赖（若项目未集成）

核心 API -->
<dependency>
>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
<version>1.24.0</dependency>
方法追踪注解 -->
<dependency>
>io.opentelemetry.instrumentation
elemetry-instrumentation-annotations 24.0>

2. 业务方法添加注解

在 Service 层、Controller 层的关键业务方法上添加 @WithSpan 注解，自定义 Span 名称：
import io.opentelemetry.instrumentation.annotations.WithSpan;
import org.springframework.stereotype.Service;
 
@Service
public class OrderService {
 
// 自定义 Span 名称为 "calculateOrderAmount"，会被 Agent 采集
@WithSpan("calculateOrderAmount")
public BigDecimal calculateAmount(Order order) {
// 复杂业务逻辑（如计算订单金额、折扣、税费等）
return order.getTotalAmount().multiply(new BigDecimal("0.95"));
}
 
// 无注解的方法不会生成独立 Span，但内部调用的 HTTP/SQL 仍会被 Agent 监控
public void saveOrder(Order order) {
// 保存订单逻辑
}
}
  • 说明：添加注解后，方法的执行时间、参数、异常信息会被单独采集为一个 Span，在 Webfunny 平台可查看完整的业务链路。

六、监控数据验证

1. 验证流程

  1. 按上述配置启动应用，确保启动日志无 OpenTelemetry 相关报错；
  1. 触发应用流量（如调用 HTTP 接口、执行数据库操作、触发业务方法）；
  1. 登录 Webfunny 监控平台 → 进入 APM 链路追踪模块 → 选择当前服务名称（otel.service.name 配置的值）；
  1. 查看链路数据，确认以下信息：
    • HTTP 接口：URL、请求方法、状态码、响应时间；
    • SQL 操作：SQL 语句、执行参数、耗时；
    • 业务方法：@WithSpan 注解标注的方法 Span；
    • 异常信息：若接口或方法抛出异常，是否显示异常堆栈。

2. 本地调试辅助（Jaeger 可选）

若需本地验证数据采集是否正常，可启动 Jaeger 作为临时 OTLP 接收端：
docker run -d --name jaeger \
-p 4317:4317 \
-p 16686:16686 \
jaegertracing/all-in-one:latest

七、常见问题排查

1. Agent 加载失败

  • 现象：启动日志无 OpenTelemetry 初始化信息，Webfunny 平台无数据；
  • 排查步骤：
    1. 检查 -javaagent 路径是否正确（绝对路径，无拼写错误）；
    1. 确认 Agent Jar 包未损坏（重新下载最新版本）；
    1. 检查 Java 版本是否兼容（需 JDK 8+）；
    1. 查看应用启动日志，搜索 OpenTelemetry 关键字，确认是否有加载失败报错。

2. 数据上报失败

  • 现象：应用启动正常，但 Webfunny 平台无数据；
  • 排查步骤：
    1. 验证 otel.exporter.otlp.endpoint 是否正确（需包含端口 4317）；
    1. 检查服务器网络是否能连通 Webfunny 端点（执行 telnet xxx.webfunny.cn 4317 或 curl -v http://xxx.webfunny.cn:4317）；
    1. 确认 otel.traces.exporter 配置为 otlp（而非 none）；
    1. 临时设置 otel.javaagent.logging.level=DEBUG，查看日志中是否有上报失败信息（如连接超时、权限不足）。

3. 采样率配置不生效

  • 现象：生产环境数据量过大或过小；
  • 排查步骤：
    1. 确认采样策略配置正确（otel.traces.sampler=traceidratio）；
    1. 采样率参数 otel.traces.sampler.arg 需为 0.0~1.0 之间的数值（如 0.1 表示 10%）；
    1. 开发环境建议使用 always_on（全采），生产环境避免全采（防止数据量过大）。

4. 无需监控的端点未排除

  • 现象：健康检查、Actuator 等接口的链路数据过多；
  • 解决方案：通过 otel.instrumentation.*.exclude-patterns 配置排除，不同组件的配置参数如下：
# Spring WebMVC 排除端点
-Dotel.instrumentation.spring-webmvc.exclude-patterns="/actuator/**,/health"
# Spring WebFlux 排除端点
-Dotel.instrumentation.spring-webflux.exclude-patterns="/actuator/**,/ping"
# HTTP Client 排除端点
-Dotel.instrumentation.http-client.exclude-patterns="http://xxx.com/health"

八、推荐使用方案

1. 开发环境

  • 模式：Maven 启动 + 注解增强；
  • 配置建议：otel.traces.sampler=always_on（全采，便于调试）、开启 DEBUG 日志；
  • 优势：无需手动附加命令行参数，支持断点调试，精准监控业务方法。

2. 生产环境

  • 模式：脚本启动 + Java Agent 零侵入 + 采样配置；
  • 配置建议：otel.traces.sampler=traceidratio（采样率 10%~30%）、排除健康检查等无关端点；
  • 优势：零代码侵入，配置灵活，性能开销小，支持运维自动化。

3. 混合模式（最佳实践）

  • 核心逻辑：Java Agent 自动监控基础设施（HTTP、SQL、Redis），注解增强监控关键业务方法（如订单计算、支付流程）；
  • 价值：兼顾监控全面性和业务精准性，既无需手动编写大量监控代码，又能聚焦核心业务链路。

九、总结

  1. 对接核心：通过 -javaagent 附加 OpenTelemetry Agent，配置服务名称和 Webfunny OTLP 端点即可实现零侵入监控；
  1. 灵活扩展：支持注解增强、采样配置、端点排除等个性化需求；
  1. 验证关键：启动后触发流量，通过 Webfunny 平台或本地 Jaeger 确认链路数据采集正常；
  1. 问题排查：优先查看启动日志和网络连通性，其次检查配置参数是否正确。
按本文档配置后，应用的全链路数据将实时上报至 Webfunny 监控平台，支持链路追踪、耗时分析、异常定位等功能，助力问题快速排查和系统性能优化。
 
#OpenTelemetry Java Agent
上一篇： Webfunny关于OpenTelemetry-javaAgent 对接详细文档 下一篇： 没有了
阅读全部

关于Webfunny

Webfunny专注于前端监控系统，前端埋点系统的研发。 致力于帮助开发者快速定位问题，帮助企业用数据驱动业务，实现业务数据的快速增长。支持H5/Web/PC前端、微信小程序、支付宝小程序、UniApp和Taro等跨平台框架。实时监控前端网页、前端数据分析、错误统计分析监控和BUG预警，第一时间报警，快速修复BUG！支持私有化部署，Docker容器化部署，可支持千万级PV的日活量！

  点赞 0   收藏 0
  • 一只会飞的鱼儿
    共发布63篇文章 获得8个收藏
全部评论: 0 条

    ©2020 上海快快查信息科技有限公司   沪ICP备2021030569号  版权与免责申明  版权申述