用途
Maple Node.js 风格用于纯 Node.js 应用（Express、Fastify、Hono、Bun 等）的 OpenTelemetry 接入，目标是把链路追踪、日志和指标发送到 Maple 采集端点。官方做法是使用 @opentelemetry/sdk-node，并通过 --import（Bun 使用 --preload）在框架代码运行之前加载 SDK，确保早期产生的遥测数据也能被采集。
引导配置
配置写在 telemetry.ts 中，导入 NodeSDK、自动埋点、OTLP HTTP 的 trace / log / metric 导出器、批处理日志处理器、周期性指标读取器和资源属性构造工具。端点为 https://ingest.maple.dev，欧盟区域为 https://ingest.eu.maple.dev；鉴权使用 public ingest key（maple_pk_…），在用户拥有之前可用 MAPLE_TEST。资源属性包括 service.name、service.version（package.json 版本、发布标签或提交 SHA）、deployment.environment.name、vcs.repository.url.full 与 vcs.ref.head.revision（可从 RAILWAY_GIT_COMMIT_SHA、GITHUB_SHA、GIT_COMMIT 环境变量读取）。SDK 配置中 traceExporter 指向 /v1/traces，logRecordProcessors 使用 BatchLogRecordProcessor 包裹的 OTLPLogExporter（/v1/logs），metricReaders 使用 PeriodicExportingMetricReader 包裹的 OTLPMetricExporter（/v1/metrics），instrumentations 使用 getNodeAutoInstrumentations()。
启动方式
以引导文件先加载的方式运行应用：node --import ./telemetry.js app.js。TypeScript 项目沿用仓库已有的加载器（tsx、ts-node/esm、原生 Bun），不要引入新的加载器。ESM 应用保留 register("@opentelemetry/instrumentation/hook.mjs", import.meta.url) 钩子调用，并把 @opentelemetry/instrumentation 加入 package.json。
版本与兼容
必须匹配已安装的 SDK 版本，否则 SDK 会正常启动但丢弃数据。当前 @opentelemetry/sdk-logs 使用 new BatchLogRecordProcessor({ exporter })；旧版本把 exporter 作为第一个参数，形式错误会导致每次日志导出在 SDK 内部抛错、无日志离开进程。metricReaders（数组）已取代 metricReader。若加入 ESM 钩子后应用启动失败，说明某个依赖与钩子不兼容，openai@4 是已知案例（提示 "you must import 'openai/shims/node'"），可在钩子中排除该包后手动埋点或升级。
引导规则
仅使用 HTTP OTLP 导出器，不使用 gRPC，因为 gRPC 会引入原生绑定、增加容器复杂度。getNodeAutoInstrumentations() 覆盖 HTTP、fetch（undici）、Express、Fastify、pg、MySQL、Redis 等；Hono（基于 @hono/node-server）等没有专属埋点的框架仍会在 HTTP 服务器层被追踪。仅在埋点导致应用出错时才禁用某项，例如禁用 @opentelemetry/instrumentation-fs。该函数会引入约 200 个包，小型服务也可以只列出所需的 @opentelemetry/instrumentation-* 包。CLI 和一次性脚本会在批处理和指标间隔触发前退出，需要在进程结束前 await sdk.shutdown()。Bun 使用同一 SDK，以 bun --preload ./telemetry.ts app.ts 运行；Bun 忽略 Node 的模块钩子，部分自动埋点不会生效，需要在自动埋点盲区手动添加 span。
路由处理器与业务操作
使用原生 API：以 tracer.startActiveSpan 配合 try / catch / finally 处理有界操作，如 maple-onboarding-style 所示。示例中从 @opentelemetry/api 获取 metrics、SpanStatusCode、trace，创建 tracer、meter 和计数器 orders.submitted，在 POST /orders 路由内开启名为 order.submit 的 span，设置 tenant.id、order.id 属性，调用 chargeOrder，成功后计数并返回，出错时 recordException、设置 ERROR 状态并重新抛出，finally 中结束 span。
日志
通过 OTLP 桥接已有日志器，不要替换它。getNodeAutoInstrumentations() 已包含 Pino、Winston、Bunyan 埋点，会向记录注入 trace_id / span_id 并转发到上面配置的 logRecordProcessors。Winston 转发还需安装 @opentelemetry/winston-transport。console.* 不会被桥接。用户日志器保留现有输出目标。
共存
如果仓库已使用 Sentry、Datadog、New Relic、Honeycomb、Logtail 或 Pino transport，应保持它们与 Maple 并存。
限制
资料未提供 Maple 的收费、价格、平台支持范围及除上述框架外的兼容性细节。