はじめに

弊社システムのボトルネック調査の一環として、OpenTelemetry を利用した分散トレーシングの仕組みを学習しました。
今回は簡単な Todo アプリを Nest.js + Next.js で作り、そこに OpenTelemetry を組み込んで「何がどこで遅いのか」をモニタリングできるようにした内容をまとめます。

システム構成とプロトタイプ

プロトタイプリポジトリはこちらです。
👉 https://github.com/onodera1215/open-telemetry-demo/tree/mainになります。
Todo アプリケーションを Nest.js（バックエンド）＋ Next.js（フロントエンド）構成で、両者に手動計装を加えて Jaeger から観測できるようにしています。

ディレクトリ構成は以下の通りです。

.
├── README.md
├── backend
│   ├── Dockerfile
│   ├── README.md
│   ├── dist
│   ├── eslint.config.mjs
│   ├── instrumentation.ts
│   ├── nest-cli.json
│   ├── node_modules
│   ├── package-lock.json
│   ├── package.json
│   ├── prisma
│   ├── prisma.config.ts
│   ├── src
│   ├── test
│   ├── tsconfig.build.json
│   └── tsconfig.json
├── docker
│   └── database
├── docker-compose.yml
└── frontend
    ├── Dockerfile
    ├── README.md
    ├── app
    ├── codegen.ts
    ├── components
    ├── eslint.config.mjs
    ├── features
    ├── graphql
    ├── instrumentation.ts
    ├── next-env.d.ts
    ├── next.config.ts
    ├── node_modules
    ├── package-lock.json
    ├── package.json
    ├── postcss.config.mjs
    ├── public
    ├── tsconfig.json
    └── types

用語について

OpenTelemetry を触る上で最低限知っておくべき用語を簡単にまとめます。
解説は OpenTelemetry 公式の Observability 入門を参考にしています。

テレメトリー（Telemetry）

アプリケーションやシステムの動作から得られるデータ全般のこと。
代表的なものは以下の 3 つです。

トレース：処理の流れ（リクエストの経路）
メトリクス：CPU 温度・処理時間・リクエスト数などの数値
ログ：任意のメッセージ出力（デバッグ情報など）

オブザーバビリティ（Observability）

「内部構造を知らなくても、外から観察するだけでシステムの状態を把握できる能力」のこと。
OpenTelemetry が提供するトレース／メトリクス／ログという“シグナル”を組み合わせることで、未知の問題にもアプローチしやすくなります。

信頼性（Reliability）とメトリクス

サービスが期待通りに動作しているかどうかを測る概念。
SLI（実測値）、SLO（目標値）などの指標を設定し、メトリクスを基に信頼性運用を行います。

分散トレース（Distributed Tracing）／スパン(Span)／ログ(Log)

分散トレース：サービスを跨ぐ処理の流れを可視化
スパン：処理の最小単位（関数単位など）
ログ：付随情報
トレースとスパンの関係の例

Trace（リクエスト全体）
└── Span A（API Gateway）
      └── Span B（Service A）
            ├── Span C（DB Query）
            └── Span D（Service B 呼び出し）

なぜ分散トレースが重要なのか？

ログだけでは限界がある

「このログはどのリクエストのもの？」
「この処理はどれの前後？」

特にマイクロサービスでは ログの照合が地獄 になりがちです。

分散トレースなら全部つながる

リクエストに一意の ID を付与し、処理ごとにスパンを記録することで リクエストの流れを瞬時に追跡可能 になります。

実装編

フロントエンド

まずは必要なパッケージをインストールします。

npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/sdk-metrics \
  @opentelemetry/sdk-trace-node

npm install @opentelemetry/api @opentelemetry/resources @opentelemetry/semantic-conventions

Next.js はルート直下の instrumentation.ts を自動的に読み込みます。

/*instrumentation.ts*/
import { NodeSDK } from "@opentelemetry/sdk-node";
import {
  PeriodicExportingMetricReader,
  ConsoleMetricExporter,
} from "@opentelemetry/sdk-metrics";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";

export const OTEL_SERVICE_NAME = process.env.OTEL_SERVICE_NAME!;
export const OTEL_SERVICE_VERSION = process.env.OTEL_SERVICE_VERSION!;

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: OTEL_SERVICE_NAME,
    [ATTR_SERVICE_VERSION]: OTEL_SERVICE_VERSION,
  }),
  traceExporter: new ConsoleSpanExporter(),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
  }),
});
sdk.start();

トレーサーの取得

import opentelemetry from "@opentelemetry/api";
//...
const tracer = opentelemetry.trace.getTracer(
  "instrumentation-scope-name",
  "instrumentation-scope-version"
);
// これで'tracer'を使用してトレーシングができます！

こんな感じでトレーサーを取得します。Next.js の app ルーターでやってみましょう。

