はじめに
Commune Developers Advent Calendar 2025 シリーズ1 の7日目の記事です 🚀
Next.js には OpenTelemetry をサポートするようなことが書いてあり、Vercel 上でも簡単にトレースを取得できそうな感じがしました。今回は公式 example をベースに Vercel へデプロイし、Toolbar やダッシュボード経由で実際にトレースを眺めつつ、@vercel/otel パッケージの素性を調べてみました。
Vercel にデプロイ
公式 examples があるのでそれをつかっていきます。
「Deploy your own」というボタンがあるので、そこからデプロイできます。画面どおりすすめてくと、Vercel がいい感じにデプロイしてくれます。
Vercel > New Project
デプロイしたら、https://with-opentelemetry-{something}.vercel.app/ のようなドメインが自動で発行される[1]ので、そこからアクセスできます。
Next.js のスター数が表示されたら、正常にデプロイできています。
App画面
ダッシュボード
Vercel のダッシュボードからトレースを確認してみます[2]。Logs タブを開き、「Show requests that have traces」のアイコンをクリックすると確認できるはずですが、表示されてません。
Vercel Dashboard > Logs > Show requests that have traces
画面に従い Vercel Toolbar を設定します。 Vercel Toolbar はダッシュボードまたは npm @vercel/toolbar で有効化できます[3]。
Project のタブから Settings タブを開き、「Vercel Toolbar」が「Off」になっていないことを確認します。
Project Settings > Vercel Toolbar
左上の「Go to Team Settings」からチームの設定を開き、「Vercel Toolbar」が「Off」になっていないことを確認します。
Team Settings > Vercel Toolbar
Project の画面に戻り、Overview タブを開き、「Visit」横のメニューから「Visit with Toolbar」からアプリを開きます。
Project > Overview > Visit with Toolbar
Vercel Toolbar のアイコンから「Development > Tracing... > Run Page Trace」[4]を実行すると、ページがリロードされトレーシングが開始されます。
Development > Tracing... > Run Page Trace
「Trace Complete Click to open」をクリックするか、はじめの Logs タブからトレースが確認できます。
Project > Logs > Trace
トレース
スパンを眺めていきます。「Route across regions」では、hnd1 (ap-northeast-1 - Tokyo, Japan) の Edge で受け、iad1 (us-east-1 - Washington, D.C., USA) の関数で受けてそうな、属性が付与されてることが確認できます。ちなみにリージョンは Vercel Regions で確認できます。
Route across regions
他もみてみます。Next.js は複数のスパンを自動的に計測（ゼロコード計装）するため、デフォルトのスパン GET/, render route (app) , resolve segment modules, fetch [http.method] [http.url] などを確認できます。fetchGithubStars は、page file で呼び出されている関数です。
関数の中身は、/shared/fetch-github-stars.ts に定義されており、span 通り GitHub API に fetch する処理が書いてあります。AppRouter のレンダリング処理が開始されて、データを取得する様子がみえるので面白いですね。
resolve segment modules
OpenTelemetry の設定
インストール方法はシンプルになってます。パッケージをインストールしてから、プロジェクトルートにinstrumentation.tsファイルを配置するだけです。
npm install @vercel/otel \
@opentelemetry/sdk-logs \
@opentelemetry/api-logs \
@opentelemetry/instrumentation
@vercel/otel の設定
registerOTel に 文字列の serviceName を渡すだけだとデフォルト設定になります。 デフォルト設定では、TracerProvider[5] のみで Fetch Instrumentation[6] が有効になります。ちなみにこれをカスタマイズすることができるようです。例えば、ドキュメントには Fetch Instrumentation の設定をカスタマイズすることできるようです。
import { registerOTel } from '@vercel/otel';
export function register() {
registerOTel({
serviceName: `your-project-name`,
instrumentationConfig: {
fetch: {
// This URLs will have the tracing context propagated to them.
propagateContextUrls: [
'your-service-domain.com',
'your-database-domain.com',
],
// This URLs will not have the tracing context propagated to them.
dontPropagateContextUrls: [
'some-third-party-service-domain.com',
],
// This URLs will be ignored and will not be traced.
ignoreUrls: ['my-internal-private-tool.com'],
},
},
});
}
@vercel/otel パッケージの中身を少し読んでみます。
registerOTel の処理をみてみましょう。カスタマイズされた SDK ではありそうですが、start が定義されてますね。
build.ts をみると、Edge と Node.js で別々に build してるようです。
環境変数から attribute を設定してるところがあります。
計測対象をみてみます。いまのところ、Fetch Instrumentation だけのようにみえます。
一応外部から渡してあげれば、他も計測できそうです。
LogRecordProcessor と MetricReader も外部から渡せそうなので、ログやメトリクスも取りたい場合は自前で用意して渡してあげればよさそうですね。
おまけ
OTEL Zero (Experimental) というシンプルなAPIのみを提供するパッケージも開発されてそうです。気になりますね。
おわりに
今回は Vercel 公式 example をベースにお手軽トレース検証をしました。次は自前アプリへ組み込み、スパンの整備や独自属性の付与など実運用に向けたチューニングを試してみたいところです。Log/Metrics 系のコンポーネントを差し込めることも分かったので、これも次回はためしてみたいですね。
以上、Vercel や Next.js を使ってる方の参考になればうれしいです。
Commune Developers Advent Calendar 2025 シリーズ1,2 の他の記事もお楽しみに😃
Discussion