OpenTelemetry

可観測性は、Next.js アプリの動作とパフォーマンスを理解し、最適化するために非常に重要です。

アプリケーションが複雑になるにつれて、発生する可能性のある問題を特定して診断することがますます困難になります。ロギングやメトリクスなどの可観測性ツールを活用することで、開発者はアプリケーションの動作に関する洞察を得て、最適化の領域を特定できます。可観測性があれば、開発者は重大な問題になる前にプロアクティブに対処し、より優れたユーザーエクスペリエンスを提供できます。したがって、パフォーマンスの向上、リソースの最適化、ユーザーエクスペリエンスの強化のために、Next.js アプリケーションで可観測性を使用することを強くお勧めします。

アプリの計測には OpenTelemetry を使用することをお勧めします。これは、コードを変更せずに可観測性プロバイダーを変更できる、プラットフォームに依存しないアプリの計測方法です。OpenTelemetry とその動作の詳細については、公式 OpenTelemetry ドキュメント を参照してください。

このドキュメントでは、Span、Trace、または Exporter などの用語を使用していますが、これらはすべて OpenTelemetry Observability Primer に記載されています。

Next.js は OpenTelemetry 計測をすぐにサポートします。つまり、Next.js 自体を既に計測しています。OpenTelemetry を有効にすると、getStaticProps のようなすべてのコードが、役立つ属性を持つ *スパン* で自動的にラップされます。

はじめに

OpenTelemetry は拡張可能ですが、適切にセットアップするにはかなり冗長になる可能性があります。そのため、すぐに使い始めるのに役立つパッケージ @vercel/otel を用意しました。

@vercel/otel の使用

まず、以下のパッケージをインストールします。

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

次に、プロジェクトのルートディレクトリ（または、srcフォルダーを使用している場合はその中）に、カスタムのinstrumentation.ts (または .js) ファイルを作成します。

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

追加の構成オプションについては、@vercel/otel のドキュメントを参照してください。

知っておくとよいこと:

• instrumentation ファイルは、プロジェクトのルートに配置する必要があり、app または pages ディレクトリ内には配置しないでください。src フォルダーを使用している場合は、pages や app と並べて src 内にファイルを配置してください。
• pageExtensions 設定オプションを使用してサフィックスを追加する場合は、instrumentation ファイル名も一致するように更新する必要があります。
• 基本的なwith-opentelemetry の例を作成しましたので、利用できます。

手動でのOpenTelemetry設定

@vercel/otel パッケージは多くの構成オプションを提供しており、一般的なユースケースのほとんどに対応できます。しかし、ニーズに合わない場合は、OpenTelemetryを手動で構成できます。

まず、OpenTelemetryパッケージをインストールする必要があります。

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

