OpenTelemetry

Bilmekte fayda var: Bu özellik deneyseldir, next.config.js adresinizde experimental.instrumentationHook = true; adresini sağlayarak açıkça katılmanız gerekir.

Next.js uygulamanızın davranışını ve performansını anlamak ve optimize etmek için gözlemlenebilirlik çok önemlidir.

Uygulamalar daha karmaşık hale geldikçe, ortaya çıkabilecek sorunları belirlemek ve teşhis etmek giderek zorlaşmaktadır. Geliştiriciler, günlük kaydı ve metrikler gibi gözlemlenebilirlik araçlarından yararlanarak uygulamalarının davranışları hakkında içgörü kazanabilir ve optimizasyon alanlarını belirleyebilir. Gözlemlenebilirlik sayesinde, geliştiriciler sorunları büyük sorunlara dönüşmeden önce proaktif olarak ele alabilir ve daha iyi bir kullanıcı deneyimi sağlayabilir. Bu nedenle, performansı artırmak, kaynakları optimize etmek ve kullanıcı deneyimini geliştirmek için Next.js uygulamalarınızda gözlemlenebilirliği kullanmanız şiddetle tavsiye edilir.

Uygulamalarınızı enstrümante etmek için OpenTelemetry kullanmanızı öneririz. Kodunuzu değiştirmeden gözlemlenebilirlik sağlayıcınızı değiştirmenize olanak tanıyan, uygulamaları enstrümante etmenin platformdan bağımsız bir yoludur. OpenTelemetry ve nasıl çalıştığı hakkında daha fazla bilgi için Resmi OpenTelemetry dokümanlarını okuyun.

Bu dokümanda Span, Trace veya Exporter gibi terimler kullanılmaktadır, bunların tümü OpenTelemetry Observability Primer adresinde bulunabilir.

Next.js, OpenTelemetry enstrümantasyonunu kutudan çıkar çıkmaz destekler, bu da Next.js'nin kendisini zaten enstrümante ettiğimiz anlamına gelir. OpenTelemetry'yi etkinleştirdiğinizde, getStaticProps gibi tüm kodlarınızı otomatik olarak yararlı niteliklerle span 'lara saracağız.

Bilmekte fayda var: Şu anda OpenTelemetry bağlamalarını yalnızca sunucusuz işlevlerde destekliyoruz. edge veya istemci tarafı kodu için herhangi bir destek sağlamıyoruz.

Getting Started

OpenTelemetry genişletilebilir ancak düzgün bir şekilde kurmak oldukça ayrıntılı olabilir. Bu nedenle hızlı bir şekilde başlamanıza yardımcı olacak bir paket hazırladık @vercel/otel. Genişletilebilir değildir ve kurulumunuzu özelleştirmeniz gerekiyorsa OpenTelemetry'yi manuel olarak yapılandırmalısınız.

Using @vercel/otel

Başlamak için @vercel/otel adresini yüklemeniz gerekir:

npm install @vercel/otel

Ardından, özel bir instrumentation.ts (veya .js) dosyasını projenin kök dizinine (veya kullanıyorsanız src klasörünün içine) yerleştirin:

import { registerOTel } from '@vercel/otel'
 
export function register() {
  registerOTel('next-app')
}

Bildiğim iyi oldu

• instrumentation dosyası, app veya pages dizininin içinde değil, projenizin kök dizininde olmalıdır. Eğer src klasörünü kullanıyorsanız, dosyayı pages ve app ile birlikte src içine yerleştirin.
• Bir sonek eklemek için pageExtensions yapılandırma seçeneğini kullanırsanız, instrumentation dosya adını da eşleşecek şekilde güncellemeniz gerekecektir.
• Kullanabileceğiniz temel bir with-opentelemetry örneği oluşturduk.

Manual OpenTelemetry configuration

Sarmalayıcımız @vercel/otel ihtiyaçlarınızı karşılamıyorsa, OpenTelemetry'yi manuel olarak yapılandırabilirsiniz.

Öncelikle OpenTelemetry paketlerini yüklemeniz gerekir:

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

Artık NodeSDK adresini instrumentation.ts adresinizde başlatabilirsiniz. OpenTelemetry API'leri edge çalışma zamanı ile uyumlu değildir, bu nedenle bunları yalnızca process.env.NEXT_RUNTIME === 'nodejs' adresinde içe aktardığınızdan emin olmanız gerekir. Yalnızca node kullanırken koşullu olarak içe aktardığınız yeni bir instrumentation.node.ts dosyası oluşturmanızı öneririz:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts')
  }
}

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
 
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

Bunu yapmak @vercel/otel kullanmakla eşdeğerdir, ancak değiştirmek ve genişletmek mümkündür. Örneğin, @opentelemetry/exporter-trace-otlp-http yerine @opentelemetry/exporter-trace-otlp-grpc kullanabilir veya daha fazla kaynak özniteliği belirtebilirsiniz.

Testing your instrumentation

OpenTelemetry izlerini yerel olarak test etmek için uyumlu bir arka uca sahip bir OpenTelemetry toplayıcısına ihtiyacınız vardır. adresindeki OpenTelemetry geliştirme ortamımızı kullanmanızı öneririz.

Her şey yolunda giderse, GET /requested/pathname olarak etiketlenmiş kök sunucu yayılımını görebilmeniz gerekir. Bu belirli izlemedeki diğer tüm yayılımlar bunun altında yuvalanacaktır.

Next.js, varsayılan olarak yayılandan daha fazla aralığı izler. Daha fazla aralığı görmek için NEXT_OTEL_VERBOSE=1 adresini ayarlamanız gerekir.

