关于 maple-onboard
为编码 Agent 提供技能，将仓库中的运行服务接入 OpenTelemetry 并把遥测数据发送到 Maple。涵盖各技术栈配置、业务信号、验证与交接，同时保留现有可观测性供应商。
主要功能
- 01梳理所有运行服务
- 02配置原生 OpenTelemetry SDK
- 03添加业务 Span、日志和指标
- 04验证启动及遥测导出
- 05保留现有可观测性供应商
适用场景
- 01为多服务仓库接入遥测
- 02为服务添加关联追踪的日志
- 03检查遥测是否成功导出
MCP 相关
该技能列出 Maple MCP 端点及连接 Maple MCP 工具的步骤。使用真实密钥时，可通过 Maple MCP 工具验证服务并审计配置。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/maple-onboard确认已加载。
详细介绍
Maple 接入
将 OpenTelemetry 跟踪、日志和指标接入仓库中的每个应用和服务，让遥测数据流入 Maple。使用原生 OpenTelemetry API 和各框架文档说明的引导方式。如果遇到难以处理的技术栈，请查阅该语言的 OTel 文档；不要猜测。
配套技能
先阅读 maple-onboarding-style（Span 模式、资源属性、框架说明、信号质量、验证），然后阅读仓库中每种技术栈对应的技能：maple-nextjs-style、maple-nodejs-style、maple-python-style、maple-effect-style、maple-go-style、maple-rust-style、maple-java-style、maple-csharp-style、maple-kotlin-style。如果这些技能未安装在此技能旁边，请从 https://raw.githubusercontent.com/MapleTechLabs/maple/main/skills/<skill-name>/SKILL.md 获取，仅获取本仓库需要的技能。没有对应技能的技术栈（Ruby、Elixir、PHP、Deno 等）使用 maple-onboarding-style 和上游 OTel 文档。调用 LLM 的服务还需使用 maple-agent-tracing。
步骤 0：区域、端点和密钥
密钥仅在签发它的区域有效；另一个区域会返回 401。
| 区域 | 接收端点 | 控制台 | MCP 服务 |
|---|---|---|---|
| US（默认） | https://ingest.maple.dev | https://app.maple.dev | https://api.maple.dev/mcp |
| EU | https://ingest.eu.maple.dev | https://app.eu.maple.dev | https://api.eu.maple.dev/mcp |
按以下顺序选择区域：提示词中的接收端点（原样使用）、提及 EU 或包含 eu.maple.dev 的 URL，否则使用 US。下文的 <dashboard> 和 <mcp> 指该区域对应的主机。
将端点和接收密钥直接写入引导源码。 密钥按项目限定且仅可写入（可将其视为 Sentry DSN）：不要使用 .env 文件、process.env.OTEL_EXPORTER_OTLP_* 或部署配置。公钥（maple_pk_…）可在任何地方安全使用，包括浏览器和移动端。私钥（maple_sk_…）仅限服务器使用。
- 提示词中有公钥： 将其直接写入每个引导文件。
- 提示词中有私钥： 仅写入服务器引导文件。浏览器和移动端代码中使用
MAPLE_TEST，并告知用户在那里替换为公钥（公钥也可用于服务器，因此一个密钥即可覆盖整个仓库）。 - 没有密钥： 将占位符
MAPLE_TEST直接写入代码。两个区域都会对此返回 200 且不存储任何内容，因此引导流程可以端到端运行。请先简要告知用户：“我将使用MAPLE_TEST作为占位符，以便引导流程能够运行。请从设置 → 数据接入（/settings?tab=ingestion）复制公用接收密钥，或先在 /sign-up 创建账户，然后在我编写的文件中搜索并替换MAPLE_TEST。”然后继续操作。不要等待用户注册。
步骤 1：梳理每项服务
从工作区清单（pnpm/bun/npm 工作区、go.work、Cargo、Python 工作区）以及 apps/* 和 services/* 中枚举服务：Web 前端、API、工作进程、后台任务、CLI、演示应用、移动应用、无服务器函数和边缘函数。仅跳过没有运行时入口的包。本轮对所有内容进行埋点；后续可能不会再有处理机会。打印清单，让用户有机会更正，然后继续操作，无需等待。
第 2 步：安装原生 OTel 并为每项服务引导初始化
使用该语言的原生 SDK：
- Node 服务：
@opentelemetry/sdk-node。Next.js 服务端：在instrumentation.ts中使用@vercel/otel。 - 浏览器前端（Vite、SPA、Next.js 客户端）：
@maple-dev/browser（追踪、错误和会话回放共用同一个session.id）。 - Expo / React Native：使用带有 OTLP HTTP 导出器的
@opentelemetry/sdk-trace-web。 - Python：
opentelemetry-sdk+opentelemetry-instrumentation-*。Go：go.opentelemetry.io/otel。Effect：@maple-dev/effect-sdk。
规则：
- 引导初始化必须在导入任何框架之前运行，并通过文档说明的钩子（
--import、instrumentation.ts、main.py顶部）执行。 - 使用 HTTP OTLP 导出器，绝不使用 gRPC。
- 服务端需要追踪、日志和指标。日志通过语言的日志桥接，经由现有日志记录器使用 OTLP 发送，从而携带
trace_id/span_id。 - 设置
service.name、service.version、deployment.environment.name、vcs.repository.url.full（服务端必需）和vcs.ref.head.revision（尽力设置）。 - 不使用封装 API（
sendMapleSpan、recordCounter、withTelemetry）：使用模块级 tracer 和 meter，以及 SDK 自带的调用。 - 使用仓库的包管理器。编辑现有配置，不要覆盖。
- 保留现有供应商（Sentry、Datadog、New Relic、Pino transports 等）。OTel 与它们并行运行。
各框架的具体说明（浏览器初始化和 CORS、Expo、Workers、FastAPI）见 maple-onboarding-style 中的“框架说明”和各技术栈的技能。
第 3 步：业务追踪、日志和指标
自动插桩是基础。阅读代码，并根据 maple-onboarding-style 中的“业务信号”添加：
- 追踪：覆盖每项关键业务操作（
order.process、payment.charge、job.<type>），将实体 ID 和结果作为属性，记录异常，失败时设置Error状态，并始终结束追踪。跳过简单辅助函数。不得包含 PII。 - 日志：采用结构化格式，并与追踪关联。仅在需要人工干预时使用错误级别。
- 指标：用计数器统计状态转换，用直方图统计延迟和大小，仅使用低基数维度。
第 4 步：验证
针对每项服务：
- 项目自身的开发或构建命令仍能正常启动，并且冒烟测试（启动或导入应用，然后通过已插桩的路由发送一个请求，或运行一条真实的 CLI 命令）会初始化引导流程。启动故障属于回归：必须修复。
- 遥测数据必须离开进程：启用导出器诊断运行，并确认关闭刷新后没有导出错误。
maple-onboarding-style中的“验证导出”说明了各语言对应的开关，以及遇到401时的处理方法。 - 使用真实密钥和 Maple MCP 工具，等待约一分钟，调用
list_services确认每个service.name，然后调用audit_setup并修复其报告的问题。使用MAPLE_TEST时跳过此项，因为它不会存储任何内容；没有 MCP 时，告知用户在“设置 → 数据摄取”中可以查看数据何时到达。
引导流程能加载却从不导出数据，就不算完成。
Step 5：交接
- 更改内容： 用 3 到 7 条简短要点说明：软件包、文件、业务跨度和指标、保留的供应商。如果添加了
@maple-dev/browser，请说明已开启会话回放并屏蔽输入（replay: { enabled: false }可关闭回放），且会在 localStorage 和 Cookie 中保存访客 ID（privacy: { persistVisitorId: false }可关闭此功能）。 - 占位符： 如果
MAPLE_TEST仍是内联值，请告知用户：“引导程序使用MAPLE_TEST作为占位符，以便顺利完成端到端安装。请从 Settings → Ingestion（/settings?tab=ingestion）复制公开写入密钥；如果你还没有 Maple 账户，请先前往 /sign-up 创建账户。然后在我写入的文件中搜索并替换MAPLE_TEST，再重新部署。如果你的组织位于欧盟区域（app.eu.maple.dev），还需将ingest.maple.dev替换为ingest.eu.maple.dev，或在 Maple SDK 中设置region: "eu"。”如果使用了欧盟端点，则省略有关欧盟的句子。 - 部署： 按照平时的方式部署。无需进行任何配置：密钥已写入源代码。
Step 6：Maple MCP
如果 Maple MCP 工具已连接到 <mcp>，则跳过（另一地区的服务会返回 401 或读取其他组织的数据）。否则，先提出运行以下命令，并在确认后执行：claude mcp add --transport http maple <mcp>。告知用户，但不要运行：Codex 使用 codex mcp add maple --url <mcp>；Cursor 和其他客户端可复制 /mcp 中的代码片段。
严格规则
- 切勿修改项目根目录之外的文件。切勿提交、推送或创建 PR。
- 切勿将私钥（
maple_sk_…）放入浏览器或移动端代码。 - 除非用户要求，否则切勿移除现有的可观测性供应商。
- 如果开发或构建命令因你添加的埋点而失败，请修复问题或报告情况。