Webfunny关于OpenTelemetry-javaAgent 对接详细文档

一、对接概述

本文档基于 OpenTelemetry 官方规范及 Webfunny 平台适配要求，详细说明 Java 应用对接 OpenTelemetry-javaAgent 探针的完整流程，包括环境准备、探针引入（开发环境 / 生产环境）、配置说明、错误上报及数据验证，适用于需要通过 OpenTelemetry 采集链路追踪、日志等数据并上报至 Webfunny 监控平台的 Java 项目（支持 Spring WebMVC、JDBC、HTTP Client 等常见组件）。

二、前置准备

（一）环境要求

Java 版本：支持 Java 8 及以上
项目类型：Java 后端项目（含 Spring Boot、Spring MVC 等主流框架）
依赖管理：Maven/Gradle（本文以 Maven 为例）

（二）核心文件下载

下载 OpenTelemetry-javaAgent.jar 探针包，官方下载地址：OpenTelemetry Java Agent 官网
记录 jar 包本地存储路径（开发环境）或服务器存储路径（生产环境），后续配置需使用。

三、开发环境对接（IDEA 中配置）

（一）引入 OpenTelemetry 依赖

在项目 pom.xml 文件中添加以下依赖，用于支持注解式链路追踪及 API 调用：

<!-- OpenTelemetry 核心 API -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.24.0</version>
</dependency>
<!-- OpenTelemetry  instrumentation 注解（用于方法链路追踪） -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    <version>1.24.0</version>
</dependency>

添加后执行 maven clean install 刷新依赖。

（二）配置 IDEA 启动参数

打开 IDEA 项目启动配置（Run/Debug Configurations）
在「VM options」中添加以下配置（参数说明见第四章）：

-javaagent:/Users/yulei/Documents/package/opentelemetry/opentelemetry-javaagent.jar
-Dotel.service.name=应用名称（如：webfunny-gear-service）
-Dotel.resource.attributes=deployment.environment=production,service.instance.id=webfunny_20251129_230724_sit
-Dotel.exporter.otlp.endpoint=http://xxx.webfunny.cn:4317
-Dotel.exporter.otlp.protocol=grpc
-Dotel.traces.exporter=otlp
-Dotel.metrics.exporter=none
-Dotel.logs.exporter=otlp
-Dotel.javaagent.logging.level=INFO
-Dotel.instrumentation.jvm-metrics.enabled=true
-Dotel.instrumentation.system-metrics.enabled=true
-Dotel.instrumentation.jdbc.enabled=true
-Dotel.instrumentation.spring-webmvc.enabled=true
-Dotel.instrumentation.http-client.enabled=true

注意：-javaagent: 后需替换为本地 opentelemetry-javaagent.jar 的实际路径。

（三）添加方法链路追踪注解

在需要监控的 Service 层、Controller 层方法上添加 @WithSpan 注解，实现错误信息及链路数据上报：

import io.opentelemetry.instrumentation.annotations.WithSpan;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Slf4j
@Service
@Transactional(propagation = Propagation.SUPPORTS, readOnly = true, rollbackFor = Exception.class)
public class GearServiceImpl extends ServiceImpl<GearMapper, Gear> implements IGearService {

    @Override
    @WithSpan // 开启该方法的链路追踪，错误信息会自动上报至 span
    public IPage<Gear> getGearPage(Gear gear, QueryRequest request) {
        Page<CdkeyConfig> page = new Page<>(request.getPageNum(), request.getPageSize());
        SortUtil.handlePageSort(request, page, "gear.type", FebsConstant.ORDER_ASC, false);
        IPage<Gear> gearPage = this.baseMapper.getGearPage(page, gear);
        return gearPage;
    }
}

（四）验证开发环境配置

启动 IDEA 项目，查看控制台输出
若打印 OpenTelemetry 版本信息及初始化日志（INFO 级别），说明探针关联成功
调用添加 @WithSpan 注解的方法，触发链路数据上报

四、生产环境对接（应用脚本启动）

（一）脚本编写

创建启动脚本 manage_opentelemetry.sh，包含探针配置、进程管理（启动 / 停止 / 重启）逻辑，脚本内容如下：

bash

#!/bin/bash

# 应用名称（自定义，如：webfunny-manage）
prog="webfunny-manage"

