Java Agent 接入与应用示例

Java Agent 通过字节码增强采集 HTTP、RPC、数据库、JVM 等可观测数据，通常不需要改动业务代码。接入前先确认应用 JDK、框架、Agent 与 SkyWalking OAP 的版本兼容性，并在预发布环境验证性能与采样策略。

1. 下载与目录约定

你提供的实践记录使用 apache-skywalking-java-agent-8.8.0，并将解压后的 Agent 放在 /apps/skywalking-agent。团队可以使用任意受控路径，但应用启动参数、镜像构建和运维脚本应统一。

# 从 Apache 官方归档或内部制品库下载与 OAP 兼容的 Agent 版本。
wget https://archive.apache.org/dist/skywalking/java-agent/8.8.0/apache-skywalking-java-agent-8.8.0.tgz

# 解压后保留版本目录，并建立稳定软链接，便于升级和回滚。
sudo tar -xzf apache-skywalking-java-agent-8.8.0.tgz -C /apps
sudo ln -sfn /apps/skywalking-agent /apps/skywalking-agent-current

# Agent 核心文件应位于链接目录中。
ls -l /apps/skywalking-agent-current/skywalking-agent.jar

不要把下载步骤放在应用启动时执行，也不要让应用容器以 root 身份在运行期修改 Agent 文件。

2. 基础配置

Agent 配置可通过 config/agent.config、JVM 参数或环境变量注入。生产环境优先使用环境变量或部署平台配置，让同一镜像可以在不同环境中复用。

# 服务名用于服务拓扑、Dashboard 和告警归属，必须稳定且有业务语义。
agent.service_name=${SW_AGENT_NAME:checkout-api}

# 命名空间用于区分环境或租户；不要使用随机值。
agent.namespace=${SW_AGENT_NAMESPACE:production}

# OAP gRPC 地址；Kubernetes 中应写 Service DNS 名称。
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:skywalking-oap.monitoring.svc:11800}

service_name 不应包含 Pod 名、发布批次或时间戳；这些变化信息应放在 instance_name、环境标签或部署元数据中，避免服务列表和拓扑不断膨胀。

3. 启动 Java 应用

# 指向受控的 Agent 路径；启动前确认当前 JDK 和 Agent 版本兼容。
# 服务名和实例名需要分离；实例名可使用 hostname 或 Pod 名。
# OAP 地址使用 gRPC 端口；不要误填 UI 的 8080 或 OAP HTTP 的 12800。
java \
  -javaagent:/apps/skywalking-agent-current/skywalking-agent.jar \
  -Dsw.agent.name=checkout-api \
  -Dsw.agent.instance_name=${HOSTNAME} \
  -Dsw.collector.backend_service=skywalking-oap.monitoring.svc:11800 \
  -jar /apps/checkout/checkout-api.jar

4. Halo 实验示例

原始记录以 Halo 1.6.0 作为 Java Web 应用样例。该版本和默认 H2 数据库适合演示 Agent 行为，不适合作为生产博客部署方式。实验只需确保 Halo 能在 8090 启动，再以 Agent 参数重启进程。

# Halo 示例应用需要 JDK 11；实际版本应以应用官方兼容要求为准。
sudo apt update
sudo apt install -y openjdk-11-jdk

# 下载原始实验使用的 Halo 1.6.0，并以 Agent 方式启动。
mkdir -p /apps/halo
wget -O /apps/halo/halo-1.6.0.jar \
  https://github.com/halo-dev/halo/releases/download/v1.6.0/halo-1.6.0.jar

java \
  -javaagent:/apps/skywalking-agent-current/skywalking-agent.jar \
  -Dsw.agent.name=blog-halo \
  -Dsw.collector.backend_service=172.16.41.29:11800 \
  -jar /apps/halo/halo-1.6.0.jar

通过浏览器访问应用后，在 SkyWalking UI 中选择 blog-halo，确认服务、实例、Endpoint 和一条 Trace 均已出现。实验完成后应停止测试应用与不必要的对外端口。

下列截图来自原始 Halo 实验，分别展示初次配置、登录界面、已加载 Agent 的服务页面与 SkyWalking 中出现的服务。它们用于核对实验结果，生产环境不应使用默认 H2 数据库或将测试应用直接暴露到公网。

5. 接入验证与排障

# 检查 JVM 启动参数是否加载了 Agent。
ps -ef | grep -F skywalking-agent | grep -v grep

# 查看 Agent 日志目录；路径会随 Agent 版本和配置变化。
tail -n 200 /apps/skywalking-agent-current/logs/skywalking-api.log

# 在应用节点验证 OAP gRPC 端口可达。
nc -vz skywalking-oap.monitoring.svc 11800

现象	优先检查
UI 没有服务	Agent 是否加载、service_name 是否有效、OAP 地址与端口是否正确
只有入口服务	下游服务是否接入、HTTP/RPC 插件是否支持、Trace Context 是否透传
服务或实例数量暴涨	服务名是否混入 Pod 名、版本号、请求参数或随机值
应用启动变慢或内存升高	Agent 版本、插件、采样率、JVM 参数与应用框架兼容性

排障过程中不要长期启用全量采样或 Debug 日志。先用单次可控请求复现，再基于 Agent 和 OAP 日志定位问题。