Deployment

Using OpenTelemetry Collector

OpenTelemetry Collector ile dağıtım yaparken, @vercel/otel adresini kullanabilirsiniz. Hem Vercel üzerinde hem de kendi kendine barındırıldığında çalışacaktır.

Deploying on Vercel

OpenTelemetry'nin Vercel'de kutudan çıktığı gibi çalıştığından emin olduk.

Projenizi bir gözlemlenebilirlik sağlayıcısına bağlamak için adresindeki Vercel belgelerini izleyin.

Self-hosting

Diğer platformlara dağıtmak da kolaydır. Next.js uygulamanızdan telemetri verilerini almak ve işlemek için kendi OpenTelemetry Collector'ınızı kurmanız gerekecektir.

Bunu yapmak için, toplayıcıyı kurma ve Next.js uygulamanızdan veri alacak şekilde yapılandırma konusunda size yol gösterecek olan OpenTelemetry Collector Getting Started kılavuzunu izleyin.

Toplayıcınızı kurup çalıştırdıktan sonra, Next.js uygulamanızı ilgili dağıtım kılavuzlarını izleyerek seçtiğiniz platforma dağıtabilirsiniz.

Custom Exporters

OpenTelemetry Collector kullanmanızı öneririz. Platformunuzda bu mümkün değilse, manuel OpenTelemetry yapılandırması ile özel bir OpenTelemetry dışa aktarıcı kullanabilirsiniz

Custom Spans

OpenTelemetry API'leri ile özel bir açıklık ekleyebilirsiniz.

npm install @opentelemetry/api

Aşağıdaki örnekte GitHub yıldızlarını getiren ve getirme isteğinin sonucunu izlemek için özel bir fetchGithubStars span ekleyen bir işlev gösterilmektedir:

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()
      }
    })
}

Kodunuz yeni bir ortamda çalışmadan önce register işlevi çalışacaktır. Yeni açıklıklar oluşturmaya başlayabilirsiniz ve bunlar dışa aktarılan izlemeye doğru şekilde eklenmelidir.

Default Spans in Next.js

Next.js, uygulamanızın performansı hakkında yararlı bilgiler sağlamak için otomatik olarak çeşitli aralıkları enstrümante eder.

Açıklıklardaki öznitelikler OpenTelemetry semantik kurallarını takip eder . Ayrıca next ad alanı altında bazı özel öznitelikler de ekliyoruz:

• next.span_name - yayılma adını çoğaltır
• next.span_type - her span türünün benzersiz bir tanımlayıcısı vardır
• next.route - Talebin rota modeli (örneğin, /[param]/user).
• next.page
  • Bu, bir uygulama yönlendiricisi tarafından kullanılan dahili bir değerdir.
  • Bunu özel bir dosyaya giden bir yol olarak düşünebilirsiniz ( page.ts, layout.ts, loading.ts ve diğerleri gibi)
  • Yalnızca next.route ile eşleştirildiğinde benzersiz bir tanımlayıcı olarak kullanılabilir çünkü /layout hem /(groupA)/layout.ts hem de /(groupB)/layout.ts

[http.method] [next.route]

• next.span_type: BaseServer.handleRequest

Bu span, Next.js uygulamanıza gelen her istek için kök spanı temsil eder. İsteğin HTTP yöntemini, rotasını, hedefini ve durum kodunu izler.

Nitelikler:

• Ortak HTTP öznitelikleri
  • http.method
  • http.status_code
• Sunucu HTTP öznitelikleri
  • http.route
  • http.target
• next.span_name
• next.span_type
• next.route

render route (app) [next.route]

• next.span_type: AppRender.getBodyResult.

Bu açıklık, uygulama yönlendiricisinde bir rota oluşturma sürecini temsil eder.

Nitelikler:

• next.span_name
• next.span_type
• next.route

fetch [http.method] [http.url]

• next.span_type: AppRender.fetch

Bu aralık, kodunuzda yürütülen getirme isteğini temsil eder.

Nitelikler:

• Ortak HTTP öznitelikleri
  • http.method
• İstemci HTTP öznitelikleri
  • http.url
  • net.peer.name
  • net.peer.port (yalnızca belirtilmişse)
• next.span_name
• next.span_type

executing api route (app) [next.route]

• next.span_type: AppRouteRouteHandlers.runHandler.

Bu açıklık, uygulama yönlendiricisinde bir API rota işleyicisinin yürütülmesini temsil eder.

Nitelikler:

• next.span_name
• next.span_type
• next.route

getServerSideProps [next.route]

• next.span_type: Render.getServerSideProps.

Bu açıklık, belirli bir rota için getServerSideProps adresinin yürütülmesini temsil eder.

Nitelikler:

• next.span_name
• next.span_type
• next.route

getStaticProps [next.route]

• next.span_type: Render.getStaticProps.

Bu açıklık, belirli bir rota için getStaticProps adresinin yürütülmesini temsil eder.

Nitelikler:

• next.span_name
• next.span_type
• next.route

render route (pages) [next.route]

• next.span_type: Render.renderDocument.

Bu yayılma alanı, belirli bir rota için belgeyi oluşturma sürecini temsil eder.

Nitelikler:

• next.span_name
• next.span_type
• next.route

generateMetadata [next.page]

• next.span_type: ResolveMetadata.generateMetadata.

Bu açıklık, belirli bir sayfa için meta veri oluşturma sürecini temsil eder (tek bir rota bu açıklıklardan birden fazlasına sahip olabilir).

Nitelikler:

• next.span_name
• next.span_type
• next.page