# ======================== OpenTelemetry 核心配置 ========================
# 服务名称（用于监控平台区分不同应用）
OTEL_SERVICE_NAME="java后端管理平台"
# 资源属性：环境标识、实例ID（实例ID建议包含时间戳，避免重复）
OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.instance.id=webfunny_20251218_224703_pro"
# 数据上报端点（Webfunny 平台 OTLP 接收地址）
OTEL_EXPORTER_OTLP_ENDPOINT="http://xxx.webfunny.cn:4317"
# 上报协议（固定为 grpc）
OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
# 追踪数据导出器（启用 otlp，即上报至配置的端点）
OTEL_TRACES_EXPORTER="otlp"
# 指标数据导出器（关闭，如需采集指标可改为 otlp）
OTEL_METRICS_EXPORTER="none"
# 日志数据导出器（启用 otlp，上报日志数据）
OTEL_LOGS_EXPORTER="otlp"
# 探针日志级别（INFO/DEBUG/WARN/ERROR，默认 INFO）
OTEL_JAVAAGENT_LOGGING_LEVEL="INFO"
# 启用 JVM 指标采集（如内存、CPU）
OTEL_INSTRUMENTATION_JVM_METRICS_ENABLED="true"
# 启用系统指标采集（如磁盘、网络）
OTEL_INSTRUMENTATION_SYSTEM_METRICS_ENABLED="true"
# 启用 JDBC  instrumentation（监控数据库操作）
OTEL_INSTRUMENTATION_JDBC_ENABLED="true"
# 启用 Spring WebMVC  instrumentation（监控 HTTP 接口）
OTEL_INSTRUMENTATION_SPRING_WEBMVC_ENABLED="true"
# 启用 HTTP Client  instrumentation（监控外部 HTTP 调用）
OTEL_INSTRUMENTATION_HTTP_CLIENT_ENABLED="true"

# ======================== 探针路径配置 ========================
# 服务器上 opentelemetry-javaagent.jar 的实际路径
OTEL_AGENT_JAR="/home/yulei/manage/opentelemetry-agent/opentelemetry-javaagent.jar"

# ======================== 工具函数：检查探针文件 ========================
check_opentelemetry_agent() {
    if [ ! -f "$OTEL_AGENT_JAR" ]; then
        echo "错误: OpenTelemetry 代理文件不存在: $OTEL_AGENT_JAR"
        echo "请确保已下载 opentelemetry-javaagent.jar 到指定位置"
        exit 1
    fi
    echo "OpenTelemetry 代理文件存在"
}

# ======================== 启动命令 ========================
start() {
    now=$(date "+%Y%m%d%H%M%S")
    # 检查探针文件是否存在
    check_opentelemetry_agent
    # 启动应用（JVM 参数可根据实际需求调整，如 -Xms/-Xmx）
    exec java \
        -javaagent:"$OTEL_AGENT_JAR" \
        -Dotel.service.name="$OTEL_SERVICE_NAME" \
        -Dotel.resource.attributes="$OTEL_RESOURCE_ATTRIBUTES" \
        -Dotel.exporter.otlp.endpoint="$OTEL_EXPORTER_OTLP_ENDPOINT" \
        -Dotel.exporter.otlp.protocol="$OTEL_EXPORTER_OTLP_PROTOCOL" \
        -Dotel.traces.exporter="$OTEL_TRACES_EXPORTER" \
        -Dotel.metrics.exporter="$OTEL_METRICS_EXPORTER" \
        -Dotel.logs.exporter="$OTEL_LOGS_EXPORTER" \
        -Dotel.javaagent.logging.level="$OTEL_JAVAAGENT_LOGGING_LEVEL" \
        -Dotel.instrumentation.jvm-metrics.enabled="$OTEL_INSTRUMENTATION_JVM_METRICS_ENABLED" \
        -Dotel.instrumentation.system-metrics.enabled="$OTEL_INSTRUMENTATION_SYSTEM_METRICS_ENABLED" \
        -Dotel.instrumentation.jdbc.enabled="$OTEL_INSTRUMENTATION_JDBC_ENABLED" \
        -Dotel.instrumentation.spring-webmvc.enabled="$OTEL_INSTRUMENTATION_SPRING_WEBMVC_ENABLED" \
        -Dotel.instrumentation.http-client.enabled="$OTEL_INSTRUMENTATION_HTTP_CLIENT_ENABLED" \
        -Xms256M -Xmx256M \
        -jar webfunny_manage-2.0.jar >/dev/null 2>&1 &
    # 保存进程 ID 到文件
    PID=$!
    echo $PID > server.pid
    # 等待 2 秒确认启动
    sleep 2
    # 验证进程状态
    if kill -0 $PID 2>/dev/null; then
        echo "启动 $prog 成功 (PID: $PID)"
        echo "OpenTelemetry 监控已启用，数据将发送到: $OTEL_EXPORTER_OTLP_ENDPOINT"
    else
        echo "启动 $prog 失败，请检查应用日志"
        rm -f server.pid
        exit 1
    fi
}

# ======================== 停止命令 ========================
stop() {
    if [ -f server.pid ]; then
        PID=$(cat server.pid)
        if kill -0 $PID 2>/dev/null; then
            echo "正在停止 $prog (PID: $PID)..."
            kill $PID
            sleep 2
            # 强制终止未停止的进程
            if kill -0 $PID 2>/dev/null; then
                echo "进程未正常停止，强制终止..."
                kill -9 $PID
                sleep 1
            fi
            echo "停止 $prog 完成"
        else
            echo "进程 $PID 未运行"
        fi
        rm -rf server.pid
    else
        echo "server.pid 文件不存在，$prog 可能未运行"
    fi
}

# ======================== 重启命令 ========================
restart() {
    echo "重新启动 $prog ..."
    stop
    sleep 2
    start
}

# ======================== 命令分发 ========================
case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    restart)
        restart
        ;;
    *)
        echo "使用方法: $0 {start|stop|restart}"
        exit 1
        ;;
