1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | edot-java-migrate-elastic-agent-skills |
| 作者/维护者 | Elastic（官方 GitHub 组织） |
| 来源链接 | https://github.com/elastic/agent-skills/tree/main/skills/observability/edot-java-migrate |
| 许可证 | Apache-2.0（数据来自 GitHub API，License 适用于整个仓库） |
| GitHub Stars / Forks | 548 / 45（数据来自 GitHub API；这两个数字属于整个 elastic/agent-skills 合集仓库，不代表本子技能个体热度，详见第 6 章说明） |
| 最新版本 | 0.1.1（SKILL.md 元数据） |
| 安装方式 | Claude Code 插件市场 / Codex 本地安装脚本 / GitHub Copilot CLI 插件市场 / 第三方 npx skills 安装器，详见第 10 章 |
2. 功能介绍与亮点
edot-java-migrate 教 coding agent 把一个已经接了经典 Elastic APM Java agent 的服务，迁移到 Elastic Distribution of OpenTelemetry（EDOT）Java agent。整套指令按顺序覆盖：清除全部经典 APM 残留（elastic-apm-agent.jar、elasticapm.properties、全部 ELASTIC_APM_* 环境变量、Maven/Gradle 里的 co.elastic.apm 依赖）→ 换装 elastic-otel-javaagent.jar，通过 -javaagent 参数或 JAVA_TOOL_OPTIONS 挂载 → 只设置三个必需环境变量（服务名、OTLP 端点、鉴权 Header）→ 明确禁止再设导出器类型变量、禁止新旧 agent 在同一 JVM 同时挂载。
亮点是把迁移中最容易踩的坑写成“禁止项”堵死：新端点不能沿用旧的 APM Server 地址（不能带 apm-server、:8200、/intake/v2/events）、旧版 ELASTIC_APM_SECRET_TOKEN 不能直接套进新的 Header 格式。它是 Elastic 官方 observability 技能组的成员，姊妹技能覆盖 Python、.NET 的对应迁移场景，以及三种语言各自的“从零埋点”技能，结构完全一致。
3. 适用场景
固定分类：DevOps 与基础设施
适合已在生产环境使用经典 Elastic APM Java agent、计划切换到基于 OpenTelemetry 标准的 EDOT Java agent 的团队——迁移涉及多处配置项一一对应替换，人工操作容易漏改或错填，agent 可照单执行并主动避开清单中列出的常见错误。
4. 跨 Agent 兼容性
- Claude Code：原生支持。仓库提供 Claude Code 插件市场安装路径（
claude plugin marketplace add+claude plugin install observability@elastic-agent-skills）。 - Codex：原生支持。仓库自带的本地安装脚本内置
codex目标，会把技能写入 Codex 的.agents/skills目录。 - OpenClaw：官方仓库与安装脚本均未点名。SKILL.md 遵循 agentskills.io 开放格式的纯文本标准，理论上可手动放入对应目录使用，但未获得官方渠道验证。
- Hermes Agent：官方仓库与安装脚本均未提及，兼容性未经验证。
5. 推荐理由
它把“从经典 Elastic APM Java agent 迁移到 EDOT”这条路径上最容易改漏、改错的配置项收进一份可直接执行的清单，替团队省下逐项核对官方文档的时间。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Elastic 官方组织出品；合集仓库整体 548 星、45 Forks 属于整个 elastic/agent-skills 仓库，不代表本技能自身热度——第三方插件目录 claudepluginhub.com 收录了该技能条目，但展示的仍是仓库整体 Stars/Forks，未提供独立于仓库的安装量或评分数据 |
| 可用性 | 7 | 步骤清晰（配置项逐条对应替换），但 SKILL.md 本身不含完整代码示例，复杂场景需点开外部 Elastic 官方迁移文档；该子技能文件自今年 3 月发布 0.1.1 版本后内容未再变更 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
① shell 命令及权限——SKILL.md 不含脚本，只指导替换 JVM 启动参数与环境变量，未索取广泛 shell 权限
② 联网外发数据——埋点数据经 OTLP 协议发到使用者自行配置的 Elastic 端点，非硬编码地址
③ API key/凭据存储——OTEL_EXPORTER_OTLP_HEADERS 携带鉴权 Token，以标准环境变量存储，未见明文硬编码
④ 可疑指令——全文通读未发现 prompt 注入或隐藏指令
⑤ 作者/组织信誉——Elastic 为知名开源可观测性公司官方账号
⑥ License——Apache-2.0，明确
⑦ 最近维护时间——所属仓库整体近日仍有提交；该子技能文件自身内容已数月未变
7. 跟同类 Skills 相比的优势
同样面向“教 coding agent 正确处理 OpenTelemetry 埋点”这个方向，dash0hq/agent-skills（Dash0 官方出品，Apache-2.0，83★）的 otel-instrumentation 子技能是一个值得对照的同类项目：
| 维度 | edot-java-migrate | dash0hq/agent-skills 的 otel-instrumentation |
|---|---|---|
| 定位 | 绑定 Elastic 后端的“经典 APM agent → EDOT”迁移指令，Java/Python/.NET 各一份 | 面向多语言的通用 OpenTelemetry 埋点最佳实践指南（trace/metrics/log 配置规则） |
| 迁移场景覆盖 | 明确处理“新旧 agent 冲突”“端点误填成旧版地址”等迁移特有陷阱 | 不针对“从某个厂商旧版 agent 切换”这类场景，聚焦新装埋点本身的质量与成本优化 |
| 后端假设 | 明确指向 Elastic 的托管 OTLP 端点，配置细节围绕 Elastic 特有的鉴权与端点格式 | 不绑定单一后端，规则文件与后端厂商无关 |
核心差异是“要不要处理存量迁移”：已经在用经典 Elastic APM Java agent、需要平滑切换到 OTel 标准的团队，edot-java-migrate 直接给出迁移路径上的对应替换清单；团队是全新埋点、尚未绑定后端厂商，dash0hq/agent-skills 的埋点质量规则更通用。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。第三方插件目录 claudepluginhub.com 已收录该技能条目（归类为 “Java backend devops”），但页面展示的 Stars/Forks 数字为仓库整体聚合值，未提供针对该子技能自身的独立评分或安装数据。
9. 其他补充
同一个 observability 技能组内还有面向 Python、.NET 的对应迁移技能，以及三种语言各自的“从零接入 OpenTelemetry”埋点技能，均采用与本技能相同的清单式结构，供已用其他语言栈、或尚未接入过 APM 的团队参考。
10. 安装使用方式
方式一（Claude Code 用户推荐）：
claude plugin marketplace add https://github.com/elastic/agent-skills
claude plugin install observability@elastic-agent-skills方式二（Codex 及其他，本地克隆）：
git clone https://github.com/elastic/agent-skills.git
cd agent-skills
./scripts/install-skills.sh add -a codex（-a 后可替换为脚本支持的其他 agent 标识，如 cursor、opencode）
方式三（GitHub Copilot CLI）：
copilot plugin marketplace add elastic/agent-skills
copilot plugin install observability@elastic-agent-skills方式四（第三方 npx 安装器）：
npx skills add elastic/agent-skills --skill observability-edot-java-migrate安装后注意：Claude Code 插件如未立即生效，需重启会话（官方仓库记录的已知问题）；技能本身是指导性文本，实际迁移仍需在项目里真实执行依赖替换、JVM 参数修改与环境变量切换，且迁移前应先在非生产环境验证新旧 agent 未同时挂载。
11. 注意事项
- 该子技能内容非常精简，不含完整代码示例，遇到复杂场景（如自定义 Span 处理器、非标准部署方式）时 agent 需要自行查阅 SKILL.md 中链接的外部 Elastic 官方迁移文档。
- 强绑定 Elastic 作为可观测性后端——明确要求填入 Elastic 的 OTLP 端点，不适合尚未确定后端厂商、希望保持中立的团队。
- 仅适用于“已在用经典 Elastic APM Java agent”的存量迁移场景；全新接入 OpenTelemetry、之前从未用过 APM 的团队应参考同组的“从零埋点”技能而非本技能。
- 是否兼容 OpenClaw、Hermes Agent 未获得官方渠道验证。