Tin tức

OpenTelemetry JS SDK 3.0 đòi Node.js 22.15 và bỏ nhiều gói cũ

Bản 3.0 gộp các gói sdk-trace, bỏ exporter và propagator Jaeger, đổi cách import. Bài liệt kê những gì dễ vỡ khi nâng cấp ứng dụng Node.js.

Đỗ Phạm Nguyên

OpenTelemetry JS SDK 3.0 đòi Node.js 22.15 và bỏ nhiều gói cũ

Dự án OpenTelemetry công bố SDK JavaScript 3.0 trong bài viết ngày 05/11/2026 trên blog chính thức. Bản này đòi Node.js từ 22.15.0 trở lên, bỏ nhiều gói quen thuộc và chặn các cách import sâu vào thư mục build, nên ứng dụng đang dùng bản 2.x có thể lỗi ngay khi nâng cấp.

Bài được AI hỗ trợ soạn thảo; xem mục "Cách bài này được tạo" ở cuối bài.

Các tủ rack chứa máy chủ trong một phòng máy chủ
Ảnh: Kevin Ache / Unsplash (Unsplash License)

Điểm mới trong bản 3.0

Các gói ổn định nhảy lên phiên bản 3.0.0 trở lên, còn gói thử nghiệm lên 0.300.0 trở lên, theo blog OpenTelemetry. Gói `@opentelemetry/api` vẫn ở nhánh 1.x và đi kèm bản 1.10.0 trong đợt phát hành này.

Ghi chú phát hành ghi rõ: "The minimum supported Node.js has been raised to `>=22.15.0`." (ghi chú phát hành v3.0.0). Bản 2.x yêu cầu `^18.19.0 || >=20.6.0` theo hướng dẫn nâng cấp, nghĩa là máy chủ còn chạy Node 18 hoặc 20 phải nâng runtime trước.

Mỗi gói giờ có bản đồ `exports`. Theo hướng dẫn nâng cấp, import sâu kiểu `@opentelemetry/core/build/...` sẽ báo lỗi `ERR_PACKAGE_PATH_NOT_EXPORTED`, và không còn import được `<package>/package.json`.

Những gói và API bị bỏ

Đã bỏThay bằng
`@opentelemetry/sdk-trace-base`, `sdk-trace-node`, `sdk-trace-web``@opentelemetry/sdk-trace` (`BasicTracerProvider` thành `TracerProvider`)
`@opentelemetry/exporter-jaeger`Exporter OTLP
`@opentelemetry/propagator-jaeger``W3CTraceContextPropagator` trong `@opentelemetry/core`
`AsyncHooksContextManager``AsyncLocalStorageContextManager`
`@opentelemetry/api-logs`Import từ `@opentelemetry/api`
`forceFlushTimeoutMillis` trong tùy chọn provider`provider.forceFlush({ timeoutMillis })`
`LoggerConfig.disabled``enabled` (giá trị đảo ngược)

Bảng trên lấy từ hướng dẫn nâng cấp 3.x. Hướng dẫn cũng ghi `BatchSpanProcessor` và `SimpleSpanProcessor` giờ nhận một object tùy chọn, ví dụ `new BatchSpanProcessor({ exporter })`, thay cho đối số vị trí.

Phân tích tác động với người đọc

Phần này là nhận định của chúng tôi, dựa trên các thay đổi nêu trên. Rủi ro lớn nhất nằm ở propagator Jaeger. Hướng dẫn nâng cấp cảnh báo mọi dịch vụ trong hệ thống phải đổi sang W3C Trace Context cùng lúc, hoặc dùng `CompositePropagator` trong giai đoạn chuyển tiếp. Nếu chỉ nâng một dịch vụ, trace có thể đứt ở ranh giới giữa dịch vụ cũ và mới.

Rủi ro thứ hai là công cụ build. Hướng dẫn nâng cấp nêu bundler phải hỗ trợ trường `imports`: webpack từ 5.54, Jest từ 29.4, Metro của React Native từ 0.81.3. Dự án đóng gói cho trình duyệt hoặc chạy test bằng Jest cũ nên kiểm tra các mốc này trước.

Rủi ro thứ ba là cảnh báo về phụ thuộc. Theo cùng hướng dẫn, `@opentelemetry/propagator-jaeger@^2` giới hạn `@opentelemetry/api` dưới 1.10.0, nên giữ gói này sẽ chặn bạn lên API 1.10.0.

Các bước nâng cấp theo hướng dẫn chính thức

  1. Nâng runtime lên Node.js 22.15.0 trở lên.
  2. Đổi import từ `@opentelemetry/api-logs` sang `@opentelemetry/api`.
  3. Kiểm tra bundler hỗ trợ `imports` và `exports`.
  4. Thay propagator và exporter Jaeger, đồng bộ cho mọi dịch vụ.
  5. Thay các import `sdk-trace-*` bằng `@opentelemetry/sdk-trace`.
  6. Đổi `disabled` thành `enabled` (đảo giá trị) trong cấu hình logger.

Danh sách rút gọn từ hướng dẫn nâng cấp 3.x; bản đầy đủ còn nhiều mục khác cho `sdk-node` và instrumentation.

Cách bài này được tạo: bài được AI hỗ trợ tìm nguồn và soạn thảo từ các nguồn nêu trong mục Nguồn tham khảo, và do Đỗ Phạm Nguyên biên tập.

Nguồn tham khảo

  • Blog OpenTelemetry: https://opentelemetry.io/blog/2026/otel-js-sdk-3-0/
  • Ghi chú phát hành v3.0.0: https://github.com/open-telemetry/opentelemetry-js/releases/tag/v3.0.0
  • Hướng dẫn nâng cấp 3.x: https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/3.x/migration-guide.md

Nên làm tiếp: đọc hướng dẫn nâng cấp đầy đủ và thử trên staging trước khi nâng bản trên production.