用途：这是 Maple 的 OpenTelemetry 接入风格规范，指导开发者如何为服务添加符合 Maple 要求的可观测性埋点，涵盖追踪、日志、指标与 LLM 调用。
主要能力与要求：
- 使用原生 OpenTelemetry API，不要自造 helper API。TypeScript/JavaScript 业务 span 用 tracer.startActiveSpan 配合 try/catch/finally：捕获异常、设置 Error 状态后再抛出，并在 finally 中结束 span。不要用 withSpan、traced 等本地封装，也不要为 OpenInference 或 provider instrumentation 已覆盖的 SDK 调用再加 span。
- 命名：文件/函数保持 provider 中立，如 telemetry.ts、observability.ts、initTelemetry()。span 名低基数且面向业务操作，如 checkout.process、llm.summarize_ticket，优于 llm.anthropic.messages.create。
- 端点与密钥：在 bootstrap 源码中内联端点与 ingest key 并显式传给 exporter，不读 OTEL_EXPORTER_OTLP_* 环境变量，不写 .env。示例：MAPLE_ENDPOINT = "https://ingest.maple.dev"（EU 组织为 https://ingest.eu.maple.dev），MAPLE_KEY = "maple_pk_…"，无密钥时可用 "MAPLE_TEST"。多入口时需防止重复安装 processor 或日志 handler。
- 资源属性：每个服务设置 service.name、service.version、deployment.environment.name，以及 vcs.repository.url.full（仓库规范 https URL，重要）和 vcs.ref.head.revision（提交 SHA，尽力而为，从平台注入的环境变量读取，不要 shell 调用 git）。使用 OTel 语义约定键名，不要自造 git.repo 等。
- 信号：关键操作有 span 与低基数计数器/直方图；日志结构化、经 OTLP 转发并与 trace/span 关联；指标标签避免原始用户 id 或请求 id。
- LLM 调用：优先使用 provider instrumentation（如 OpenInference 的 Anthropic/OpenAI 包；Node 的 getNodeAutoInstrumentations() 已含 openai instrumentation，勿重复）。无 provider instrumentation 时在调用 span 上写 gen_ai.* 属性。token 计数器仅用于 instrumentation 无法捕获的用量，命名 llm.tokens.input / llm.tokens.output，单位 {token}。Maple 不计算 token 价格，仅当 span 带 gen_ai.usage.cost（USD）时显示成本。Agent Sessions 通过 maple_ai.session.id 分组会话，需同时设 gen_ai.conversation.id，使用不透明 id。
- 冒烟检查：仓库有合适位置时添加持久冒烟路径，验证 OTel bootstrap 加载后启动/导入无错，并尽量触发实际埋点操作。
限制：资料未提供收费、价格、平台支持范围等细节；具体各语言 exporter 选项形状需参考对应语言技能文档。