import HomeLayout from "@/components/templates/HomeLayout";
import getTodosFeature from "./features/get-todos.feature";

export default async function Home() {
  const { todos } = await getTodosFeature();
  return <HomeLayout todos={todos} />;
}

現状こんな感じになってるので、ここに追加していきます。
ドキュメントの実装例に従って

import HomeLayout from "@/components/templates/HomeLayout";
import getTodosFeature from "./features/get-todos.feature";
import { trace } from "@opentelemetry/api";
import { OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION } from "@/instrumentation";

const tracer = trace.getTracer(OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION);

export default async function Home() {
  const { todos } = await getTodosFeature();
  return <HomeLayout todos={todos} />;
}

TODO リストの登録・削除を行うサーバーアクションにも tracer をセットします。

const tracer = trace.getTracer(OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION);

export default async function createTodoAction(
  prevState: Todo[],
  formData: FormData
): Promise<Todo[]> {
  // 状態変更の分岐
  const action = formData.get("action") as ActionType; // 作成アクション

  if (action === ActionType.CREATE) {
    const input = {
      title: formData.get("title") as string,
      description: formData.get("description") as string,
    };
    return await createActionHandler(input, prevState);
  } // 削除アクション
  if (action === ActionType.DELETE) {
    const id = parseInt(formData.get("id") as string, 10);
    return await deleteActionHandler(id, prevState);
  } // デフォルトは状態を変更しない

  return prevState;
}

スパンの作成

app ルーターのスパンを作成していこうと思います。ドキュメントの例に従って実装すると

export default async function Home() {
  return tracer.startActiveSpan("Home Page Load", async (span) => {
    try {
      const { todos } = await getTodosFeature();
      return <HomeLayout todos={todos} />;
    } catch (e) {
      span.recordException(e);
      span.setStatus({ code: SpanStatusCode.ERROR });
    } finally {
      span.end();
    }
  });
}

これでスパンの作成と終了、例外の補足はできるようになります。
直接書くとやや見づらいので、高階関数 withSpan を作りラップします。

export function withSpan<T extends (...args: any[]) => any>(
  tracer: Tracer,
  name: string,
  fn: T
) {
  return (async (...args: Parameters<T>): Promise<ReturnType<T>> => {
    return tracer.startActiveSpan(name, async (span) => {
      try {
        const result = await fn(...args);
        return result as ReturnType<T>;
      } catch (err) {
        span.recordException(err as Error);
        span.setStatus({ code: SpanStatusCode.ERROR });
        throw err;
      } finally {
        span.end();
      }
    });
  }) as T;
}

この関数を使って以下の様に書き換えます。

async function Home() {
  const { todos } = await getTodosFeature();
  return <HomeLayout todos={todos} />;
}

export default withSpan(tracer, "Home Page Load", Home);

だいぶスッキリしました！細かいことをやりたいときは直接実装することになると思いますが、大体はこのやりかたで事足りそうです。

この状態でホームにアクセスするとコンソールに下記の様なデータが出力されます。

{
  resource: {
    attributes: {
      'host.name': 'e6cfaa081545',
      'host.arch': 'amd64',
      'process.pid': 8492,
      'process.executable.name': 'next-server (v16.0.3)',
      'process.executable.path': '/usr/local/bin/node',
      'process.command_args': [ '/usr/local/bin/node', '/app/node_modules/.bin/next', 'start' ],
      'process.runtime.version': '24.11.1',
      'process.runtime.name': 'nodejs',
      'process.runtime.description': 'Node.js',
      'process.command': '/app/node_modules/.bin/next',
      'process.owner': 'node',
      'service.name': 'frontend',
      'service.version': '1.0'
    }
  },
.
.
.

こんどはこれをコレクターと呼ばれるサーバーに送信するように変更していきます。
現状 docker で以下の様な設定でコンテナを立てています。jeagertracing/all-in-one はデータの蓄積と UI での表示まで特に何の設定もしなくてもやってくれます。開放しているポートはブラウザでの確認用で、テレメトリーデータは HTTP/Proto を利用する場合、4318 番に送信します。なお、今回はローカルでの検証なのでそのまま公開していますが、本番環境ではリバースプロキシ等を前に挟むことが推奨されているようです。

jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
    environment:
      - LOG_LEVEL=debug

コンソールに出力していたデータをコレクターサーバーに送信するように実装を変更しますが、その前に必要なライブラリをインストールします。エクスポーターは３種類から選べて HTTP/Proto, HTTP/JSON, gRPC があります。
今回は HTTP/Proto を使っていきます。

npm install --save @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/exporter-metrics-otlp-proto

インストールしたら、下記の様にコードを変更します。

// instrumentation.ts
const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: OTEL_SERVICE_NAME,
    [ATTR_SERVICE_VERSION]: OTEL_SERVICE_VERSION,
  }),
