研究报告 · 约 33,841 字 · 预计推送 4 部分

OpenTelemetry 全链路实践：trace、span、metric、log 统一接入 Python 和 TypeScript —— 横纵综合报告 未开始

目录

题记与说明

课题：《OpenTelemetry 全链路实践：trace、span、metric、log 如何统一接入 Python 和 TypeScript》
截面日期：2026-10-31
版本：最终稿（2026-10-31 按独立审读意见逐条修订后交付；本轮修订新增的一手核对见参考来源 A#5、A#7 与 B 节"修订复核"子块）
综合说明：本文由同日两份章节文件综合而成——纵轴章节《OpenTelemetry 全链路统一观测（Python/TypeScript vertical）》与横轴章节《OpenTelemetry 全链路接入 Python/TypeScript 横向对比（horizontal）》。综合时对两章之间的事实矛盾做了逐条一手核对与裁决（裁决记录见"参考来源 → A"）：包括 JS sdk-trace 合并发生在 2.0 还是 3.0、OpenTracing shim 何时移除、@opentelemetry/api-logs 是否已被移除、logs 状态在发布说明与官方文档表之间的口径差、CNCF 公告中里程碑日期的出处，以及 JS API 包两组下载量数字的口径调和。
标注约定：【一手】= 直接抓取一手页面/仓库/registry/API 得到；【半手】= 来自 GitHub issue、社区讨论或厂商文档正文，本次未打开原文复核或未复核全文；【转述】= 来自搜索引擎摘要或二手转述，未逐一打开原文。复合标注（如【转述+一手文档页互证】）表示由多个渠道共同支撑；逗号后缀（如"单一样本""多来源交叉"）为置信度限定。所有关键事实附来源链接。

TL;DR

OpenTelemetry 已于 2026-05 从 CNCF 毕业，成为可观测采集层事实标准。其"统一"按信号渐进：trace 2021 年稳定、metric 2022–2023 年稳定，log 最后收官——JS 端随 SDK 3.0 转正，Python 端 1.45.2 仍标 Development，浏览器仍是实验区。截面上"怎么采"已无战争：Datadog、Sentry 开放 OTLP 入口，eBPF 阵营（OBI）与 OTel 合流，剩余决策只有后端与成本。建议：新全栈项目直接上 OTel SDK+Collector，按信号×语言分阶段验收；JS log 可试点、Python log 观望，浏览器深度追踪暂用商业 SDK 补位。

纵轴：发展脉络（2016–2026）

阶段 0｜前史：两大观测框架分立，埋点碎片化之痛（2016–2018）

OpenTelemetry 的故事必须从它的两位"亲代"讲起：

两套 API 目标高度重合却互不兼容，用户被迫"选边站"，埋点代码随选型锁死；而 metric 与 log 两个信号更是完全没有跨厂商的事实标准。微服务与多云的普及把这个碎片化成本不断放大——这是 OpenTelemetry 诞生的原始驱动力（参见可观测数据标准演化综述：Alibaba Cloud: Evolution History of Observable Data Standards）。

阶段 1｜合并奠基：OpenTelemetry 诞生（2019–2020）

驱动因素：厂商中立化（CNCF 托管）让竞争者愿意共建；"API/SDK 分离"的设计吸收了 OpenTracing（接口）与 OpenCensus（实现）两家之长。

阶段 2｜trace 先行：规范 1.0 与两大语言的 GA（2021）

OpenTelemetry 选择了"一个信号一个信号地稳定"的路线，第一个收编的是共识最强的 tracing。

驱动因素：tracing 语义最成熟、跨厂商共识最强；TypeScript 同构全栈（Node 后端 + 浏览器前端共用 sdk-trace-web）是 JS 接入线的独特诉求；自动埋点是 Python 与 Node 两条线共同的成本杠杆。

阶段 3｜补齐 metric 与 log：四信号中的后两位（2022）

驱动因素：用户对 trace-metric-log 三者关联（日志带 trace_id）的强需求；logs 延后并选择 Bridge 路线，是因为日志生态存量巨大，"接管"不如"桥接"务实。

阶段 4｜协议与语义约定稳定：全链路真正"统一"的时刻（2023–2024）

这是容易被忽视、却是本课题最实质的一步：各语言 SDK 稳定只是"能发数据"，OTLP 与语义约定的稳定才是"发出来的数据彼此一致"。

驱动因素：后端兼容性压力（不同语言发同一种属性名才能串起全链路）；semconv 稳定化用"双写窗口"换平滑迁移，避免重蹈 OpenTracing/OpenCensus 分裂的覆辙。

阶段 5｜2.0/3.0 大版本、logs 收官与 AI 时代（2025–2026）

JS SDK 2.0（2025-03-17 发布，官方博客 Announcing the OpenTelemetry JavaScript SDK 2.0）。本次综合以 升级指南 upgrade-to-2.x.md（一手复核）为准，2.0 的破坏性变更是：Node 最低版本升至 ^18.19.0 || >=20.6.0（弃 14/16）、TypeScript 最低 5.0.4、编译目标升至 ES2022、移除浏览器 window.OTEL_* 环境配置、@opentelemetry/resources 的 Resource 类移除与 detector 统一、sdk-metrics 移除 View/Aggregation 类；稳定包版本线跳到 ≥2.0、实验包 ≥0.200。2.0 的破坏性变更清单不含以下两项：sdk-trace-node/web/base 三包合并与 OpenTracing/OpenCensus shim 移除在 2.x 升级指南中均无其事（三包仍独立列出、两 shim 均在 2.x 清单）——这两件事都发生在一年半后的 3.0（裁决记录见参考来源 A#1、A#2）。

JS SDK 3.0（2026-10-20，与 api 1.10.0、experimental 0.300.0 同日发布）。依据 v3.0.0 release notes 与仓库 CHANGELOG（均一手复核），关键变更：

@opentelemetry/api-logs 的去向：npm registry 一手复核显示该包既未被移除、也未被 npm 标记 deprecated——最新版 0.223.0（2026-10-06，2.x 维护线），3.x 线已有 0.300.0-development.0（2026-09-21）；v3.0.0 变更清单中无移除记录；其 README 写明计划："当 API 稳定后将在 @opentelemetry/api 中长期提供，本包届时废弃"。准确表述是：Logs API 已并入 @opentelemetry/api 1.10.0（稳定），api-logs 成为待退役的历史包，移除/废弃是后续步骤（网络上有"该包已随 3.0 移除"的说法，与一手证据不符，裁决记录见参考来源 A#3）。

语义约定继续收割：2025-05-02 semconv v1.33.0 使 database 等核心约定稳定（semantic-conventions releases，一手数据；对照解读：ClickHouse on OTel semconv）。