esac

（二）脚本使用说明

上传脚本至服务器：将 manage_opentelemetry.sh 上传至应用部署目录
修改配置参数：
- 替换 OTEL_AGENT_JAR 为服务器上 opentelemetry-javaagent.jar 的实际路径
- 调整 OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES 为项目实际信息
- 确认 OTEL_EXPORTER_OTLP_ENDPOINT 为 Webfunny 平台提供的正确地址
添加执行权限：

chmod +x manage_opentelemetry.sh

启动 / 停止 / 重启命令：

# 启动应用（同时启用 OpenTelemetry 监控）
./manage_opentelemetry.sh start

# 停止应用
./manage_opentelemetry.sh stop

# 重启应用
./manage_opentelemetry.sh restart

五、核心配置参数说明

配置参数	说明	可选值	必填
`-javaagent:`	指定 OpenTelemetry 探针 Jar 包路径	本地 / 服务器绝对路径	是
`otel.service.name`	服务名称，用于监控平台区分应用	自定义字符串（如：user-service）	是
`otel.resource.attributes`	资源属性，包含环境、实例 ID 等	键值对格式（如：deployment.environment=production）	是
`otel.exporter.otlp.endpoint`	OTLP 数据接收端点	Webfunny 平台提供的 grpc 地址	是
`otel.exporter.otlp.protocol`	数据上报协议	grpc（固定）	是
`otel.traces.exporter`	追踪数据导出器	otlp（启用）/none（禁用）	是
`otel.metrics.exporter`	指标数据导出器	otlp（启用）/none（禁用）	否
`otel.logs.exporter`	日志数据导出器	otlp（启用）/none（禁用）	否
`otel.javaagent.logging.level`	探针日志级别	INFO/DEBUG/WARN/ERROR	否
`otel.instrumentation.*.enabled`	组件 instrumentation 开关	true（启用）/false（禁用）	否

六、数据验证与查看

数据上报逻辑：应用启动后，探针会自动采集 JVM 指标、系统指标、JDBC 操作、HTTP 接口调用等数据；添加 @WithSpan 注解的方法会生成链路追踪数据，异常信息会自动上报至 span。
数据查看方式：登录 Webfunny 监控平台，在 APM 模块的 ApmSpaninfo 表中可查看上报的链路追踪及错误数据，包括服务名称、实例 ID、调用耗时、异常堆栈等信息。

七、常见问题排查

（一）探针关联失败

现象：启动应用后无 OpenTelemetry 初始化日志
排查步骤：
1. 检查 javaagent 路径是否正确（绝对路径，无拼写错误）
2. 确认 opentelemetry-javaagent.jar 文件是否存在且完整（重新下载可解决文件损坏问题）
3. 检查 Java 版本是否兼容（需 Java 8+）

（二）数据上报失败

现象：应用启动正常，但 Webfunny 平台未接收数据
排查步骤：
1. 检查 otel.exporter.otlp.endpoint 是否正确（需包含端口，如：4317）
2. 确认服务器网络可访问上报端点（执行 telnet xxx.webfunny.cn 4317 验证连通性）
3. 查看应用日志，是否有 OpenTelemetry 上报相关错误（如连接超时、权限不足）
4. 检查 otel.traces.exporter 是否配置为 otlp（而非 none）

（三）注解 `@WithSpan` 不生效

现象：添加注解的方法未生成链路数据
排查步骤：
1. 确认 opentelemetry-instrumentation-annotations 依赖已正确引入（版本与 opentelemetry-api 一致）
2. 检查注解是否导入正确（import io.opentelemetry.instrumentation.annotations.WithSpan）
3. 确认方法是否被实际调用（仅调用后才会生成链路数据）

Webfunny关于OpenTelemetry-javaAgent 对接详细文档

一、对接概述

二、前置准备

（一）环境要求

（二）核心文件下载

三、开发环境对接（IDEA 中配置）

（一）引入 OpenTelemetry 依赖

（二）配置 IDEA 启动参数

（三）添加方法链路追踪注解

（四）验证开发环境配置

四、生产环境对接（应用脚本启动）

（一）脚本编写

（二）脚本使用说明

五、核心配置参数说明

六、数据验证与查看

七、常见问题排查

（一）探针关联失败

（二）数据上报失败

（三）注解 `@WithSpan` 不生效

关于Webfunny

关注我们

关注Webfunny公众号

热门文章

最新发布

Webfunny关于OpenTelemetry-javaAgent 对接详细文档

一、对接概述

二、前置准备

（一）环境要求

（二）核心文件下载

三、开发环境对接（IDEA 中配置）

（一）引入 OpenTelemetry 依赖

（二）配置 IDEA 启动参数

（三）添加方法链路追踪注解

（四）验证开发环境配置

四、生产环境对接（应用脚本启动）

（一）脚本编写

（二）脚本使用说明

五、核心配置参数说明

六、数据验证与查看

七、常见问题排查

（一）探针关联失败

（二）数据上报失败

（三）注解 @WithSpan 不生效

关于Webfunny

关注我们

关注Webfunny公众号

热门文章

最新发布

（三）注解 `@WithSpan` 不生效