- traceExporter: new ConsoleSpanExporter(),
+ traceExporter: new OTLPTraceExporter({
+    url: OTEL_SERVICE_ENDPOINT, // http://jaeger:4318/v1/traces　みたいな値が入る
+  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
  }),
});

この状態で JaegerUI にアクセスしてみると。
frontend-in-service

↑ サービスのところに frontend と表示されていますね！これで OK です。さらにトレースを見てみると、
frontend-trace
↑ このようにスパンが表示されていて、app ルータに設定した Home Page Load もちゃんと表示されています。
登録・削除を行うサーバーアクションにも同様の実装をすると。

const tracer = trace.getTracer(OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION);

async function _action(prevState: Todo[], formData: FormData): Promise<Todo[]> {
  // 状態変更の分岐
  const action = formData.get("action") as ActionType; // 作成アクション

  if (action === ActionType.CREATE) {
    const input = {
      title: formData.get("title") as string,
      description: formData.get("description") as string,
    };
    return await createActionHandler(input, prevState);
  } // 削除アクション

  if (action === ActionType.DELETE) {
    const id = parseInt(formData.get("id") as string, 10);
    return await deleteActionHandler(id, prevState);
  } // デフォルトは状態を変更しない

  return prevState;
}
export const tracedAction = withSpan(tracer, "server-actions", _action);

const _create = async (
  { title, description }: { title: string; description: string },
  prevState: Todo[]
): Promise<Todo[]> => {
  const result = await createTodoFeature({ title, description });
  if (result.success && result.todo) {
    return [result.todo, ...prevState];
  }
  return prevState;
};
const createActionHandler = withSpan(tracer, "create-todo", _create);

const _delete = async (id: number, prevState: Todo[]): Promise<Todo[]> => {
  await deleteTodoFeature(id);
  return prevState.filter((todo) => todo.id !== id);
};
const deleteActionHandler = withSpan(tracer, "delete-todo", _delete);

server-actions-trace
↑ こんな感じでサーバーアクションの呼び出しも確認できます。

バックエンド

バックエンドについても同じように実装していきます。

まずは必要なパッケージをインストールします。

npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/sdk-metrics \
  @opentelemetry/sdk-trace-node

npm install @opentelemetry/api @opentelemetry/resources @opentelemetry/semantic-conventions

/*instrumentation.ts*/
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} from "@opentelemetry/semantic-conventions";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { propagation } from "@opentelemetry/api";
import { W3CTraceContextPropagator } from "@opentelemetry/core";

export const OTLP_SERVICE_NAME = process.env.OTLP_SERVICE_NAME!;
export const OTLP_SERVICE_VERSION = process.env.OTLP_SERVICE_VERSION!;
const JEAGER_TRACES_ENDPOINT = process.env.OTLP_JAEGER_TRACES_ENDPOINT!;
const JEAGER_METRICS_ENDPOINT = process.env.OTLP_JAEGER_METRICS_ENDPOINT!;

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: OTLP_SERVICE_NAME,
    [ATTR_SERVICE_VERSION]: OTLP_SERVICE_VERSION,
  }),
  traceExporter: new OTLPTraceExporter({
    url: JEAGER_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: JEAGER_METRICS_ENDPOINT,
    }),
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

export function setupInstrumentation() {
  propagation.setGlobalPropagator(new W3CTraceContextPropagator());
  sdk.start();
}

これを main.ts で読み込みます。

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { setupInstrumentation } from "instrumentation";