Python logs 的收官与再出发——Python 接入线最有戏剧性的一段：v1.35.0（2025-07-11）引入 event_name 顶级字段，宣布"事件就是日志"；v1.38.0（2025-10-16）为 1.39.0 将落地的 logs SDK 破坏性重命名打预告警告（changelog 原文："logs: add warnings for classes that would be deprecated and renamed in 1.39.0"，#4771；1.39.0 实际落地 [BREAKING] Rename several classes from Log to LogRecord 与移除 LogData，一手复核）；v1.39.0（2025-12-03）弃用 Events API/SDK；v1.40.0（2026-03-04）弃用 LoggingHandler，推荐改用 opentelemetry-instrumentation-logging。直至 2026-10-31，CHANGELOG.md 顶部仍写着 "We are working on stabilizing the Log signal…"，README 成熟度表标注 Logs: Development——Python 四信号中最后一块拼图仍在收尾。

AI/Agent 可观测成为新前沿：gen_ai.* 语义约定先在主仓库实验（2024 年起），2026-05-05 独立为 open-telemetry/semantic-conventions-genai（仓库创建时间，GitHub API 一手数据），覆盖 token 用量、延迟直至 agent 的任务/工具调用/记忆等约定，目前全部实验状态（GenAI metrics 规范）。

2026-05-21，CNCF 宣布 OpenTelemetry 毕业（CNCF announcement；OpenTelemetry blog: otel-graduates；cncf.io 项目页时间线另记 2026-05-11 翻转为 Graduated——公告发布日与状态翻转日，一手复核，见 A#5）。公告正文（本次综合一手复核）给出的硬数据：velocity 在 240+ 个 CNCF 项目中位居第二、仅次于 Kubernetes；JS API 包下载超 13.6 亿次、Python API 包下载超 13 亿次（口径：这是公告统计的截至 2026-04 末的滚动 12 个月累计，经 npm 下载 API 逐日数据复算为 13.69 亿、与公告吻合；它与 npm 页"周下载 1.33 亿"是不同统计时点的两个读数、并不矛盾，调和过程见 §横轴 5 与参考来源 A#7）；社区有 12,000+ 贡献者、来自 2,800+ 家公司；毕业前完成了第三方安全审计与正式治理评审。

尾声｜2026-10-31 时点的两语言对照

维度Python 接入线TypeScript/JS 接入线
trace API/SDK稳定（v1.0.0，2021-03-26 起）稳定（api 1.0.0 2021-06-10；trace SDK 1.0.0 2021-09-30 起）
metric API/SDK稳定（RC 2022-05 起；至迟 v1.19.0/2023-07 已标 Stable）API 稳定 2022-10-27；SDK 2022-11-09 起进入稳定 1.x 版本线（首版编号 1.8.0，无独立 1.0.0，npm registry 一手）
log 接入sdk._logs + LoggingHandler（已弃用）→ opentelemetry-instrumentation-logging，仍在稳定化中（README: Development）sdk-logs stable（3.0.0，2026-10-20），Logs API 并入 @opentelemetry/api 1.10.0
自动埋点opentelemetry-instrument 零代码包装器 + contrib 按库 pip 包@opentelemetry/auto-instrumentations-node（2021-04-05 起）；浏览器端仍 experimental
当前版本1.45.2/0.66b2（2026-10-29，PyPI 一手复核）3.0.0 / experimental 0.300.0（2026-10-20）

纵轴三条贯穿始终的观察：其一，OpenTelemetry 的"统一"是按信号渐进收敛的——trace（2021）→ metric（2022–2023）→ log（2023 规范、2025–2026 语言端），每个信号都走"规范先行、语言跟上、双写过渡"的同一条曲线；其二，Python 与 JS 两条接入线节奏几乎镜像，但 JS 的浏览器同构诉求（sdk-trace-web、浏览器插桩至今 "experimental and mostly unspecified"）与 Python 的 logging 桥接惯性各自塑造了独特路径；其三，真正的里程碑不是 SDK 1.0，而是 2023 年 OTLP/语义约定的稳定——它让"统一接入"从 API 层面落到数据层面，也让 2026 年的 GenAI 约定扩展成为顺水推舟。

横轴：横向对比（2026-10-31 截面）

1. 对比对象地图：六条竞争/替代路线