次に、instrumentation.ts で NodeSDK を初期化できます。@vercel/otel とは異なり、NodeSDK はエッジランタイムと互換性がないため、process.env.NEXT_RUNTIME === 'nodejs' の場合にのみインポートしていることを確認する必要があります。ノードを使用している場合にのみ条件付きでインポートする新しいファイル instrumentation.node.ts を作成することをお勧めします。

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

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } 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: new Resource({
    [ATTR_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

これは @vercel/otel を使用するのと同等ですが、@vercel/otel によって公開されていない一部の機能を変更および拡張できます。エッジランタイムのサポートが必要な場合は、@vercel/otel を使用する必要があります。

インストルメンテーションのテスト

OpenTelemetryトレースをローカルでテストするには、互換性のあるバックエンドを備えたOpenTelemetryコレクターが必要です。弊社のOpenTelemetry開発環境を使用することをお勧めします。

すべてが正常に機能していれば、GET /requested/pathnameというラベルの付いたルートサーバースパンを確認できるはずです。その特定のトレースからの他のすべてのスパンは、その下にネストされます。

Next.jsは、デフォルトで出力されるよりも多くのスパンをトレースします。より多くのスパンを表示するには、NEXT_OTEL_VERBOSE=1を設定する必要があります。

デプロイ

OpenTelemetry Collectorの使用

OpenTelemetry Collectorを使用してデプロイする場合は、@vercel/otel を使用できます。これはVercelとセルフホストの両方で機能します。

Vercelへのデプロイ

OpenTelemetryはVercel上でそのまま動作するようにしました。

プロジェクトをオブザーバビリティプロバイダーに接続するには、Vercelドキュメントに従ってください。

セルフホスティング

他のプラットフォームへのデプロイも簡単です。Next.jsアプリからテレメトリデータを受信して処理するために、独自のOpenTelemetry Collectorを起動する必要があります。

これを行うには、OpenTelemetry Collectorの入門ガイドに従ってください。これにより、コレクターの設定と、Next.jsアプリからのデータの受信設定が説明されます。

コレクターが起動して実行されたら、それぞれのデプロイガイドに従って、選択したプラットフォームにNext.jsアプリをデプロイできます。

カスタムエクスポーター

OpenTelemetry Collectorは必須ではありません。@vercel/otel または 手動OpenTelemetry設定でカスタムOpenTelemetryエクスポーターを使用できます。

カスタムスパン

OpenTelemetry APIを使用してカスタムスパンを追加できます。

npm install @opentelemetry/api

次の例では、GitHubのスターを取得し、フェッチリクエストの結果を追跡するためのカスタムfetchGithubStarsスパンを追加する関数を示しています。

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

register関数は、新しい環境でコードが実行される前に実行されます。新しいスパンの作成を開始でき、エクスポートされたトレースに正しく追加されるはずです。

Next.jsのデフォルトスパン

Next.jsは、アプリケーションのパフォーマンスに関する有用な洞察を提供するために、いくつかのスパンを自動的に計測します。

スパンの属性は、OpenTelemetryのセマンティック規約に従います。また、next名前空間の下にいくつかのカスタム属性を追加します。

• next.span_name - スパン名の複製
• next.span_type - 各スパンタイプには一意の識別子があります
• next.route - リクエストのルートパターン（例：/[param]/user）。
• next.rsc (true/false) - リクエストがプリフェッチなどのRSCリクエストであるかどうか。
• next.page
  • これは、アプリルーターで使用される内部値です。
  • これを、特別なファイル（page.ts、layout.ts、loading.tsなど）へのルートと考えることができます。
  • /layoutを/(groupA)/layout.tsと/(groupB)/layout.tsの両方を識別するために使用できるため、next.routeと組み合わせて使用する場合にのみ、一意の識別子として使用できます。

[http.method] [next.route]

• next.span_type: BaseServer.handleRequest

このスパンは、Next.jsアプリケーションへの各受信リクエストのルートスパンを表します。リクエストのHTTPメソッド、ルート、ターゲット、およびステータスコードを追跡します。

属性

• 共通HTTP属性
  • http.method
  • http.status_code
• サーバーHTTP属性
  • http.route
  • http.target
• next.span_name
• next.span_type
• next.route

render route (app) [next.route]

• next.span_type: AppRender.getBodyResult.

このスパンは、app router でのルートのレンダリング処理を表します。

属性

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

fetch [http.method] [http.url]

• next.span_type: AppRender.fetch

このスパンは、コード内で実行された fetch リクエストを表します。

属性

• 共通HTTP属性
  • http.method
• クライアントHTTP属性
  • http.url
  • net.peer.name
  • net.peer.port (指定されている場合のみ)
• next.span_name
• next.span_type

このスパンは、環境変数で NEXT_OTEL_FETCH_DISABLED=1 を設定することによりオフにできます。これは、カスタムの fetch 計測ライブラリを使用する場合に役立ちます。

executing api route (app) [next.route]

• next.span_type: AppRouteRouteHandlers.runHandler.

このスパンは、app router における API ルートハンドラーの実行を表します。

属性

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

getServerSideProps [next.route]

• next.span_type: Render.getServerSideProps.

このスパンは、特定のルートに対する getServerSideProps の実行を表します。

属性

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

getStaticProps [next.route]

• next.span_type: Render.getStaticProps.

このスパンは、特定のルートに対する getStaticProps の実行を表します。

属性

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

render route (pages) [next.route]

• next.span_type: Render.renderDocument.

このスパンは、特定のルートのドキュメントをレンダリングするプロセスを表します。

属性

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

generateMetadata [next.page]

• next.span_type: ResolveMetadata.generateMetadata.

このスパンは、特定のページに対してメタデータを生成するプロセスを表します（単一のルートにこれらのスパンが複数存在する場合があります）。

属性

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

resolve page components

• next.span_type: NextNodeServer.findPageComponents.

このスパンは、特定のページのページコンポーネントを解決するプロセスを表します。

属性

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

resolve segment modules

• next.span_type: NextNodeServer.getLayoutOrPageModule.

このスパンは、レイアウトまたはページのコードモジュールのロードを表します。

属性

• next.span_name
• next.span_type
• next.segment

start response

• next.span_type: NextNodeServer.startResponse.

この長さゼロのスパンは、レスポンスで最初のバイトが送信された時間を表します。