‏تریس‌های Next.js رو با OpenTelemetry بفرست بیرون

نویسنده می‌گه تریس‌ها یه معدن طلا از اطلاعاتن که کمکت می‌کنن صفحه‌های کند رو پیدا و درست کنی. خبر خوب اینه که Next.js از جعبه از تریسینگ پشتیبانی می‌کنه: درخواست‌های ورودی، فراخوانی‌های fetch()، میدل‌ور و رندر سمت سرور همه آماده‌ان که به هر بک‌اند سازگار با OpenTelemetry فرستاده بشن. تنها گیرش اینه که تا یه اکسپورتر تنظیم نکنی، هیچ‌وقت این تریس‌ها رو نمی‌بینی.

برای این که بفهمی چرا مهمه، نویسنده می‌گه وقتی یه صفحه کنده، سخت‌ترین بخش اینه که بفهمی کدوم قسمت درخواست مقصره؛ میدل‌ور، رندر سمت سرور، یه API route، کوئری دیتابیس یا یه fetch() بالادستی. با تریسینگ هر قدم به‌صورت یه span تو یه خط زمانی ضبط می‌شه و یه trace همهٔ span‌های یه درخواست رو تو یه آبشار کنار هم می‌ذاره تا دقیق ببینی وقت کجا رفته.

راه‌اندازیش هم کوتاهه. کتابخونهٔ @vercel/otel خودش SDK رو تنظیم می‌کنه و فرق بین رانتایم Node و Edge رو هم مدیریت می‌کنه. کافیه یه فایل instrumentation.ts تو ریشهٔ پروژه بذاری که Next.js موقع استارت خودکار لودش می‌کنه:

import { registerOTel } from "@vercel/otel";

export function register() {
  registerOTel({ serviceName: "next-app" });
}

نویسنده می‌گه span‌هایی که Next.js خودش می‌ده عمومی‌ان و چیزی از منطق کسب‌وکار تو رو ندارن، برای همین بهتره دور عملیات‌های مهم span خودت رو اضافه کنی؛ چیزایی مثل تولید فاکتور، شارژ کارت یا فراخوانی یه مدل هوش مصنوعی. توصیه می‌کنه هر تابع کمکی رو نپیچی و از عملیات‌های سطح‌بالا شروع کنی، و برای اسم span از قالب نقطه‌ای و کنش‌محور مثل invoice.generate-pdf استفاده کنی که بشه بعداً گروه‌بندی و فیلترشون کرد. یه هشدار مهم هم می‌ده: تو attributeها آیدی خام کاربر، ایمیل، سکرت یا پرامپت نذار.

یه محدودیت مهم @vercel/otel اینه که span سفارشی فقط تو رانتایم Node پشتیبانی می‌شه؛ رو Edge span‌های خودکار Next.js میان ولی نمی‌تونی span دستی اضافه کنی و برای اون باید سراغ SDK خود Sentry بری. برای فرستادن تریس‌ها هم OTLP پروتکل استانداردیه و Sentry یه اندپوینت مستقیم OTLP داره؛ فقط با ست کردن دو تا متغیر محیطی (آدرس اندپوینت و هدر احراز هویت) تریس‌ها شروع به اومدن می‌کنن، بدون SDK و بدون کالکتور.

در آخر نویسنده یه مقایسه می‌ذاره: اگه اولین باره تریسینگ رو راه می‌ندازی، مخصوصاً برای Next.js توصیه‌اش استفاده از SDK خود Sentryه، چون @vercel/otel کل تصویر رو نمی‌گیره؛ سمت مرورگر، مانیتورینگ خطا، stack trace با سورس‌مپ و Session Replay رو نداره. ولی اگه از قبل یه پایپ‌لاین OpenTelemetry داری یا فقط تریس استاندارد سمت سرور می‌خوای، OTLP مستقیم گزینهٔ سبک‌تریه. یه نکتهٔ سازگاری هم هست: نباید @vercel/otel و SDK سنتری رو با هم تو یه اپ راه بندازی چون هر دو یه tracer provider ثبت می‌کنن و به هم می‌خورن.

نکات کلیدی:

• Next.js از جعبه تریسینگ داره ولی تا اکسپورتر تنظیم نکنی چیزی نمی‌بینی
• با یه فایل instrumentation.ts و registerOTel() تریس‌ها رو راه می‌ندازی
• دور عملیات‌های مهم span سفارشی با اسم نقطه‌ای مثل invoice.generate-pdf بذار
• span سفارشی @vercel/otel فقط رو رانتایم Node کار می‌کنه، نه Edge
• Sentry اندپوینت مستقیم OTLP داره؛ ولی برای مانیتورینگ خطا و تریس مرورگر SDK خودش کامل‌تره