课题本体（下称"OTel 路线"）指：应用侧用 OpenTelemetry API/SDK（Python 端 opentelemetry-* 包，JS 端 @opentelemetry/* 包）产出 trace（含 span）、metric、log 三类信号，经 OTLP 送入 OTel Collector 或任一支持 OTLP 的后端。它在 2026 年截面上的竞品/同类/替代方案实际分成六条路线（A–F）；另将 B 的官方发行版变体（B'）单独列入下表——选型实践中它常被当作独立候选，但定位上是 B 的变体而非第七条独立路线：

路线代表一句话定位
A. 厂商私有 Agent 一体化Datadog（dd-trace-py / dd-trace-js）、New Relic装厂商 Agent，数据格式、分析、告警、定价全在一家
B. OTel 生态本体（课题本体）OTel SDK + contrib 插桩 + Collector + 任选后端厂商中立的采集层标准，后端可换
B'. OTel 官方发行版（B 的变体——预配置发行版）Elastic EDOT（Python：elastic-opentelemetry；Node：@elastic/opentelemetry-node）在上游 SDK 上包一层预配置，降低接入门槛
C. 错误监控系 + OTLP 补充Sentry以错误事件为核心，2026 年开放 OTLP trace/log 直收
D. eBPF 零侵入OBI（原 Grafana Beyla，已捐给 OTel）、Odigos、Coroot不改代码、不装 SDK，内核态抓 HTTP/gRPC/SQL 流量生成信号
E. 管线与开源后端Vector、Fluent Bit（管线）；SigNoz、Grafana LGTM/Alloy（后端）与 OTel 竞争"采集管线"位置，或作为 OTel 数据的自建后端
F. 遗留标准（历史替代）OpenTracing、OpenCensus已归档的上一代标准，用于确认"取代关系"而非活跃竞品

2. 主对比表

主对比表拆为"能力"与"成本/场景"两张 4 列表（路线为行，单元格统一为"状态符 + 一句话"），避免宽表难以阅读；自动插桩机制的逐项对比见 §6，此处不重复。

表 2-1｜信号与语言能力覆盖（✅ 完整支持 / ⚠️ 部分支持或受限 / ❌ 不支持）

路线信号覆盖（trace·metric·log·profile）Python 接入TypeScript/Node/浏览器接入
A. 厂商私有 Agent✅ 四信号全覆盖 + 私有增强（Continuous Profiler；【转述】2026-09-01 起原生保存 OTel 直方图桶）✅ 高：dd-trace-py 成熟，Agent 自动附着✅ 高：dd-trace-js，浏览器端成熟
B. OTel SDK+Collector（课题本体）✅ trace/metric/log 三信号规范完备（log 是 SDK 侧最晚稳定的信号）；⚠️ profile 实验性（规范推进中）✅ 高：SDK 1.45.2（2026-10-29），trace/metric Stable、log Development；opentelemetry-instrument 包装器 + 按库 pip 包⚠️ Node 高：SDK v3.0.0（2026-10-20）；浏览器明确标注 experimental
B'. OTel 官方发行版（B 的变体）同 B✅ 高：EDOT Python（elastic-opentelemetry）预配置✅ Node 高：@elastic/opentelemetry-node；浏览器同上游
C. Sentry⚠️ trace/log 走 OTLP 直收（开放测试中）；❌ OTLP 不收 metric；✅ profile；错误事件富信息需 Sentry SDK✅ 高：Sentry Python SDK 为主，SDK 手动/框架自动插桩✅ 高：Sentry JS SDK，浏览器端成熟
D. eBPF 零侵入完全零代码（内核态）；⚠️ 协议级 span+metric（HTTP/gRPC/SQL/Redis/Mongo），进程内细粒度不覆盖；✅ Coroot 含 CPU profile⚠️ 中：OBI 支持 Python（HTTP 分布式追踪）⚠️ 中：OBI 支持 Node.js（HTTP）
E. 管线与开源后端✅ 后端收 OTLP 全信号（LGTM 栈的 profile 走 Grafana Pyroscope）；⚠️ 管线（Vector/Fluent Bit）只搬运不生成 trace✅ 收 OTLP 即可，与语言 SDK 无关同左
F. 遗留标准⚠️ OpenCensus 含 trace+metric；❌ log；OpenTracing 仅 trace低（已归档）低（已归档）

表 2-2｜成本、中立性与适用场景

路线直接成本供应商中立性典型适用场景
A. 厂商私有 Agent按主机/用量计费；监控账单随规模增长快，是社区对比文中最常被引用的成本痛点【转述】（参 §7 Last9 对比框架）★ 私有格式与定价小团队要开箱即用、预算充足
B. OTel SDK+Collector（课题本体）✅ 0 许可费；自建后端付基础设施，托管后端付用量★★★★★ CNCF 项目，后端即插即换多语言全栈、跨云、要保留后端选择权
B'. OTel 官方发行版（B 的变体）同 B；发行版本身免费，后端按 Elastic 商业模式★★★★ 输出标准 OTLP，预配置绑定 Elastic 生态已在 Elastic 栈
C. Sentry按事件量计费★★ OTLP 是新增入口，核心仍是私有 SDK错误追踪为核心诉求
D. eBPF 零侵入✅ 开源为主（OBI 开源）★★★★ OBI 已是 OTel 官方子项目；Odigos/Coroot 输出 OTLP遗留系统/三方服务改不了代码
E. 管线与开源后端✅ 开源自托管 ≈ 基础设施成本★★★★★（后端）/ ★★★★（管线）数据主权/成本敏感的自建派；只想做好日志采集或复杂转换
F. 遗留标准n/a历史仅存量系统维护

3. 信号覆盖：四信号的"统一"完成到什么程度了

OTel 规范层面 trace/metric/log 三信号已齐，profile 作为"第四信号"仍在推进。【一手】opentelemetry.io 语言页的状态表（2026-10-31 抓取，本次综合对 JS 页做了二次复核，状态表仍为 "Traces: Stable / Metrics: Stable / Logs: Development"）：Python 语言页、JS 语言页。

这里必须如实呈现一个口径差并给出裁决：JS 端 v3.0.0 的 release notes（【一手】opentelemetry-js releases）已宣布 @opentelemetry/sdk-logs 标记 stable、Logs API 并入 @opentelemetry/api 1.10.0；而文档页状态表在抓取当日（晚于 3.0 发布 11 天）仍写 Development。本文的裁决：SDK 侧事实已转正（release notes + api CHANGELOG 双重一手证据），文档状态表属于滞后或更严的口径；但 api-logs 旧包尚未清退（见裁决记录），生态迁移未完成，文档谨慎可以理解。对选型的实际含义：JS 端 log 信号刚跨过稳定线（2026-10-20 起），Python 端 log 仍是两者中最弱的一环。"trace、span、metric、log 统一接入"这个课题目标，在 2026 年截面上 trace/metric 已无争议，log 是最后一块正在补齐的短板。

日志带 trace_id 怎么落地（课题核心需求，两语言现行姿势）：规范侧 OTLP log record 自带 trace_id/span_id 字段，SDK 生成日志记录时从当前 Context 自动取值（Python changelog v1.35.0 一手记录："sdk: use context instead of trace_id,span_id for initializing LogRecord"），因此只要日志经 OTel logs SDK 导出，关联自动完成，无需手工拼字段。Python：旧姿势 LoggingHandler 已弃用（v1.40.0），现行姿势是 opentelemetry-instrumentation-logging——自动给 stdlib logging 挂 OTel handler（readthedocs 原文："automatically instruments Python logging with a handler to convert Python log messages into OpenTelemetry logs and export them"，即"替代 opentelemetry-sdk 中已弃用的那个 handler"），并把 otelTraceID/otelSpanID/otelServiceName/otelTraceSampled 注入日志记录，OTEL_PYTHON_LOG_CORRELATION=true 可同时改写日志格式把 trace_id 打进文本（官方文档，一手复核）。TS：既有日志库经 Bridge API 桥接——@opentelemetry/instrumentation-pino 的定位原文即 "inject trace-context into Pino log records (log correlation) and to send Pino logging to the OpenTelemetry Logging SDK (log sending)"（npm 包 README，一手抓取），instrumentation-winston/instrumentation-bunyan 同理。后端按 trace_id 把日志拼回同一条 trace（SigNoz/LGTM/Datadog 均支持）。

对比项上：Datadog 的 OTLP 直收端点支持 metric/trace/log 三信号，且【转述】自 2026-09-01 起原生保存 explicit-bucket 与 exponential 直方图的原始桶（Datadog OTLP ingest 文档）；Sentry 的 OTLP 直收【转述】目前只收 traces 和 logs、不收 metrics，且错误监控的富信息（堆栈聚合、issue 分组）仍需 Sentry SDK 才能拿到（Sentry OTLP 方案页、Sentry 博客、getsentry discussion #40712）。也就是说：Sentry 走的是"OTel 管分布式追踪、Sentry SDK 管错误"的混合路线，不是全信号替代。

4. Python 接入线：版本、机制与已知坑

【一手，本次综合二次复核】PyPI 显示 opentelemetry-sdk 最新版 1.45.2（2026-10-29 发布），要求 Python >=3.10（支持 3.10–3.14），近一年节奏约每月一个 minor：1.40.0（2026-03-04）→ 1.41.0（04-09）→ 1.42.0（05-19）→ 1.43.0（06-24）→ 1.44.0（07-16）→ 1.45.0（09-25）→ 1.45.1（10-06）→ 1.45.2（10-29）（PyPI: opentelemetry-sdk）。

接入机制上，Python 走按库 pip 包 + 启动器包装路线：pip install opentelemetry-instrumentation-<lib> 逐个装插桩包，再用 opentelemetry-instrument python app.py 启动（底层是 sitecustomize 注入）。已知坑【半手，来自 GitHub issue 与社区讨论】：与宿主依赖版本冲突（如 urllib3，opentelemetry-operator#1885）；对 pex/zipapp 等密封打包方式失效（opentelemetry-python-contrib#1994）；K8s 零代码路径依赖 Operator 注入（opentelemetry-python-contrib）。与之相对，商业发行版把这一步包掉了：Elastic 的 EDOT Python（elastic-opentelemetry）是上游 SDK 的预配置发行版，主打环境变量配置开箱即用（EDOT 文档、发行版列表 opentelemetry.io/ecosystem/distributions）。

最小接入示例（零代码包装器路线）：

pip install opentelemetry-distro opentelemetry-exporter-otlp   # 发行版 + OTLP 导出器
opentelemetry-bootstrap -a install                             # 按已装框架自动补齐插桩包
export OTEL_SERVICE_NAME=my-service                            # 等价于 --service_name flag
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317       # 缺省即 localhost:4317 (gRPC)
opentelemetry-instrument python app.py                         # sitecustomize 注入启动

（命令与默认行为依据 官方 getting-started：opentelemetry-instrument 默认走 OTLP/gRPC 发往 localhost:4317，环境变量与命令行 flag（--service_name/--traces_exporter 等）等价；环境变量全量清单见 SDK 环境变量规范。）

5. TypeScript / Node / 浏览器接入线：v3.0.0 是本截面最大变化

v3.0.0 的完整变更清单见纵轴阶段 5。补充生态与运行时维度：

【一手】npm 页显示 @opentelemetry/api 1.10.0 约 1.33 亿次周下载、5,486 个直接依赖方（npm: @opentelemetry/api；npm 下载 API 复核：2026-10-23～29 当周 133,174,187）——JS 生态的 OTel API 已是"事实底座"级别的基础设施；CNCF 毕业公告亦援引 JS API 包 12 个月下载超 13.6 亿次。两组数字口径不同、并不矛盾：13.6 亿是公告统计的截至 2026-04 末滚动 12 个月累计（npm 下载 API 逐日复算为 13.69 亿，吻合），1.33 亿/周是 2026-10 当周的当前速率——期间月下载量从约 0.77 亿（2025-05）涨到 3.59 亿（2026-10），公告另载明 2026-04 创月度新高（详见参考来源 A#7）。

Node 与浏览器的成熟度差距是 TS 侧特有问题：【一手】官方文档明确警告浏览器端客户端插桩是 "experimental and mostly unspecified"（实验性且基本未规范化），Node 侧承诺支持所有活跃/维护 LTS 版本；TypeScript 类型支持遵循 DefinitelyTyped 的 2 年窗口政策（JS 语言页）。上下文传播在 Node 依赖 async_hooks 系 ContextManager（v3.0 已移除旧 AsyncHooksContextManager，保留 AsyncLocalStorageContextManager），浏览器没有对应原语，需 Zone.js 类方案——这是社区在 Angular/React 集成中反复抱怨的点【转述】。对比 Datadog（dd-trace-js）与 Sentry JS SDK：两者浏览器端都比 OTel 浏览器 SDK 成熟，是"浏览器侧暂不上 OTel"的现实理由。

最小接入示例（元包 + --import 预载路线）：

npm install @opentelemetry/sdk-node @opentelemetry/api \
            @opentelemetry/auto-instrumentations-node
// instrumentation.mjs —— 必须先于业务代码加载
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] }).start();
OTEL_SERVICE_NAME=my-service OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
  node --import ./instrumentation.mjs app.js     # TS 可用 npx tsx --import ./instrumentation.ts app.ts

（依据 官方 getting-started：插桩文件 "must be run *before* your application code"，用 --import 预载；注意不要与其他 --import/--require 冲突；官方示例默认 console 导出，生产改为在 NodeSDK 显式传 OTLP exporter 或配 OTEL_* 环境变量。）

6. 自动插桩与零侵入：三种机制的正面对比

机制PythonTypeScript/Node适用与代价
按库插桩包opentelemetry-instrumentation-{lib}，逐包安装、精确可控@opentelemetry/auto-instrumentations-node 元包（--import 预载，require-in-the-middle 打补丁）控制力最强；Python 有依赖冲突/打包坑；JS 侧注意元包靠运行时 hook require()，bundler 打包/ESM 输出场景会静默失效（见 §11）
Distro/OperatorEDOT Python；K8s Operator 注入@elastic/opentelemetry-node牺牲一点可控性换开箱即用
eBPF 零代码OBI 支持 Python（HTTP 分布式追踪）OBI 支持 Node.js（HTTP）不改一行代码；但 span 粒度停留在协议级，进程内函数级 span 与自定义 attribute 不可得；eBPF 直接写用户态内存做上下文传播目前 Go 专属【一手】（OBI 零代码文档）

值得强调的结构性事实：eBPF 阵营与 OTel 已经合流而非对峙——Grafana 把 Beyla 捐给了 OpenTelemetry 项目，更名为 OBI（OpenTelemetry eBPF Instrumentation），2025-11 达 alpha，由 Grafana、Splunk、Coralogix、Odigos 等共同推进【转述+一手文档页互证】。Odigos、Coroot 的输出也都是 OTLP。所以"零侵入 vs OTel"在 2026 年已是伪命题：零侵入是 OTel 信号的另一种发射方式。

7. 成本模型：三种账单结构

采样与数据量：账单最大的可控变量。 三种账单结构里的"用量"都由数据量驱动，而 trace 数据量最直接的可控杠杆是采样：头部采样用规范标准环境变量 OTEL_TRACES_SAMPLER=parentbased_traceidratio + OTEL_TRACES_SAMPLER_ARG=0.25（0–1 取值；默认 parentbased_always_on，SDK 环境变量规范，一手复核），在应用侧按比例丢弃；要按"错误/慢请求优先保留"做精细裁决，用 Collector 的 tail_sampling processor 在尾部采样（opentelemetry-collector-contrib/processor/tailsamplingprocessor）。metric 不能采样（控量靠聚合与基数管理），log 控量靠级别与过滤。自建后端时，采样率决定存储与算力规模；托管后端时，直接决定按量账单——所以 §后文的验收清单应把采样策略当作与后端选型同级的决策项。

8. 管线层：Collector vs Vector vs Fluent Bit

【转述】2026 年的社区共识（Parseable 2026-02、OpenObserve 2026-08 等多篇对比）：OTel Collector（Go）胜在厂商中立的多信号管线（log+metric+trace 一套配置），代价是资源占用高于 Fluent Bit，尤其挂载大量 contrib 组件时；Fluent Bit 胜在轻量日志采集，现已原生收发 OTLP，可在日志场景替代 Collector；Vector 强在复杂转换与路由。对本课题的含义：Python/TS 应用侧出 OTLP 后，管线层有真实的选择空间，Collector 不是唯一解，但它是唯一"三信号一套"的中立解。

最小 Collector 配置（OTLP 入口 + 三信号管线）：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317    # 各语言 SDK 缺省发往的 gRPC 入口
      http:
        endpoint: 0.0.0.0:4318    # 浏览器等不支持 gRPC 的客户端走 HTTP
exporters:
  debug: { verbosity: detailed }  # v0.86.0 之前叫 logging
service:
  pipelines:
    traces:  { receivers: [otlp], exporters: [debug] }
    metrics: { receivers: [otlp], exporters: [debug] }
    logs:    { receivers: [otlp], exporters: [debug] }

快速起容器：docker run -p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 otel/opentelemetry-collector:0.164.0（quick-start：4317 为 "OTLP over gRPC, the default for most SDKs"、4318 为 "OTLP over HTTP"；配置块依 configuration 文档 的 otlp receiver + pipelines 示例摘编）。

9. 后端层：开源与商业后端在 OTel 面前平权

SigNoz（ClickHouse 存储，OTel 原生，logs/metrics/traces 单面板）与 Grafana LGTM（Mimir/Loki/Tempo + Grafana + Alloy 采集器）是自建路线两大代表【转述+社区共识】（euro-stack on SigNoz、Grafana blog）；商业侧 Datadog、New Relic、Honeycomb、Elastic 全部提供 OTLP 入口（Honeycomb 与 New Relic 在 2026-09 的第三方对比中 trace/span 支持评分持平【转述，单一样本，仅供参考】）。最说明问题的样本是 Lightstep/ServiceNow Cloud Observability：2026-03-01 停止支持【转述，多来源交叉，未能打开官方 EOL 通知原文】——它曾是最"OTel 原生"的商业后端，其退场恰恰演示了课题本体的核心价值：SDK 插桩不动，换一个 Exporter 端点即可迁移。

10. 遗留标准：替代关系已终结

OpenTracing 与 OpenCensus 于 2019-05 宣布合并为 OpenTelemetry；OpenCensus 仓库 2023-07-31 归档，OpenTracing 同样进入归档维护【转述】（logz.io 综述 等）。JS v3.0.0 移除 OpenTracing shim（一手复核）是这条历史线收尾的最新注脚——旧系统迁移仍会碰到，新项目不存在选型问题。

11. Python vs TypeScript 双语差异专项表（课题特有轴）

维度PythonTypeScript/JavaScript
最新版本（2026-10-31 一手核实）sdk 1.45.2（2026-10-29），月度 minor 节奏SDK v3.0.0（2026-10-20），api 1.10.0；2025-03 出 2.0，2026-10 出 3.0
运行时支持Python >=3.10（至 3.14）Node >=22.15.0（v3 起）；浏览器实验性；TS 类型随 DT 2 年窗口
trace / metricStable / StableStable / Stable
log文档页标 Development（最弱项；LoggingHandler 已弃用，转向 instrumentation-logging）v3.0.0 起 sdk-logs 标记 stable、Logs API 并入 api 包（文档页滞后标 Development）
自动插桩逐库 pip 包 + opentelemetry-instrument 包装器（sitecustomize）；pex/zipapp 等密封打包失效；依赖版本冲突是高频坑元包 @opentelemetry/auto-instrumentations-node + --import 预载；自动插桩靠运行时 hook require()（require-in-the-middle）打补丁，bundler 打包/ESM 输出场景会静默失效（contrib issue #2390 "Instrumentation not working"）【半手】
上下文传播原语同步/异步统一（线程 + asyncio，SDK 内建）Node 靠 async_hooks 系 ContextManager（v3.0 收敛为 AsyncLocalStorage）；浏览器无等价原语（Zone.js 类方案），是浏览器端不成熟的根因
生态护城河AI/数据栈（官方 contrib 53 个插桩包持续增加【一手：GitHub 目录清点，2026-10-31】；LangChain 等 AI 框架插桩由社区发行补充，如 PyPI opentelemetry-instrumentation-langchain）npm 周下载 1.33 亿、5,486 依赖方，事实底座（下载量口径见 A#7）
大版本风格1.x 内月度 minor，无破坏性大版本2025-03 出 2.0、2026-10 出 3.0，激进清退（Node 版本、包合并、shim 移除）
同类竞品的相对优势dd-trace-py 与 EDOT Python 均以"少配置、快接入"为卖点（厂商定位口径，未做实测对比；发行版定位见 opentelemetry.io/ecosystem/distributions）dd-trace-js、Sentry JS 的浏览器端显著成熟于 OTel 浏览器 SDK

一句话结论：两个语言的 trace/metric 完成度已对齐，差异集中在 log 稳定性（JS 刚转正、Python 未转正）、大版本节奏（JS 激进清退 vs Python 平滑月度）与"浏览器"这一 Python 天然没有的战场。

交叉洞察：两轴结合说明了什么、对用户意味着什么

洞察 1｜"统一"是三层动态过程：协议先行、信号渐进、语言异速

纵轴显示，OpenTelemetry 的"统一"从来不是一次到位，而是三层叠加的过程：协议层（OTLP 2023 年锁定，所有语言同时受益）、信号层（trace 2021 → metric 2022–2023 → log 2023 规范/2025–2026 语言端，逐个收敛）、语言层（每个信号在每个语言的落地时间不同，JS log 2026-10-20 转正、Python log 至今 Development）。横轴则给出这三层在 2026-10-31 截面上的"读数"：trace/metric 双语言 Stable、log 一边刚转正一边未转正、浏览器整体实验区。

对用户的判断：不要问"我们上没上 OTel"，要问"哪个信号在哪个语言上到了哪一层"。落地验收必须按"信号 × 语言"开二维清单，而不是按"上了 OTel"一刀切。课题标题里那个"统一"，2026 年的真实含义是"API/协议统一，各信号各语言的完成度参差"。

洞察 2｜采集层战争已经结束，战场移到后端与账单

两轴在此完全互证。纵轴的时间线：合并（2019）→ 标准收敛（2021–2023）→ CNCF 毕业（2026-05）；横轴的截面证据：Datadog 铺设三条 OTLP 入口、Sentry 开放 OTLP trace/log、Beyla 干脆捐给 OTel 变成 OBI、Lightstep 退场后客户靠换 Exporter 端点迁移——所有玩家要么变成 OTel 的"后端"，要么变成它的"发射器"。"怎么采"已无战争，"采上来放哪、按什么计费"才是战场。

对用户的判断：在 Python/TS 项目里纠结"要不要上 OTel"已经没有意义——插桩层投资不会浪费；有意义的决策只剩两个变量：后端选择（自建 SigNoz/LGTM vs 托管）与成本结构（基础设施+工程时间 vs 按量账单）。

洞察 3｜真正的里程碑是 2023 年的 OTLP/语义约定，不是 SDK 1.0

纵轴的证据：各语言 SDK 1.0（2021）只解决"能发数据"；OTLP stable（2023-04）+ proto v1.0.0（2023-07）+ HTTP semconv 稳定（2023-11）+ semconv 独立仓库，才解决"发出来的数据彼此一致"。横轴的证据：正因为协议与属性名统一了，后端层才出现"平权"（SigNoz/LGTM/商业后端全部收 OTLP）、eBPF 阵营才可能"合流"（发同一协议）、Lightstep 客户才可能"换端点即迁移"。两轴拼起来才能看清：2023 年那组不起眼的协议发布，才是全链路统一观测的真正分水岭；2021 年的 SDK 1.0 只是入场券，2026 年的毕业只是追认。

洞察 4｜"稳定"有三层：release notes、官方文档、生态包——JS logs 案例的三层不同步

JS 端 log 信号在 2026-10-31 这一天同时呈现三种状态：release notes 说 sdk-logs 已 stable（一手），官方文档状态表仍写 Development（一手），api-logs 旧包既未废弃也未移除（npm registry 一手）。这不是"哪个对"的问题，而是成熟度本身分三层：代码事实（release）、文档口径（docs）、生态清退（npm 包生命周期）。评价任何 OTel 信号"能不能放心上生产"，应该三层都看：代码已稳定 + 文档未更新 → 可试点但自担文档缺口；生态旧包未清 → 迁移路径上还有一次依赖调整。

本报告写作过程本身就是这个洞察的注脚：对同一事实（api-logs 是否被移除、sdk-trace 合并发生在哪个大版本），二手转述与社区记忆会给出相互矛盾的表述（裁决记录见参考来源 A#1–#3），唯有回到 release notes、CHANGELOG、npm registry 三个一手层级才能裁决。对用户的方法论：引用 OTel 的任何"稳定"结论前，先核对三层来源的日期与口径。

洞察 5｜两个语言的接入成本分布不对称，验收标准必须分开写

纵轴显示两条线节奏"几乎镜像"，但横轴揭开了镜像下的分叉：Python 的坑集中在打包与依赖（pex/zipapp 密封打包失效、urllib3 类版本冲突、Operator 依赖），TS 的坑集中在运行时分裂（Node/浏览器双世界、浏览器无上下文传播原语、大版本激进清退——一年半内 2.0、3.0 两个大版本，Node 最低版本两次抬升到 >=22.15.0）。Python 是平滑月度 minor 无破坏性大版本，JS 是用大版本一次性清偿历史包袱。

对用户的判断：不能用同一份"OTel 接入验收标准"套两个语言。Python 项目评审应加：打包链兼容性（pex/zipapp/PyInstaller）、依赖冲突扫描、K8s Operator 注入路径；TS 项目评审应加：Node 版本升级预算（>=22.15）、bundler 兼容（v3.0 起浏览器构建改用 #platform 子路径导入，要求 bundler 支持 package.json imports/exports 字段——webpack ≥5.54、Jest ≥29.4、React Native/Metro ≥0.81.3；深导入 build/src/... 也不再解析。来源：v3.0.0 release notes 原文 "webpack needs 5.54 or later" 与 3.x 迁移指南，均为一手复核）、浏览器端范围明确排除或降级。

洞察 6｜零侵入与 SDK 是金字塔两层，不是二选一

横轴的机制对比表在纵轴的时间线里能得到更深解释：OBI（Beyla）之所以"捐给 OTel"，正因为 OTLP/semconv 稳定后，零侵入方案与 SDK 方案发的是同一种数据——eBPF 从 OTel 的竞争者变成了 OTel 信号的另一种发射方式。金字塔结构由此成立：OBI/Coroot 给全栈打底（协议级 span+metric，覆盖改不动的遗留与三方服务），OTel SDK 在关键服务上做增量（函数级 span、自定义属性、metric 维度），两层输出同一条管线。注意边界：eBPF 直接写用户态内存做上下文传播目前 Go 专属【一手】，Python/Node 的零侵入方案拿不到进程内细节，增量层不可省。

洞察 7｜AI 时代打开第二增长曲线，Python 生态恰好站上位

纵轴的收官事件是 GenAI semconv 独立成仓（2026-05-05）与 CNCF 毕业（2026-05-21）——前者说明 OTel 正从"微服务观测标准"升级为"AI 系统观测标准"（token、延迟、agent 任务/工具调用/记忆），后者说明采集层标准之争正式落幕。横轴补上语言分布：Python 的生态护城河恰在 AI/数据栈——官方 contrib 53 个插桩包以 Web 框架与 DB 为主（FastAPI、Django 等【一手：GitHub 目录清点】），LangChain 等 AI 框架插桩由社区发行补充（PyPI opentelemetry-instrumentation-langchain）。两轴结合的判断：LLM/Agent 应用的观测需求会优先沿 Python 线落地，今天就可以用 OTel 接入 gen_ai.* 信号，但全部约定处于实验状态，应有随时随 semconv 演进调整的心理预期（参考 semconv HTTP 双写迁移的先例：破坏性属性改名会用 OTEL_SEMCONV_STABILITY_OPT_IN 式的过渡开关）。

给用户的选型矩阵与分阶段验收清单

场景 → 推荐路线：

场景推荐路线理由
全新 Python(FastAPI/Django) + TS(Next.js/Node) 全栈，要跨云、怕锁定OTel SDK + Collector + 任选后端（自建 SigNoz/LGTM 或托管）采集层一次投入，后端即插即换（Lightstep 案例）
小团队、无运维、预算可接受Datadog 一体化（可选走 OTLP 入口保留退路）开箱即用最强；但注意"不同接入路径产品能力不同"的官方告示
核心诉求是错误追踪，trace 只是辅助Sentry SDK 为主 + OTLP trace/log 直收补充Sentry 的错误聚合能力 OTel 生态没有等价物；metric 别指望 Sentry
存量系统/三方服务改不了代码OBI / Odigos / Coroot（输出仍是 OTLP）零代码拿协议级 span+metric，进程内细节用 OTel SDK 逐服务补
数据主权/成本敏感SigNoz 或 LGTM 自建 + Collector（或 Vector/Fluent Bit 管日志）0 许可费换基础设施投入；日志量大时 Fluent Bit 前置
已在 Elastic 栈EDOT Python/Node → Elastic发行版降低接入门槛，且兼容上游 OTel
浏览器端深度追踪暂用 Sentry JS / dd-trace-js，或接受 OTel 浏览器 experimental官方自认 "experimental and mostly unspecified"

按"信号 × 语言"的验收清单（2026-10-31 口径）：

  1. trace：双语言立即验收生产。Python/Node 均多年 Stable，semconv HTTP 已稳定，OTEL_SEMCONV_STABILITY_OPT_IN 双写窗口可收口。
  2. metric：双语言立即验收生产。JS 注意 2.0 移除了 View/Aggregation 类，老代码升级 3.x 时同步改。
  3. log（Node/TS）：可试点。sdk-logs 3.0.0 起稳定、Logs API 并入 @opentelemetry/api；新代码直接从 @opentelemetry/api 取 Logs API，不要再引入 api-logs（待退役包）；文档状态表滞后，以 release notes 为准。
  4. log（Python）：观望或小范围试点。仍标 Development；LoggingHandler 已弃用（v1.40.0），新代码用 opentelemetry-instrumentation-logging；Events API/SDK 已弃用（v1.39.0），不要基于它建新依赖。日志-链路关联走 §3 所述的 instrumentation 注入路径。
  5. 浏览器：整体降级为"尽力而为"。官方自认实验性且未规范化；深度追踪先用商业 SDK 补位，或只做最基础的页面加载 trace。
  6. GenAI 信号：LLM 应用现在就接 gen_ai.*，但按实验状态管理——固定 semconv 版本、升级时跑属性名 diff。
  7. 后端迁移预案：以 Lightstep 退场（2026-03-01）为假想演练——确认自家 SDK/Collector 配置中 Exporter 端点可一键切换，锁定只允许发生在后端层，不允许回流到插桩层。
  8. 采样策略：与后端选型同级的成本决策项（§7）——头部采样 OTEL_TRACES_SAMPLER 起步，精细化需求再上 Collector tail sampling。

参考来源

A. 两章节矛盾的裁决记录（本次综合新增的一手核对，2026-10-31；#5、#7 于修订版更新）

#矛盾点纵轴初稿说法横轴初稿说法裁决与证据
1sdk-trace-node/web/base 合并为 @opentelemetry/sdk-trace 的版本记在 JS SDK 2.0（2025-03）名下记在 v3.0.0（2026-10-20）名下裁决：发生在 3.0。一手：v3.0.0 release notes（"The sdk-trace-base, sdk-trace-web, and sdk-trace-node packages have been replaced by the @opentelemetry/sdk-trace package"）+ upgrade-to-2.x.md（2.x 中三包仍独立列出，无合并条目）。本报告已按 3.0 更正
2OpenTracing shim 移除的版本记在 2.0 名下（"移除 OpenCensus/OpenTracing 兼容垫片"）记在 v3.0.0 名下裁决：发生在 3.0。一手：upgrade-to-2.x.md 中 @opentelemetry/shim-opentracing 2.0.0、shim-opencensus 0.200.0 仍在 2.x 清单；v3.0.0 release notes 有 "remove the @opentelemetry/shim-opentracing package"
3@opentelemetry/api-logs 是否随 3.0 被移除称"独立的 api-logs 包被移除"同称"移除了独立的 api-logs 包"裁决：未被移除、未废弃。一手：npm registry（https://registry.npmjs.org/@opentelemetry/api-logs，本次 curl 抓取）最新 0.223.0（2026-10-06）、无 deprecated 标记、3.x 线有 0.300.0-development.0；v3.0.0 CHANGELOG 小节无移除记录。准确表述：Logs API 已并入 @opentelemetry/api 1.10.0（api/CHANGELOG.md PR #4862），api-logs 为待退役历史包
4JS logs 的稳定状态依据 release notes 称已稳定指出文档状态表仍标 Development、不做裁决裁决：两层各自如实、并行呈现。一手：release notes "chore(sdk-logs): mark @opentelemetry/sdk-logs as stable [#7143]"；JS 语言页（本次二次抓取）状态表仍为 "Logs: Development"。判定为文档滞后/口径更严，本报告以 release notes 为代码事实、文档表为官方口径
5CNCF Sandbox（2019-05-07）与 Incubating（2021-08-26）日期出处称出自 CNCF 毕业公告中的项目时间线未涉及裁决：已定位真实出处（修订版更新）。修订时抓取 cncf.io 项目页 时间线，一手记载："OpenTelemetry was accepted to CNCF on May 7, 2019"、"moved to the Incubating maturity level on August 26, 2021"、"moved to the Graduated maturity level on May 11, 2026"。而 CNCF 毕业公告 正文只含公告日（2026-05-21）、velocity 排名、下载量与贡献者数据，未含 Sandbox/Incubating 日期。两日期改引项目页时间线，置信度由"中等"上调为一手；正文中"宣布毕业（2026-05-21，公告日）"与"状态翻转（2026-05-11，项目页）"分别表述、并不冲突
6Python metrics 翻转为 Stable 的精确版本只给出已验证区间未涉及裁决：维持区间表述（RC 2022-05-17 → 至迟 v1.19.0/2023-07-13 已标 Stable），未逐版本回溯，不虚构精确翻转点
7JS API 下载量两组数字（"12 个月超 13.6 亿" vs "周下载约 1.33 亿"）引 CNCF 公告"过去十二个月下载超 13.6 亿次"引 npm 页"约 1.33 亿次周下载"裁决：同一计数器、不同统计时点，两数并存且不矛盾（修订版新增）。一手复算：npm 下载 API 逐日数据（2025-05-01～2026-10-30，https://api.npmjs.org/downloads/range/...）按月汇总为 0.77 亿（2025-05）→ 1.03 亿（2025-10）→ 2.03 亿（2026-04）→ 3.59 亿（2026-10）的陡增曲线；截至 2026-04-30 的滚动 12 个月累计 = 1,368,778,989 ≈ 13.69 亿，与公告"超 13.6 亿"精确吻合（公告 2026-05-21 发布，且载明 2026-04 创月度下载新高）；而 133,174,187/周（2026-10-23～29，downloads/point/last-week API）是当前速率。引用时必须注明时点：公告数字是"截至 2026-04 的 12 个月累计"，周数字是"当周速率"，用周×52 直接年化会得到 ~69 亿/年的高估。当前滚动 12 个月累计（至 2026-10-30）为 26.65 亿。另：npm 计数器本身含 CI/镜像等自动化重复拉取，只宜做趋势与相对比较，不宜当"用户数"

另辟谣一条：网络流传"Python logs 于 v1.12.0（2022）稳定"，与一手证据（opentelemetry-python CHANGELOG 无此记录、main 分支 README 仍标 Development）矛盾，本报告不采信。

B. 一手来源（两章节内 + 本次综合抓取 + 修订版复核，2026-10-31）

规范/协议/语义约定：

opentelemetry-js 仓库（本次综合直接抓取核对）：

opentelemetry-python：

npm/registry（两章节一手 + 本次综合 + 修订版复核）：

官方文档与博客：

CNCF/历史：

修订版新增（bundler 失效样本）：

C. 转述来源（搜索摘要，未逐字核对原文）

D. 方法与局限（如实声明）

  1. 本报告由两份章节文件综合而成；两章节的一手抓取均完成于 2026-10-31 当天，本次综合另对 6 处关键事实做了复核（见 A 节），全部为直接抓取。修订版又对约 14 项事实/来源补做一手复核（新增裁决见 A#5、A#7，来源清单见 B 节"修订版"标注条目），同样全部为直接抓取。
  2. 标注【转述】的事实来自搜索引擎结果摘要，未逐一打开原文核对；其中 Lightstep/ServiceNow EOL（2026-03-01）未能找到并打开官方 EOL 通知原文，仅多来源交叉。
  3. "opentelemetry-python SDK 月下载 2.24 亿（2026-01）"与"CVE-2026-114603 影响 1.45.1 之前的 opentelemetry-python"两条均来自搜索摘要，未核实原始出处，不作为本报告结论依据，仅提示 1.45.2 已是 10-29 最新补丁版（PyPI 一手核实）。
  4. Honeycomb/New Relic "72/100 持平"评分来自单一第三方对比站，样本与方法不明，仅作参考；"2026 年新云原生插桩 ~95% 采用 OTel"属预测口径，非实测数据。
  5. 本截面未实测任何方案的性能/资源占用（所有性能表述引自公开对比文），"Collector 资源占用高于 Fluent Bit"为二手结论。
  6. CNCF Sandbox（2019-05-07）与 Incubating（2021-08-26）两个日期：修订版已定位到 cncf.io 项目页时间线一手出处（见 A#5），原"未取得原始公告文本、置信度中等"的局限解除。
  7. 本报告为最终稿；清单、nightly-log 与维护状态由脚本统一串行提交，本文不触碰。
  8. 修订版新增的最小接入示例、trace-log 关联与采样段落，依据官方 getting-started/规范/插桩文档撰写（来源见 B 节），属"文档核验级"——未在本机实际跑通端到端链路，命令与默认行为以官方文档当日版本为准。

思考题（读完后想一想，参考答案可展开）

  1. 报告为什么说 OpenTelemetry 的「统一」是按信号渐进收敛的？截至 2026-10-31，trace/metric/log 三信号在 Python 与 JS 两端的稳定状态分别如何？
    参考答案

    统一按信号逐个收敛：trace 2021 年稳定、metric 2022–2023 年稳定、log 最后收官。截面上双语言 trace/metric 均 Stable；log 差异最大——JS 端 sdk-logs 随 SDK 3.0.0（2026-10-20）标记 stable、Logs API 并入 @opentelemetry/api 1.10.0（文档状态表滞后仍写 Development），Python 端 1.45.2 的 README 仍标 Logs: Development。因此报告建议 JS log 可试点、Python log 观望。

  2. 采集路线上，OTel SDK+Collector、厂商私有 Agent（如 Datadog）、eBPF 零侵入（OBI）三条路线各自的取舍是什么？为什么说「零侵入 vs OTel」已是伪命题？
    参考答案

    OTel 路线 0 许可费、后端即插即换（Lightstep 退场后客户换 Exporter 端点即迁移），但需更多基础设施与工程投入；Datadog 开箱即用最强、按主机/用量计费，但官方承认不同接入路径产品能力不同，锁定未消失；eBPF 零侵入不改一行代码，但 span 停留在协议级、进程内细节不可得。Beyla 已捐给 OTel 更名 OBI，输出同为 OTLP——零侵入成为 OTel 信号的另一种发射方式，二者是金字塔两层而非二选一。

  3. 报告指出「稳定」有三层不同步，请以 JS logs 为例说明；并指出 Python 与 TS 接入时各自最需要警惕的坑。
    参考答案

    JS logs 同日呈现三种状态：release notes 称 sdk-logs 已 stable（代码事实）、官方文档仍标 Development（文档口径）、api-logs 旧包未清退（生态层），判断能否上生产应三层都看。坑的分布不对称：Python 集中在打包与依赖（pex/zipapp 密封打包失效、urllib3 版本冲突）；TS 集中在运行时分裂（一年半出 2.0/3.0 两个大版本、Node 最低升至 22.15、自动插桩靠 hook require() 在 bundler/ESM 场景静默失效、浏览器仍 experimental）。

  4. 对一个 Python(FastAPI) + TS(Next.js) 的个人全栈项目，报告给出的分阶段验收建议是什么？
    参考答案

    新项目直接上 OTel SDK+Collector，后端任选。按「信号×语言」验收：trace、metric 双语言立即可上生产；Node/TS 的 log 可试点（新代码从 @opentelemetry/api 取 Logs API，勿用待退役的 api-logs）；Python log 观望，新代码用 opentelemetry-instrumentation-logging 替代已弃用的 LoggingHandler；浏览器端降级为尽力而为，深度追踪暂用商业 SDK 补位；采样用 OTEL_TRACES_SAMPLER 起步，是与后端选型同级的成本决策。

← 资料库今日播报 →