OpenTelemetry

補足: この機能は実験的であり、next.config.jsでexperimental.instrumentationHook = true;を明示的に設定する必要があります。

オブザーバビリティ（可観測性）は、Next.jsアプリケーションの動作とパフォーマンスを理解・最適化する上で重要です。

アプリケーションが複雑になるにつれ、発生する問題を特定・診断することが難しくなります。ロギングやメトリクスなどのオブザーバビリティツールを活用することで、開発者はアプリケーションの動作を把握し、最適化すべき領域を特定できます。オブザーバビリティにより、開発者は問題が重大化する前に積極的に対処し、より良いユーザーエクスペリエンスを提供できます。そのため、Next.jsアプリケーションでオブザーバビリティを使用してパフォーマンスを向上させ、リソースを最適化し、ユーザーエクスペリエンスを向上させることを強く推奨します。

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

このドキュメントでは_Span_、Trace、_Exporter_などの用語を使用します。これらの用語はOpenTelemetry Observability Primerで説明されています。

Next.jsはOpenTelemetry計装を標準でサポートしており、Next.js自体が既に計装されています。OpenTelemetryを有効にすると、getStaticPropsなどのすべてのコードが有用な属性を持つ_span_で自動的にラップされます。

はじめに

OpenTelemetryは拡張可能ですが、適切に設定するにはかなり冗長な作業が必要です。そのため、迅速に開始できるように@vercel/otelパッケージを用意しました。

@vercel/otelの使用

まず、@vercel/otelをインストールする必要があります：

npm install @vercel/otel

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

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

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

補足

• instrumentationファイルはプロジェクトのルートに配置し、appやpagesディレクトリ内には配置しないでください。srcフォルダを使用している場合は、pagesやappと同じレベルに配置します。
• 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')
  }
}

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

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

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

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

const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_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コレクターの使用

OpenTelemetryコレクターでデプロイする場合、@vercel/otelを使用できます。 これはVercelでもセルフホスティングでも動作します。

Vercelへのデプロイ

Vercel上でOpenTelemetryがすぐに動作するようにしました。

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

セルフホスティング

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

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

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

カスタムエクスポーター

OpenTelemetryコレクターは必須ではありません。@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
  • これはApp Routerで使用される内部値です。
  • page.ts、layout.ts、loading.tsなどの特別なファイルへのルートと考えることができます。
  • next.routeと組み合わせた場合にのみ一意の識別子として使用できます。なぜなら/layoutは/(groupA)/layout.tsと/(groupB)/layout.tsの両方を識別するために使用できるからです。

[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.

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

属性：

• 一般的なHTTP属性
  • http.method
• クライアントHTTP属性
  • http.url
  • net.peer.name
  • net.peer.port（指定されている場合のみ）
• next.span_name
• next.span_type

このスパンは、環境変数NEXT_OTEL_FETCH_DISABLED=1を設定することで無効にできます。これはカスタムフェッチ計装ライブラリを使用したい場合に便利です。

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.

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