‏OpenTelemetry JS SDK 3.x اومد: چی عوض شده و چطور مهاجرت کنیم

تیم OpenTelemetry JS تو اکتبر ۲۰۲۶ اولین نسخه‌های SDK 3.x رو منتشر کرد و همراهش یه راهنمای مهاجرت نوشته. OpenTelemetry یعنی یه استاندارد باز برای جمع‌کردن trace، متریک و لاگ از اپ‌ها. پکیج‌های پایدار حالا نسخهٔ 3.0.0 دارن و پکیج‌های آزمایشی از 0.223.0 پریدن به 0.300.0. به گفتهٔ تیم، این پرش عمداً بوده تا معلوم باشه این پکیج‌ها مال «نسل 3.x» هستن. همزمان @opentelemetry/api هم نسخهٔ مینور 1.10.0 گرفته.

اگه فقط از چیزی مثل @opentelemetry/auto-instrumentations-node استفاده می‌کنی و مستقیم با پکیج‌های SDK کار نداری، احتمالاً لازم نیست کدت رو عوض کنی. ولی حداقل نسخهٔ Node برای همه به >=22.15.0 رسیده، چون Node 18 و 20 به پایان عمرشون رسیدن. یه تغییر مهم دیگه اینه که پکیج‌ها حالا خروجی درست ESM و CJS دارن و ورودی‌هاشون رو با فیلد exports تو package.json تعریف می‌کنن. یعنی هر deep import (یعنی import از مسیرهای داخلی پکیج) دیگه کار نمی‌کنه.

خبر خوب اینه که سیگنال Logs پایدار شده. پکیج @opentelemetry/api-logs حذف شده و همه‌چیزش رفته توی @opentelemetry/api. پس فقط باید importها رو عوض کنی:

// before
import { logs, SeverityNumber } from '@opentelemetry/api-logs';

// after
import { logs, SeverityNumber } from '@opentelemetry/api';

حالا attributeها (یعنی همون کلید و مقدارهایی که به span یا لاگ می‌چسبونی) می‌تونن مقدارهای پیچیده‌تر هم داشته باشن، مثل آبجکت، null یا آرایهٔ مخلوط. این طبق OTEP 4485 هست. برای کاربر API معمولاً شکستنی نیست، ولی برای کسایی که SDK می‌نویسن هست. attributeهای پیچیده روی Resource و scope لاگر دیگه پشتیبانی نمی‌شن و با یه هشدار دور ریخته می‌شن. تیم هم توصیه می‌کنه تا جای ممکن از attribute ساده استفاده کنی.

برای کدی که نسخهٔ Node و مرورگر جدا داره، دیگه فیلد browser تو package.json نیست و انتخاب با شرط‌های exports و imports و مسیر #platform انجام می‌شه. پس bundler باید اینارو پشتیبانی کنه: Webpack 5.54 به بالا، Jest 29.4 به بالا و Metro 0.81.3 به بالا برای React Native. Parcel و Jest 30 تنظیم جدا لازم دارن.

چند پکیج هم کلاً حذف شدن: propagator-jaeger (به‌جاش W3CTraceContextPropagator)، exporter-jaeger (به‌جاش exporterهای OTLP، چون خود Jaeger الان OTLP می‌گیره)، shim-opentracing و shim-opencensus. تیم هشدار می‌ده که عوض‌کردن propagator باید تو همهٔ سرویس‌ها با هم انجام بشه، وگرنه traceهای توزیع‌شده از هم می‌پاشن. اگه نمی‌تونی همه رو با هم ببری، دورهٔ گذار رو روی SDK 2.x بگذرون.

نکات کلیدی:

• پکیج‌های پایدار به 3.0.0 و آزمایشی‌ها به 0.300.0 رسیدن.
• حداقل نسخهٔ Node حالا 22.15.0 هست، به‌جز پکیج‌های API و semantic-conventions.
• پکیج @opentelemetry/api-logs حذف شده و Logs رفته توی @opentelemetry/api نسخهٔ 1.10.0.
• deep import و import کردن package.json پکیج دیگه کار نمی‌کنه؛ برای نسخه از SDK_INFO استفاده کن.
• پکیج‌های Jaeger، OpenTracing و OpenCensus حذف شدن.
• نسخهٔ 2.x تا یک سال بعد از انتشار 3.0.0 پشتیبانی می‌شه.