effect/opentelemetry 变更日志深度解读Effect 可观测性桥接从 v4 Beta 到 RC 的行为演进【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本篇技术指南以当前仓库内.repos/effect-smol/packages/opentelemetry/CHANGELOG.md为骨架结合该包完整源码.repos/effect-smol/packages/opentelemetry/src与测试用例系统梳理effect/opentelemetry自4.0.0-beta.0到4.0.0-rc.112的关键行为变更日志严重级别映射、Provider 生命周期与关闭语义、采样决策与 trace state 保留、指标 delta 基线与时钟对齐等。读完本文你将能理解该桥接包每一处核心行为背后的源码实现并掌握 Node/Web SDK 层的配置方式与常见坑点。一、包定位Effect 与 OpenTelemetry 之间的三信号桥effect/opentelemetry是 Effect 生态的 OpenTelemetry 集成包将 Effect 的tracing、metrics、logs三大信号导出到 OpenTelemetry SDK并对外提供NodeSdk与WebSdk两个即插即用的 Layer。包的安装方式与依赖边界记录在其 README.md 中npm install effectrc effect/opentelemetryrc从 package.json 可以看到opentelemetry/*系列 SDK 包全部以peerDependencies形式声明opentelemetry/api、sdk-trace-node、sdk-trace-web、sdk-logs、sdk-metrics、resources、semantic-conventions等且绝大多数标注为optional: true——这意味着用哪个信号装哪个包避免不必要的依赖膨胀。Node 版本要求18.0.0包导出采用扁平路径.与./*均指向src/*.ts这一导出结构正是 CHANGELOG 中4.0.0-beta.103移除显式./index入口点的结果。包的对外模块面由 src/index.ts 决定NodeSdkNode.js 环境的全信号安装 LayerWebSdk浏览器环境的全信号安装 LayerOtelTracerEffectTracer与 OTel Span 的适配器OtelLoggerEffect 日志到 OTel LogRecord 的适配器OtelMetricsEffect 指标到 OTelMetricProducer的适配器Resource资源服务元数据服务与 Layer。CHANGELOG 中大量的 Patch Changes 条目正是围绕这五个模块的行为修正下面按主题逐一展开。二、日志严重级别从内部序数到 OTel 规范 SeverityNumberCHANGELOG 中信息量最大、也最实战的变更出现在4.0.0-beta.61PR #2129Logger 改为按 OTel 规范输出SeverityNumber1–24替代原先使用 Effect 内部 log-level 序数。变更原因在 CHANGELOG 中写得很明确OtelLogger.make此前通过LogLevel.getOrdinal(level)生成severityNumber例如 Info20000、Error40000这些值落在 OpenTelemetry 日志数据模型的合法范围1–24之外Honeycomb、Datadog 等会对该字段做校验的后端会把此类值统一归类为UNSPECIFIED导致日志级别信息丢失。修复后的映射表如下原表完整继承Effect LogLevelOTel SeverityNumberTraceTRACE (1)DebugDEBUG (5)InfoINFO (9)WarnWARN (13)ErrorERROR (17)FatalFATAL (21)该映射在源码 src/OtelLogger.ts 中以logLevelToSeverityNumber函数落地并作为公共 API 导出供下游复用make构造的 Effect Logger 在每次emit时同时携带severityText保留 Effect 的级别字符串与severityNumber规范数值。对应测试位于 test/OtelLogger.test.ts通过Effect.logTrace/logDebug/logInfo/logWarning逐一断言映射结果。三、时间基准统一日志与 Span 的单调时钟对齐4.0.0-beta.11PR #1400修复了一个典型的可观测性脏数据问题此前 Logger 用Date.now()墙钟生成日志timestamp而 Tracer 用clock.currentTimeNanosUnsafe()单调时钟生成 Span 的startTime两种时钟源的漂移会导致日志时间戳早于其父 Span。修复后两者统一走单调时钟通过nanosToHrTime(clock.currentTimeNanosUnsafe())生成时间戳。在源码中可见这一设计已内化为常量约定OtelSpan.end、OtelSpan.event等 Span 生命周期方法使用 src/internal/attributes.ts 导出的nanosToHrTime将纳秒时间转为 OTelHrTime而 Logger 的make同样在 emit 时以clock.currentTimeNanosUnsafe()同时填充timestamp与observedTimestamp。跨进程分布式追踪时时间源一致性直接影响火焰图的父子关系正确性这是一处容易被忽视但影响数据质量的关键细节。四、生命周期语义forceFlush、shutdown 与 shutdownTimeoutCHANGELOG 中4.0.0-beta.104集中了三条生命周期相关修复PR #7064flush 失败时Web 与 Node 的 tracer provider 也要保证 shutdownPR #7046flush 失败时logger provider 也要保证 shutdown后续4.0.0-beta.106PR #7112Node tracer provider 的 shutdown 由配置的shutdownTimeout约束。源码中这三条语义的落地位置非常清晰src/NodeSdk.ts 的layerTracerProvider使用Effect.acquireReleaserelease 阶段执行provider.forceFlush().finally(() provider.shutdown())外层再套Effect.ignore失败不抛出、Effect.interruptible可中断与Effect.timeoutOption(config?.shutdownTimeout ?? 3000)——默认 3 秒超时src/OtelLogger.ts 的layerLoggerProvider采用完全相同的手势src/OtelMetrics.ts 的registerProducer在作用域释放时对注册过的 reader 批量执行shutdown同样带timeoutOption(options?.shutdownTimeout ?? 3000)。即使 forceFlush 失败也要保证 shutdown这一点是beta.104的实质forceFlush().finally(() shutdown())用finally把两者解耦forceFlush的 rejection 不会阻断shutdown的执行。对应测试在 test/OtelLogger.test.ts构造一个forceFlush必失败、shutdown计数递增的LogRecordProcessor断言作用域结束后shutdown恰好执行一次。此外4.0.0-beta.106PR #7118还修复了日志注解覆盖活动 Span 关联标识的问题当 fiber 上下文同时存在CurrentLogAnnotations与Tracer.ParentSpan时spanId、traceId属性不会被注解覆盖保证日志与 Trace 的关联字段优先。五、采样与传播语义Sampling 决策、Trace State 与父 Span分布式追踪桥接最容易出错的是上下文Context与采样位的传递CHANGELOG 记录了三处针对性修复4.0.0-beta.86PR #2451把通用 Effect 外部 Span 适配为 OpenTelemetry 时保留采样决策sampling decision4.0.0-beta.103PR #6902适配活动中的 OpenTelemetry 父上下文时保留 trace state 与 locality4.0.0-beta.21PR #1553修复span 永远没有父 span的问题。对应源码在 src/OtelTracer.ts 中形成了一套完整的上下文机制OtelTraceFlags与OtelTraceState两个 Context Service 专门携带采样位与 trace statemakeExternalSpan从外部SpanContext构造 EffectExternalSpan时若提供了traceFlags则按(traceFlags SAMPLED) SAMPLED判定sampled未提供时才默认 sampledtruegetOtelParent从活动 OTel Context 反查父SpanContextmakeSpanContext负责把 Effect Span 还原为 OTelSpanContext含isRemote、traceFlags、traceStatepopulateContext则在 fiber 评估时把当前 Effect Span 写入 OTel 活动上下文实现双向桥接。模块注释中点名的三个入口值得实战关注makeExternalSpan与withSpanContext用于承接外部传入的远程 Trace如消息队列、HTTP 网关透传的traceparentcurrentOtelSpan用于在任意 Effect 中取回当前 OTel Span 对象。该模块顶部注释同时给出明确警告构建外部 Span 时保留traceFlags与traceState否则采样默认视为已采样、trace state 无法传播——这与 CHANGELOG 中两条修复的动机完全对应。六、指标语义Delta 基线与多 Reader 隔离4.0.0-beta.103PR #6904修复了每个已注册 metric reader 的 delta 指标基线互相污染的问题此前多个 reader 共享同一 delta 基线导致先导出方把数据消费掉、后导出方看到的增量失真。修复后每个 reader 的 delta baseline 被隔离。源码在 src/internal/metrics.ts 的MetricProducerImpl中实现fork()而 src/OtelMetrics.ts 的registerProducer对MetricProducerImpl实例会调用self.fork()后分别setMetricProducer给每个 reader正是隔离基线的机制。OtelMetrics还提供TemporalityPreference cumulative | delta类型cumulative自固定起点累加、每个数据点依赖全部历史测量默认行为delta只报告距上次导出的增量、各区间互相独立。其layer的文档示例展示了导出 delta 指标的完整写法——用InMemoryMetricExporter(AggregationTemporality.DELTA)配合PeriodicExportingMetricReader并在OtelMetrics.layer(() reader, { temporality: delta })中声明最终Metric.counter(docs.requests, { incremental: true })的两次更新可被断言为 delta 值 2见 src/OtelMetrics.ts。七、Span 状态语义与异常记录4.0.0-beta.104PR #7069修复了wrapped span 把非 error 的 OpenTelemetry 状态误判为错误的问题。在 src/OtelTracer.ts 的makeOtelSpan中可以看到setStatus仅在status.code SpanStatusCode.ERROR时把退出状态置为Exit.die其余状态OK/UNSET均置为Exit.void从而避免把正常状态误上报为异常。同时该模块还导出一个此前变更引入的实用项Cause.prettyErrors的includeCauseInStack选项4.0.0-beta.93PR #2511用于在异常栈中携带完整 cause 链——OtelSpan.end的失败分支正依赖它做异常记录先recordException逐条记录错误再以首条错误信息设置SpanStatusCode.ERROR对仅含中断interrupt的 cause 则标记为OK并附加span.label/status.interrupted属性见 src/OtelTracer.ts。八、模块命名与 API 整理避免碰撞与简化入口两条属于结构治理的变更同样值得记录4.0.0-beta.93PR #2511为 opentelemetry 模块加前缀以避免碰撞。反映在 Context Service 的 tag 上effect/opentelemetry/Resource、effect/opentelemetry/Tracer、effect/opentelemetry/Tracer/OtelTracerProvider、effect/opentelemetry/Logger/OtelLoggerProvider等见各模块源码中的Context.Service声明确保与用户代码或其他包的同名服务隔离。4.0.0-beta.103PR #6701移除显式./index入口点。package.json的exports与publishConfig.exports中均以./index: null、./*/index: null显式禁用了index子路径统一走扁平文件路径与src/index.ts的 barrel 导出保持一致性。4.0.0-beta.44PR #1961ServiceMap模块更名为Context4.0.0-beta.32PR #1740将多处多值 Context 更新重构为Context.mutate批量更新。这类重构虽不改变外部行为但解释了 CHANGELOG 中 Effect 侧依赖版本频繁同步的原因。九、资源Resource构建环境变量与显式元数据CHANGELOG 虽未逐条描述 Resource 行为但它是NodeSdk/WebSdk两套 Layer 的公共底座值得结合 src/Resource.ts 说明Resource.layer由显式{ serviceName, serviceVersion?, attributes? }构建资源Resource.layerFromEnv解析OTEL_SERVICE_NAME与OTEL_RESOURCE_ATTRIBUTES逗号分隔的kv对环境变量再与额外属性合并Node SDK 的layer内部即调用它Resource.configToAttributes把服务元数据转换为属性映射固定写入service.name、telemetry.sdk.name effect/opentelemetry、telemetry.sdk.language依据globalThis.document是否存在自动判定nodejs/webjs仅在提供serviceVersion时才写入service.versionResource.layerEmpty空资源供不需要元数据的场景测试与最小化运行使用。Node 与 Web 的关键差异源码注释中明确声明NodeSdk的配置中resource是可选字段可从环境变量读取WebSdk的resource是必填字段且 Web 侧不读取 OTel 环境变量必须显式提供服务元数据。十、一个配置对象搞定 Node/Web 三信号综合NodeSdk.Configuration见 src/NodeSdk.ts与WebSdk.Configuration见 src/WebSdk.ts一套典型配置如下import { NodeSdk } from effect/opentelemetry import { SimpleSpanProcessor } from opentelemetry/sdk-trace-base import { OTLPTraceExporter } from opentelemetry/exporter-trace-otlp-http import { Effect, Layer } from effect const SdkLayer NodeSdk.layer(Effect.sync(() ({ resource: { serviceName: my-service, serviceVersion: 1.0.0, attributes: { deployment.environment: production } }, spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()), // metricReader: new PeriodicExportingMetricReader({ exporter }), // logRecordProcessor: [new SimpleLogRecordProcessor({ exporter })], shutdownTimeout: 5000 }))) const program Effect.logInfo(hello otel).pipe( Effect.provide(SdkLayer) )关键行为源码可证spanProcessor/metricReader/logRecordProcessor任一为空对应信号的 Layer 即为Layer.empty不会被安装src/NodeSdk.ts三信号 Layer 与 Resource Layer 通过Layer.mergeAllLayer.provideMerge组合一次provide即完成全量接入配置可以惰性求值LazyArg或 effectfulEffect方式提供支持从配置系统动态读取若使用 Node 自动插桩auto-instrumentations必须在导入被测模块之前注册——这是模块级源码注释明确标注的 gotchasrc/NodeSdk.ts若应用已有自己的 OTelTracerProvider则不必使用NodeSdk.layer直接用OtelTracer.layerGlobal/OtelTracer.layer挂接 Effect 的Tracer即可src/OtelTracer.ts。十一、版本脉络从 v4 Beta 到 RC 的演进主线CHANGELOG 记录了从4.0.0-beta.0PR #1183v4 beta 里程碑唯一的 Major Change到4.0.0-rc.112共 112 个版本的演进。将散落的条目按主题归纳可提炼出三条主线规范合规SeverityNumber映射beta.61、日志/Span 单调时钟统一beta.11、采样位与 trace state 保留beta.86 / beta.103、span 状态正确判定beta.104生命周期健壮性flush 失败仍保证 shutdownbeta.104、shutdownTimeout生效beta.106、Web 与 Node 行为对齐结构治理模块前缀防碰撞beta.93、移除./index入口beta.103、ServiceMap→Context更名beta.44、Context.mutate批量更新beta.32。每次 Patch Changes 中大量- Updated dependencies ... effect4.0.0-*条目则体现了该包与 Effect 核心库严格同步发布的版本策略effect以 workspace 版本作为 peerDependency双方版本号完全一一对应。对于使用该包的开发者这意味着升级时应保持effect与effect/opentelemetry版本一致避免 peer 依赖冲突。延伸阅读包入口与模块面.repos/effect-smol/packages/opentelemetry/src/index.tsNode/Web SDK 配置与生命周期NodeSdk.ts、WebSdk.ts桥接实现细节OtelTracer.ts、OtelLogger.ts、OtelMetrics.ts、Resource.ts行为验证测试test/OtelLogger.test.ts、test/OtelTracer.test.ts、test/OtelMetrics.test.ts【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 @effect/opentelemetry 变更日志深度解读：Effect 可观测性桥接从 v4 Beta 到 RC 的行为演进
effect/opentelemetry 变更日志深度解读Effect 可观测性桥接从 v4 Beta 到 RC 的行为演进【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本篇技术指南以当前仓库内.repos/effect-smol/packages/opentelemetry/CHANGELOG.md为骨架结合该包完整源码.repos/effect-smol/packages/opentelemetry/src与测试用例系统梳理effect/opentelemetry自4.0.0-beta.0到4.0.0-rc.112的关键行为变更日志严重级别映射、Provider 生命周期与关闭语义、采样决策与 trace state 保留、指标 delta 基线与时钟对齐等。读完本文你将能理解该桥接包每一处核心行为背后的源码实现并掌握 Node/Web SDK 层的配置方式与常见坑点。一、包定位Effect 与 OpenTelemetry 之间的三信号桥effect/opentelemetry是 Effect 生态的 OpenTelemetry 集成包将 Effect 的tracing、metrics、logs三大信号导出到 OpenTelemetry SDK并对外提供NodeSdk与WebSdk两个即插即用的 Layer。包的安装方式与依赖边界记录在其 README.md 中npm install effectrc effect/opentelemetryrc从 package.json 可以看到opentelemetry/*系列 SDK 包全部以peerDependencies形式声明opentelemetry/api、sdk-trace-node、sdk-trace-web、sdk-logs、sdk-metrics、resources、semantic-conventions等且绝大多数标注为optional: true——这意味着用哪个信号装哪个包避免不必要的依赖膨胀。Node 版本要求18.0.0包导出采用扁平路径.与./*均指向src/*.ts这一导出结构正是 CHANGELOG 中4.0.0-beta.103移除显式./index入口点的结果。包的对外模块面由 src/index.ts 决定NodeSdkNode.js 环境的全信号安装 LayerWebSdk浏览器环境的全信号安装 LayerOtelTracerEffectTracer与 OTel Span 的适配器OtelLoggerEffect 日志到 OTel LogRecord 的适配器OtelMetricsEffect 指标到 OTelMetricProducer的适配器Resource资源服务元数据服务与 Layer。CHANGELOG 中大量的 Patch Changes 条目正是围绕这五个模块的行为修正下面按主题逐一展开。二、日志严重级别从内部序数到 OTel 规范 SeverityNumberCHANGELOG 中信息量最大、也最实战的变更出现在4.0.0-beta.61PR #2129Logger 改为按 OTel 规范输出SeverityNumber1–24替代原先使用 Effect 内部 log-level 序数。变更原因在 CHANGELOG 中写得很明确OtelLogger.make此前通过LogLevel.getOrdinal(level)生成severityNumber例如 Info20000、Error40000这些值落在 OpenTelemetry 日志数据模型的合法范围1–24之外Honeycomb、Datadog 等会对该字段做校验的后端会把此类值统一归类为UNSPECIFIED导致日志级别信息丢失。修复后的映射表如下原表完整继承Effect LogLevelOTel SeverityNumberTraceTRACE (1)DebugDEBUG (5)InfoINFO (9)WarnWARN (13)ErrorERROR (17)FatalFATAL (21)该映射在源码 src/OtelLogger.ts 中以logLevelToSeverityNumber函数落地并作为公共 API 导出供下游复用make构造的 Effect Logger 在每次emit时同时携带severityText保留 Effect 的级别字符串与severityNumber规范数值。对应测试位于 test/OtelLogger.test.ts通过Effect.logTrace/logDebug/logInfo/logWarning逐一断言映射结果。三、时间基准统一日志与 Span 的单调时钟对齐4.0.0-beta.11PR #1400修复了一个典型的可观测性脏数据问题此前 Logger 用Date.now()墙钟生成日志timestamp而 Tracer 用clock.currentTimeNanosUnsafe()单调时钟生成 Span 的startTime两种时钟源的漂移会导致日志时间戳早于其父 Span。修复后两者统一走单调时钟通过nanosToHrTime(clock.currentTimeNanosUnsafe())生成时间戳。在源码中可见这一设计已内化为常量约定OtelSpan.end、OtelSpan.event等 Span 生命周期方法使用 src/internal/attributes.ts 导出的nanosToHrTime将纳秒时间转为 OTelHrTime而 Logger 的make同样在 emit 时以clock.currentTimeNanosUnsafe()同时填充timestamp与observedTimestamp。跨进程分布式追踪时时间源一致性直接影响火焰图的父子关系正确性这是一处容易被忽视但影响数据质量的关键细节。四、生命周期语义forceFlush、shutdown 与 shutdownTimeoutCHANGELOG 中4.0.0-beta.104集中了三条生命周期相关修复PR #7064flush 失败时Web 与 Node 的 tracer provider 也要保证 shutdownPR #7046flush 失败时logger provider 也要保证 shutdown后续4.0.0-beta.106PR #7112Node tracer provider 的 shutdown 由配置的shutdownTimeout约束。源码中这三条语义的落地位置非常清晰src/NodeSdk.ts 的layerTracerProvider使用Effect.acquireReleaserelease 阶段执行provider.forceFlush().finally(() provider.shutdown())外层再套Effect.ignore失败不抛出、Effect.interruptible可中断与Effect.timeoutOption(config?.shutdownTimeout ?? 3000)——默认 3 秒超时src/OtelLogger.ts 的layerLoggerProvider采用完全相同的手势src/OtelMetrics.ts 的registerProducer在作用域释放时对注册过的 reader 批量执行shutdown同样带timeoutOption(options?.shutdownTimeout ?? 3000)。即使 forceFlush 失败也要保证 shutdown这一点是beta.104的实质forceFlush().finally(() shutdown())用finally把两者解耦forceFlush的 rejection 不会阻断shutdown的执行。对应测试在 test/OtelLogger.test.ts构造一个forceFlush必失败、shutdown计数递增的LogRecordProcessor断言作用域结束后shutdown恰好执行一次。此外4.0.0-beta.106PR #7118还修复了日志注解覆盖活动 Span 关联标识的问题当 fiber 上下文同时存在CurrentLogAnnotations与Tracer.ParentSpan时spanId、traceId属性不会被注解覆盖保证日志与 Trace 的关联字段优先。五、采样与传播语义Sampling 决策、Trace State 与父 Span分布式追踪桥接最容易出错的是上下文Context与采样位的传递CHANGELOG 记录了三处针对性修复4.0.0-beta.86PR #2451把通用 Effect 外部 Span 适配为 OpenTelemetry 时保留采样决策sampling decision4.0.0-beta.103PR #6902适配活动中的 OpenTelemetry 父上下文时保留 trace state 与 locality4.0.0-beta.21PR #1553修复span 永远没有父 span的问题。对应源码在 src/OtelTracer.ts 中形成了一套完整的上下文机制OtelTraceFlags与OtelTraceState两个 Context Service 专门携带采样位与 trace statemakeExternalSpan从外部SpanContext构造 EffectExternalSpan时若提供了traceFlags则按(traceFlags SAMPLED) SAMPLED判定sampled未提供时才默认 sampledtruegetOtelParent从活动 OTel Context 反查父SpanContextmakeSpanContext负责把 Effect Span 还原为 OTelSpanContext含isRemote、traceFlags、traceStatepopulateContext则在 fiber 评估时把当前 Effect Span 写入 OTel 活动上下文实现双向桥接。模块注释中点名的三个入口值得实战关注makeExternalSpan与withSpanContext用于承接外部传入的远程 Trace如消息队列、HTTP 网关透传的traceparentcurrentOtelSpan用于在任意 Effect 中取回当前 OTel Span 对象。该模块顶部注释同时给出明确警告构建外部 Span 时保留traceFlags与traceState否则采样默认视为已采样、trace state 无法传播——这与 CHANGELOG 中两条修复的动机完全对应。六、指标语义Delta 基线与多 Reader 隔离4.0.0-beta.103PR #6904修复了每个已注册 metric reader 的 delta 指标基线互相污染的问题此前多个 reader 共享同一 delta 基线导致先导出方把数据消费掉、后导出方看到的增量失真。修复后每个 reader 的 delta baseline 被隔离。源码在 src/internal/metrics.ts 的MetricProducerImpl中实现fork()而 src/OtelMetrics.ts 的registerProducer对MetricProducerImpl实例会调用self.fork()后分别setMetricProducer给每个 reader正是隔离基线的机制。OtelMetrics还提供TemporalityPreference cumulative | delta类型cumulative自固定起点累加、每个数据点依赖全部历史测量默认行为delta只报告距上次导出的增量、各区间互相独立。其layer的文档示例展示了导出 delta 指标的完整写法——用InMemoryMetricExporter(AggregationTemporality.DELTA)配合PeriodicExportingMetricReader并在OtelMetrics.layer(() reader, { temporality: delta })中声明最终Metric.counter(docs.requests, { incremental: true })的两次更新可被断言为 delta 值 2见 src/OtelMetrics.ts。七、Span 状态语义与异常记录4.0.0-beta.104PR #7069修复了wrapped span 把非 error 的 OpenTelemetry 状态误判为错误的问题。在 src/OtelTracer.ts 的makeOtelSpan中可以看到setStatus仅在status.code SpanStatusCode.ERROR时把退出状态置为Exit.die其余状态OK/UNSET均置为Exit.void从而避免把正常状态误上报为异常。同时该模块还导出一个此前变更引入的实用项Cause.prettyErrors的includeCauseInStack选项4.0.0-beta.93PR #2511用于在异常栈中携带完整 cause 链——OtelSpan.end的失败分支正依赖它做异常记录先recordException逐条记录错误再以首条错误信息设置SpanStatusCode.ERROR对仅含中断interrupt的 cause 则标记为OK并附加span.label/status.interrupted属性见 src/OtelTracer.ts。八、模块命名与 API 整理避免碰撞与简化入口两条属于结构治理的变更同样值得记录4.0.0-beta.93PR #2511为 opentelemetry 模块加前缀以避免碰撞。反映在 Context Service 的 tag 上effect/opentelemetry/Resource、effect/opentelemetry/Tracer、effect/opentelemetry/Tracer/OtelTracerProvider、effect/opentelemetry/Logger/OtelLoggerProvider等见各模块源码中的Context.Service声明确保与用户代码或其他包的同名服务隔离。4.0.0-beta.103PR #6701移除显式./index入口点。package.json的exports与publishConfig.exports中均以./index: null、./*/index: null显式禁用了index子路径统一走扁平文件路径与src/index.ts的 barrel 导出保持一致性。4.0.0-beta.44PR #1961ServiceMap模块更名为Context4.0.0-beta.32PR #1740将多处多值 Context 更新重构为Context.mutate批量更新。这类重构虽不改变外部行为但解释了 CHANGELOG 中 Effect 侧依赖版本频繁同步的原因。九、资源Resource构建环境变量与显式元数据CHANGELOG 虽未逐条描述 Resource 行为但它是NodeSdk/WebSdk两套 Layer 的公共底座值得结合 src/Resource.ts 说明Resource.layer由显式{ serviceName, serviceVersion?, attributes? }构建资源Resource.layerFromEnv解析OTEL_SERVICE_NAME与OTEL_RESOURCE_ATTRIBUTES逗号分隔的kv对环境变量再与额外属性合并Node SDK 的layer内部即调用它Resource.configToAttributes把服务元数据转换为属性映射固定写入service.name、telemetry.sdk.name effect/opentelemetry、telemetry.sdk.language依据globalThis.document是否存在自动判定nodejs/webjs仅在提供serviceVersion时才写入service.versionResource.layerEmpty空资源供不需要元数据的场景测试与最小化运行使用。Node 与 Web 的关键差异源码注释中明确声明NodeSdk的配置中resource是可选字段可从环境变量读取WebSdk的resource是必填字段且 Web 侧不读取 OTel 环境变量必须显式提供服务元数据。十、一个配置对象搞定 Node/Web 三信号综合NodeSdk.Configuration见 src/NodeSdk.ts与WebSdk.Configuration见 src/WebSdk.ts一套典型配置如下import { NodeSdk } from effect/opentelemetry import { SimpleSpanProcessor } from opentelemetry/sdk-trace-base import { OTLPTraceExporter } from opentelemetry/exporter-trace-otlp-http import { Effect, Layer } from effect const SdkLayer NodeSdk.layer(Effect.sync(() ({ resource: { serviceName: my-service, serviceVersion: 1.0.0, attributes: { deployment.environment: production } }, spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()), // metricReader: new PeriodicExportingMetricReader({ exporter }), // logRecordProcessor: [new SimpleLogRecordProcessor({ exporter })], shutdownTimeout: 5000 }))) const program Effect.logInfo(hello otel).pipe( Effect.provide(SdkLayer) )关键行为源码可证spanProcessor/metricReader/logRecordProcessor任一为空对应信号的 Layer 即为Layer.empty不会被安装src/NodeSdk.ts三信号 Layer 与 Resource Layer 通过Layer.mergeAllLayer.provideMerge组合一次provide即完成全量接入配置可以惰性求值LazyArg或 effectfulEffect方式提供支持从配置系统动态读取若使用 Node 自动插桩auto-instrumentations必须在导入被测模块之前注册——这是模块级源码注释明确标注的 gotchasrc/NodeSdk.ts若应用已有自己的 OTelTracerProvider则不必使用NodeSdk.layer直接用OtelTracer.layerGlobal/OtelTracer.layer挂接 Effect 的Tracer即可src/OtelTracer.ts。十一、版本脉络从 v4 Beta 到 RC 的演进主线CHANGELOG 记录了从4.0.0-beta.0PR #1183v4 beta 里程碑唯一的 Major Change到4.0.0-rc.112共 112 个版本的演进。将散落的条目按主题归纳可提炼出三条主线规范合规SeverityNumber映射beta.61、日志/Span 单调时钟统一beta.11、采样位与 trace state 保留beta.86 / beta.103、span 状态正确判定beta.104生命周期健壮性flush 失败仍保证 shutdownbeta.104、shutdownTimeout生效beta.106、Web 与 Node 行为对齐结构治理模块前缀防碰撞beta.93、移除./index入口beta.103、ServiceMap→Context更名beta.44、Context.mutate批量更新beta.32。每次 Patch Changes 中大量- Updated dependencies ... effect4.0.0-*条目则体现了该包与 Effect 核心库严格同步发布的版本策略effect以 workspace 版本作为 peerDependency双方版本号完全一一对应。对于使用该包的开发者这意味着升级时应保持effect与effect/opentelemetry版本一致避免 peer 依赖冲突。延伸阅读包入口与模块面.repos/effect-smol/packages/opentelemetry/src/index.tsNode/Web SDK 配置与生命周期NodeSdk.ts、WebSdk.ts桥接实现细节OtelTracer.ts、OtelLogger.ts、OtelMetrics.ts、Resource.ts行为验证测试test/OtelLogger.test.ts、test/OtelTracer.test.ts、test/OtelMetrics.test.ts【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考