‏فرستادن تله‌متری Vercel AI SDK به Sentry با OpenTelemetry

این یه دستورالعمل از کوک‌بوک سنتریه که توضیح می‌ده چطور بدون از بین بردن ستاپ موجود @vercel/otel، اسپن‌های LLM رو به AI Agents Insights سنتری مسیردهی کنی. پیش‌نیازش یه پروژه‌ست که از Vercel AI SDK با ابزاردهی @vercel/otel استفاده می‌کنه، نود ۱۸ به بالا، و یه حساب و DSN سنتری.

قدم اول نصب پکیج @sentry/opentelemetry کنار SDK رانتایمته؛ این پکیج Sampler و Propagator و SpanProcessor رو در اختیار می‌ذاره که اسپن‌های OTel رو به سنتری پل می‌زنن. پکیج‌های @vercel/otel و ai موجودت دست‌نخورده می‌مونن.

قدم دوم نکته‌ی محوریه: به‌طور پیش‌فرض SDK سنتری موقع استارت، SDK اوپن‌تله‌متری خودش رو ثبت می‌کنه. چون @vercel/otel همین کارو از قبل می‌کنه، باید با skipOpenTelemetrySetup: true به سنتری بگی این کارو نکنه. این تنظیم باعث می‌شه سنتری به جای صاحب پایپ‌لاین، یه مصرف‌کننده‌ی اسپن بشه:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  skipOpenTelemetrySetup: true,
});

قدم سوم وصل کردن SentryPropagator و SentrySampler و SentrySpanProcessor به فراخوانی registerOTel هست. ورودی‌های "auto" پیش‌فرض‌های وکسل رو حفظ می‌کنن، پس ابزاردهی موجودت سرجاش می‌مونه؛ تو داری سنتری رو به پایپ‌لاین اضافه می‌کنی، نه جایگزین چیزی. تو این مرحله باید Propagator و SpanProcessor سنتری رو کنار همون "auto"ها تو آرایه‌ها بذاری و یه SentryContextManager رو هم به‌عنوان مدیر کانتکست پاس بدی.

قدم چهارم روشن کردن تله‌متریه. به گفته‌ی نویسنده Vercel AI SDK فقط وقتی تله‌متری می‌فرسته که خودت قبولش کنی، پس باید به هر فراخوانی LLM یه experimental_telemetry با isEnabled: true و یه functionId پایدار اضافه کنی تا سنتری اجراهای مرتبط رو با هم گروه کنه. گزینه‌های recordInputs و recordOutputs پرامپت و خروجی رو به تریس می‌چسبونن که موقع دیباگ مفیده، ولی اگه پرامپتت داده‌ی حساس داره باید خاموششون کنی. قدم پنجم هم اینه که اپ رو اجرا کنی و تو داشبورد AI Agents هر فراخوانی generateText رو به تفکیک مدل، تعداد توکن و لیتنسی ببینی.

نویسنده چند دام رایج رو هم گوشزد می‌کنه: یادت رفتن skipOpenTelemetrySetup: true باعث ثبت دو تا SDK اوپن‌تله‌متری و اسپن‌های تکراری می‌شه؛ حذف "auto" از propagators یا spanProcessors پیش‌فرض‌های وکسل رو می‌پرونه و ابزاردهی خودکار HTTP و fetch و Next.js رو از دست می‌دی؛ و روشن گذاشتن recordInputs تو پروداکشن می‌تونه PII یا اسرار کاربر رو به سنتری بفرسته، پس بهتره پشت یه فلگ محیطی قایمش کنی.

نکات کلیدی:

• هدف: فرستادن اسپن‌های LLM از Vercel AI SDK به AI Agents Insights سنتری
• سنتری به جای صاحب پایپ‌لاین OTel، فقط مصرف‌کننده‌ی اسپن می‌شه
• skipOpenTelemetrySetup: true جلوی ثبت دوباره و اسپن‌های تکراری رو می‌گیره
• ورودی‌های "auto" باید بمونن تا ابزاردهی پیش‌فرض وکسل از بین نره
• روشن گذاشتن recordInputs تو پروداکشن می‌تونه داده‌ی حساس رو لو بده