SuperAPI AI 工具集

maple-effect-style

部署与运维

查看项目

更新于 10-16 00:05

技能介绍

用途:为 Effect 应用接入 Maple 的 OpenTelemetry 追踪与日志,使用 @maple-dev/effect-sdk 封装 Effect 内置的 Otlp.layerJson 导出器,并处理批处理、关闭和资源属性。

安装:npm install @maple-dev/effect-sdk effect。当前版本要求 Effect 4(effect >= 4.0.0-rc.113);Effect 3 需安装 @maple-dev/effect-sdk@effect-v3 effect @effect/platform @effect/opentelemetry,API 与导入路径相同。

主要能力:按运行时选择入口。服务端(Node.js、Bun、Deno)提供后台导出 fiber、环境变量自动检测和优雅关闭;浏览器需显式配置,内置浏览器元数据,默认录制会话回放,可用 replay: { enabled: false } 关闭;Cloudflare Workers 需在 ctx.waitUntil 中手动 flush(),惰性解析 env,在 isolate 内缓冲。

用法:服务端用 Maple.layer({ serviceName, endpoint, ingestKey, repositoryUrl }) 构建层,通过 Effect.provide 注入;自定义 span 用 Effect.withSpan,属性用 Effect.annotateCurrentSpan;Effect.log 在 span 内自动携带追踪上下文。服务端可省略 endpoint,依次读取 MAPLE_ENDPOINT、OTEL_EXPORTER_OTLP_ENDPOINT,再回退到区域公共 ingest;key 回退到 MAPLE_INGEST_KEY。Maple.layer 始终导出,缺少 key 不会禁用。Cloudflare 入口导出 make() 而非 Maple 命名空间,需在模块作用域构建一次,并在每个请求调用 ctx.waitUntil(telemetry.flush(env))。

限制:浏览器入口无环境变量回退,需显式传全部配置。不要将 Maple.layer() 与其他 tracer 层 Layer.merge,Effect 只运行一个 Tracer 服务,后者会覆盖前者;如需同时发送到多个厂商,应在现有 @effect/opentelemetry 设置中增加第二个 OTLP span processor,或在 OpenTelemetry Collector 中做 fan-out,替换现有导出器前应先询问用户。peer.service 不绘制服务边,出站调用应走 Effect 的 HttpClient。Effect.fail 与未捕获缺陷会以 Error 状态结束 span,不要用 try/catch/finally 包裹。