async function bootstrap() {
  setupInstrumentation();
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Nest.js ではデコレーターが使えるので計装はそちらに切り出して、必要な個所にデコレーターを実装していきます。

import { SpanStatusCode, trace } from "@opentelemetry/api";
import { OTLP_SERVICE_NAME, OTLP_SERVICE_VERSION } from "instrumentation";
export function TraceSpan(name?: string): MethodDecorator {
  const tracer = trace.getTracer(OTLP_SERVICE_NAME, OTLP_SERVICE_VERSION);
  return (target, propertyKey, descriptor: PropertyDescriptor) => {
    const original = descriptor.value;

    descriptor.value = function (...args: any[]) {
      // メソッド名をデフォルトの span 名に使う
      const spanName =
        name || `${target.constructor.name}.${String(propertyKey)}`;

      return tracer.startActiveSpan(spanName, async (span) => {
        try {
          const result = await original.apply(this, args);

          // async 対応
          if (result && typeof result.then === "function") {
            return result
              .then((value: any) => {
                span.end();
                return value;
              })
              .catch((err) => {
                span.recordException(err);
                span.setStatus({ code: SpanStatusCode.ERROR });
                span.end();
                throw err;
              });
          }
          // 同期のとき
          span.end();
          return result;
        } catch (err) {
          span.recordException(err);
          span.setStatus({ code: SpanStatusCode.ERROR });
          span.end();
          throw err;
        }
      });
    };

    return descriptor;
  };
}

このデコレーターを下記の様に使います。

mport { Injectable } from '@nestjs/common';
import { Todo } from '../models/Todo.model';
import { PrismaService } from 'src/prisma/prisma.service';
import { TodoInput } from '../models/Todo.input';
import { TraceSpan } from 'src/decorators/trace-span.decorator';

@Injectable()
export class CreateTodoUseCase {
  constructor(private readonly prismaService: PrismaService) {}

  @TraceSpan('CreateTodoUseCase.execute')
  async execute(input: TodoInput): Promise<Todo> {
    return await this.prismaService.todo.create({
      data: {
        ...input,
      },
    });
  }
}

これでユースケース全体を１つのスパンとして計測できます。リポジトリなどに使ってもいいです。

伝搬(Propagation)

フロント → API → DB のように一連の流れとしてトレースするには、
トレース ID を HTTP ヘッダに乗せて連携する仕組みが必要です。

フロントもバックエンドも実装は完了しましたが、このままだとフロントはフロント、バックエンドはバックエンドのように個別に表示されてしまいます。
つまりシステム全体を通してのトレースは出来ていません。それを可能にするために伝搬を行います。

フロント

まず、フロントからですが Next.js のドキュメントを確認したところ register という関数で公開する必要があるようでした。
伝搬自体は自動コンテキスト伝搬という仕組みを使って良しなにやってもらいます。その為に UndiciInstrumentation を有効にします。
これによって HTTP リクエストにトレース ID が自動付与されます。

let sdk: NodeSDK | null = null;
export async function register() {
  if (sdk) {
    return;
  }
  sdk = new NodeSDK({
    resource: resourceFromAttributes({
      [ATTR_SERVICE_NAME]: OTLP_SERVICE_NAME,
      [ATTR_SERVICE_VERSION]: OTLP_SERVICE_VERSION,
    }),
    traceExporter: new OTLPTraceExporter({
      url: OTLP_SERVICE_TRACES_ENDPOINT,
    }),
    metricReader: new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({
        url: OTLP_SERVICE_METRICS_ENDPOINT,
      }),
    }),
    instrumentations: [new UndiciInstrumentation()], // 👈ここで伝搬用のIDが発行され、headerに埋め込まれるみたいです。
  });
  sdk.start();
}

バックエンド

バックエンドは下記の様な実装になります。
@opentelemetry/instrumentation-http を有効にすることで、
ヘッダに埋め込まれたトレース ID を受け取り、同じトレースに紐付けられるようになります。

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: OTLP_SERVICE_NAME,
    [ATTR_SERVICE_VERSION]: OTLP_SERVICE_VERSION,
  }),
  traceExporter: new OTLPTraceExporter({
    url: JEAGER_TRACES_ENDPOINT,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: JEAGER_METRICS_ENDPOINT,
    }),
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
+      "@opentelemetry/instrumentation-http": {
+        enabled: true,
+      },
    }),
  ],
});

動作確認

この状態でシステムを利用して jaeger で確認してみましょう。

jaegerUI

zenn でアップロードできるデータ容量の関係で少し見ずらいですが、フロントエンドからバックエンドに処理の流れが伝搬しているのがわかりますね！

ゼロコード計装と手動計装

OpenTelemetry は多数のライブラリに対して「自動計装（ゼロコード）」を提供しています。
一覧はこちら：

自動計装対応ライブラリ・フレームワーク

ただし、ユースケース単位の処理や、ドメイン固有の情報が欲しい場合は
手動計装を併用するのがベスト だと感じました。

その他

今回のテレメトリーと直接関係ないことも含めて検証時に感じたことをまとめます。

AI との向き合い方

最初は AI に頼りながら進めていましたが、
大量の出力に飲まれてしまい、理解が追いつかないことがありました。
結局、最初に一次ドキュメントを丁寧に読む方が効率的でした。
“理解した上で AI を使う” のが一番強いと実感しています。

prisma について

Prisma 7 は Nest.js と相性があまり良くなく断念
今回は Prisma 6.19 を採用
prisma.config.ts に接続情報を書く形式に変更されていた
schema の分割が preview なしで可能になっていた

まとめ

OpenTelemetry + Jaeger を使って、
フロントからバックエンドまでの処理経路を可視化できるようになりました。

分散トレースにより、処理の流れが「見える化」される
ボトルネックの発見が非常に高速になる
自動計装と手動計装を組み合わせるのが現実的

今後は本番環境の監視にも応用しつつ、
SLI/SLO など信頼性観点の運用にも繋げていければと思いました。

Discussion