LogoENEnglish

راه‌اندازی OpenTelemetry در Next.js – رصد عملکرد، ساخت Span سفارشی، و اتصال به Collector

رصد (Observability) در Next.js به کمک OpenTelemetry امکان بررسی دقیق رفتار و عملکرد اپلیکیشن را فراهم می‌کند. این مقاله نحوهٔ نصب پکیج‌ها، راه‌اندازی اولیه با @vercel/otel، پیکربندی دستی، ساخت Span سفارشی، و اتصال به OpenTelemetry Collector را بررسی می‌کند.

OpenTelemetryInstrumentationSpanCollector

~3 دقیقه مطالعه • بروزرسانی ۶ آبان ۱۴۰۴

چرا رصد اهمیت دارد؟


با پیچیده‌تر شدن اپلیکیشن‌ها، تشخیص مشکلات و بهینه‌سازی عملکرد دشوارتر می‌شود. ابزارهای رصد مانند لاگ‌گیری و متریک‌ها به توسعه‌دهندگان کمک می‌کنند تا رفتار اپلیکیشن را تحلیل کرده و مشکلات را پیش از تبدیل شدن به بحران شناسایی کنند.


استفاده از OpenTelemetry


OpenTelemetry یک استاندارد مستقل از پلتفرم برای رصد است که امکان تغییر ارائه‌دهنده بدون تغییر کد را فراهم می‌کند. Next.js به‌صورت داخلی از OpenTelemetry پشتیبانی می‌کند.


راه‌اندازی سریع با @vercel/otel


نصب پکیج‌ها:

npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation

ساخت فایل instrumentation.ts در ریشه پروژه:

import { registerOTel } from '@vercel/otel'

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

پیکربندی دستی OpenTelemetry


نصب پکیج‌های اصلی:

npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

ساخت فایل instrumentation.node.ts:

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { NodeSDK } from '@opentelemetry/sdk-node'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

تست رصد و مشاهده Spanها


برای مشاهده Spanها، از OpenTelemetry Collector یا محیط توسعه مخصوص استفاده کنید. برای نمایش Spanهای بیشتر، متغیر NEXT_OTEL_VERBOSE=1 را تنظیم کنید.


اتصال به Collector


در حالت self-hosted، باید OpenTelemetry Collector را راه‌اندازی کرده و داده‌ها را از Next.js دریافت کنید. راهنمای رسمی OpenTelemetry Collector را دنبال کنید.


ساخت Span سفارشی


نصب پکیج API:

npm install @opentelemetry/api

مثال ساخت Span برای واکشی داده از GitHub:

import { trace } from '@opentelemetry/api'

export async function fetchGithubStars() {
  return await trace
    .getTracer('nextjs-example')
    .startActiveSpan('fetchGithubStars', async (span) => {
      try {
        return await getValue()
      } finally {
        span.end()
      }
    })
}

Spanهای پیش‌فرض در Next.js


Next.js به‌صورت خودکار Spanهایی برای موارد زیر ایجاد می‌کند:

  • BaseServer.handleRequest: ریشه درخواست HTTP
  • AppRender.getBodyResult: رندر مسیر در App Router
  • AppRender.fetch: واکشی داده‌ها
  • AppRouteRouteHandlers.runHandler: اجرای API Route
  • Render.getServerSideProps: اجرای getServerSideProps
  • Render.getStaticProps: اجرای getStaticProps
  • Render.renderDocument: رندر صفحات در Pages Router
  • ResolveMetadata.generateMetadata: تولید متادیتا برای صفحات
  • NextNodeServer.findPageComponents: یافتن کامپوننت‌های صفحه
  • NextNodeServer.getLayoutOrPageModule: بارگذاری ماژول‌های layout یا page
  • NextNodeServer.startResponse: ارسال اولین بایت پاسخ

جمع‌بندی


با استفاده از OpenTelemetry در Next.js، می‌توانید عملکرد اپلیکیشن را به‌صورت دقیق رصد کرده، مشکلات را سریع‌تر شناسایی کنید، و تجربه کاربری بهتری ارائه دهید. چه از @vercel/otel استفاده کنید و چه پیکربندی دستی انجام دهید، ابزارهای رصد به شما دیدی عمیق‌تر از رفتار اپلیکیشن می‌دهند.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article