OpenTelemetryを使用した計装の設定方法

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

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

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

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

Next.jsはOpenTelemetry計装をデフォルトでサポートしており、Next.js自体が既に計装されています。

はじめに

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

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'の場合のみインポートする必要があります。nodeを使用時にのみ条件付きでインポートする新しいファイル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 { 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()

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コレクターの使用

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のスター数を取得し、fetchリクエストの結果を追跡するための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.

このスパンは、コード内で実行される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 Route Handlerの実行を表します。

属性：

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

このスパンは、特定のページ（1つのルートに複数存在する可能性あり）のメタデータ生成プロセスを表します。

属性：

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

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