SkyWalking 探针部署的核心环节——掌握关键配置项。

正确设置探针参数是确保 Java 应用能成功上报数据、被 SkyWalking 正确识别和监控的前提。

---

🛠️ SkyWalking Java Agent 核心配置项详解

SkyWalking Agent 的配置方式有两种：

1. JVM 系统属性（推荐用于动态配置）

   -DSW_AGENT_NAME=order-service
   

2. 配置文件（agent/config/agent.config）
   适合固定配置或批量部署。

✅ 两种方式可混合使用，JVM 参数优先级高于配置文件。

---

1. 🎯 agent.service_name（服务名称）

📌 配置项（JVM 参数）：

-DSW_AGENT_NAME=your-service-name

或在 agent.config 中：

agent.service_name=your-service-name

💡 作用：

• 定义当前应用在 SkyWalking UI 中显示的服务名称。
• 用于拓扑图、调用链、指标聚合的分组依据。

✅ 最佳实践：

• 使用语义化名称：如 user-service、payment-api
• 区分环境：可加前缀 dev-user-service、prod-order-service
• 避免重复：同一集群中服务名应唯一

⚠️ 注意：

• 如果不设置，默认为 Unknown_Service + 进程 ID（不推荐）
• 建议每个微服务使用独立服务名

---

2. 🌐 collector.backend_service（OAP 服务地址）

📌 配置项（JVM 参数）：

-DSW_AGENT_COLLECTOR_BACKEND_SERVICES=oap-server:11800

或在 agent.config 中：

collector.backend_service=oap-server:11800

💡 作用：

• 指定 Agent 将数据发送到哪个 SkyWalking OAP Server。
• 使用 gRPC 协议（端口通常是 11800），性能优于 HTTP。

✅ 常见值示例：

环境	配置值
本地测试	localhost:11800
Docker 容器	oap-service:11800（服务名）
Kubernetes	skywalking-oap.observability.svc.cluster.local:11800
生产集群	负载均衡地址，如 sw-oap.prod.internal:11800

⚠️ 注意：

• 端口是 11800（gRPC），不是 12800（HTTP）或 8080（UI）
• 确保网络可达，防火墙开放端口
• 支持多个地址（逗号分隔），用于高可用：

  collector.backend_service=oap1:11800,oap2:11800
  

---

3. 📊 agent.sample_n_per_3_secs（采样率控制）

📌 配置项：

-DSW_AGENT_SAMPLE=1

或：

agent.sample_n_per_3_secs=1

💡 作用：

• 控制每 3 秒采集多少个 trace（请求）
• 0 = 关闭采样（不推荐）
• 1 = 每 3 秒采 1 个 trace（约 0.33 QPS）
• -1 = 全量采集（仅用于调试）

✅ 生产建议：

• 高 QPS 服务：设为 1 或更低
• 调试阶段：可设为 -1（全量）便于分析

---

4. 📁 logging.dir（Agent 日志目录）

📌 配置项：

-DSW_LOGGING_DIR=/var/log/skywalking/agent

或：

logging.dir=/var/log/skywalking/agent

💡 作用：

• 指定 Agent 自身的日志输出路径（如 skywalking-api.log）
• 用于排查 Agent 启动失败、上报失败等问题

✅ 建议：

• 单独目录，避免与业务日志混杂
• 在容器中挂载为 volume

---

5. 🔌 plugin.exclude_plugins（禁用插件）

📌 配置项：

plugin.exclude_plugins=redis,mysql

💡 作用：

• 禁用某些不需要监控的插件，降低性能开销
• 适用于未使用 Redis 或特定数据库的场景

✅ 示例：

# 禁用 Kafka 和 ZooKeeper 插件
plugin.exclude_plugins=kafka,zookeeper

---

6. 🧩 其他常用配置项（扩展了解）

配置项	说明
agent.namespace	多租户隔离（如 k8s namespace）
agent.authentication	OAP 认证 Token（安全场景）
agent.span_limit_per_segment	单个 Trace 最大 Span 数（防内存溢出）
propagation.mode	上下文传播模式（W3C 或 SkyWalking 原生）
agent.is_open_debugging_class	是否保存增强后的类文件（调试用）

---

📁 agent.config 配置文件示例（精简版）

# 服务名称
agent.service_name=order-service-prod

# OAP 地址（gRPC）
collector.backend_service=sw-oap.prod.internal:11800

# 采样率：每3秒采1个trace
agent.sample_n_per_3_secs=1

# 日志目录
logging.dir=/data/logs/skywalking/agent

# 禁用不必要的插件
plugin.exclude_plugins=kafka,activemq

# 设置命名空间（多租户）
agent.namespace=production

# 启用 debug 日志（谨慎开启）
# logging.level=DEBUG

---

🧪 验证配置是否生效

1. 启动应用后，检查 Agent 日志：

   tail -f /data/logs/skywalking/agent/skywalking-api.log
   

   查看是否有：

   • SkyWalking agent started 成功启动
   • Connected to collector 成功连接 OAP
   • 无 Connection refused 等错误

2. 访问 UI：

   • 服务名是否正确显示
   • 是否有调用链数据
   • JVM 指标是否上报

---

✅ 总结：核心配置项速查表

配置项	JVM 参数	作用	是否必需
agent.service_name	-DSW_AGENT_NAME	服务名称	✅ 是
collector.backend_service	-DSW_AGENT_COLLECTOR_BACKEND_SERVICES	OAP 地址	✅ 是
agent.sample_n_per_3_secs	-DSW_AGENT_SAMPLE	采样率	❌ 否
logging.dir	-DSW_LOGGING_DIR	日志目录	❌ 建议设置
plugin.exclude_plugins	-DSW_AGENT_PLUGIN_EXCLUDE_PLUGINS	禁用插件	❌ 可选