OpenTelemetry と ClickStack を使って NextJS アプリケーションを計装する

ClickStackを選ぶ理由 #

すでにリアルタイム分析の基盤として ClickHouse をご利用中であれば、同じ選択をした仲間が世界中に数多く存在します。ClickHouse は社内外向けの分析を問わず、頼れるデータベースとしての地位を急速に確立しており、最大級のユーザー向け分析ワークロードを支えています。従来のデータウェアハウスでは、現代のアプリケーションが求める高同時実行性や低レイテンシクエリに対応しきれないため、非常に多くの企業が ClickHouse への移行を進めています。

しかし、ClickHouse を分析に適した存在にしている高速なスキャン、高い圧縮率、膨大なデータ量の処理能力、そして高カーディナリティなワークロードへの対応力といった強みは、ログ、トレース、メトリクスの処理にもそのまま最適です。さらにオープンソースライセンス、優れた相互運用性、OpenTelemetry へのネイティブ対応 (独自のワイドイベントを保存できる柔軟性も含む) を兼ね備えており、オブザーバビリティの強固な基盤となります。

オブザーバビリティと分析を別々の島として扱うべきではないという考え方は、私たち独自のものではありません。Sierra の Arup Malakar 氏が最近のブログで次のように述べています。

「オブザーバビリティと分析を別々の島と考えるのではなく、ClickHouse のような優れたコンピュートエンジンを活用した単一のデータ課題として捉えられるようになれば、本当に素晴らしいことです。結局のところ、すべてはデータであり、あとはそこにアクセスする手段が必要なだけなのです」

Sierra、Arup Malakar 氏

ClickStack のリリースにより、リアルタイム分析とオブザーバビリティの統合はかつてないほど容易になりました。ClickStack SDK や任意の OpenTelemetry SDK を使ってアプリケーションを計装するだけで、アプリケーションデータとエラー、パフォーマンスメトリクス、各種課題との関連付けをすべて同じ場所ですぐに開始できます。

本記事では、この手順がいかに簡単であるかを実践的な例で解説します。題材として、1.8 兆行を超えるデータを抱え、週に 150 万件以上のクエリを処理する ClickHouse 駆動の Next.js アプリケーション、ClickPy を計装します。

ClickPy #

私たちが数年前から運用している ClickPy は、Python エコシステムの中核パッケージリポジトリである PyPI のダウンロード状況を探索できるプロジェクトです。PyPI では毎日約 20 億件のダウンロードが発生しており、開発者がどのライブラリに依存しているかを知るための豊富なメタデータソースとなっています。

データセットの規模は莫大に拡大しました。本番環境で数年運用した現在、メインテーブルには 2016 年以降の大規模な実際の Python パッケージダウンロードを表す約 1.8 兆行のデータが保存されています。この規模にもかかわらずクエリ応答は 1 秒未満を維持しており、大容量かつ高同時実行のワークロードを難なくこなす ClickHouse の能力を実証しています。

ClickPy の詳細や内部の仕組みについては、2024年に1 兆行を達成した際に公開したブログ記事をご覧ください。

このアプリは、数ページで構成されるシンプルな React + Next.js フロントエンドであり、チャート描画には Apache ECharts を、ClickHouse へのクエリ発行には公式クライアントを用いた Node.js を使用しています。SSR/CSR のハイブリッドモデルを採用しており、サーバー側で ClickHouse からデータを取得して props として渡すため初期ロードが高速で、インタラクティブ性と応答性を高めるためにチャートはクライアント側でレンダリングされます。マテリアライズドビューと賢いテーブル選択のおかげで、数兆行の規模でもパフォーマンスが低下せず、迅速な初回ロード、軽快なチャート描画、スムーズなリアルタイム探索を実現しています。このシンプルさゆえに計装が容易でありながら、実際の問題を浮かび上がらせるのに十分なコンポーネントが揃っているため、優れた検証例となります。今回は、さらなるパフォーマンス向上の余地があるか、また特定のパッケージの特性によってダッシュボードのロードが遅くなっていないかを検証したいと考えました。

Next.js を OTel と ClickStack で計装する #

ClickStack は、データベースとしての ClickHouse、UI としての HyperDX、データ収集としての OpenTelemetry という 3 つの要素を統合したものです。構成はこれだけです。複数のツールを行き来する負担なしに、完全なオブザーバビリティスタックが手に入ります。

ClickPy における今回の目的では、アプリケーションからセッションとトレースを収集することに主眼を置きます。セッションによってユーザーのブラウザ操作をリプレイできる一方、トレースは Vercel 上でホストされている Node.js サーバーサイドコードとブラウザ上で動作する React フロントエンドの双方から取得できます。

計装にはいくつかの選択肢があります。素の OpenTelemetry SDK を直接組み込むことも可能ですが、ClickStack は開発者体験を向上させる独自の SDK も提供しています。たとえば Node.js SDK には例外キャプチャ機能が組み込まれており、実用的なデフォルト設定が最初から用意されているため、わずか数行のコードで簡単に立ち上げられます。フロントエンド側では、ClickStack JavaScript SDK を使うことでブラウザ内のトレース取得をスムーズに開始でき、ユーザーエクスペリエンスの可視化とリプレイを可能にするユーザーセッションに加え、バックエンドとの関連付けも容易に行えます。

ClickStack のデプロイ #

ClickStack をローカル環境に最も素早くデプロイする方法は、ClickHouse、HyperDX、および OTel コレクターのエンドポイントが含まれたオールインワンイメージを使用することです。

1docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

これにより、HyperDX がローカルのポート 8080 で公開されます。http://localhost:8080 の UI にアクセスし、ユーザーを作成してください。すべてのソースが自動的に作成されます。

ClickHouse Cloud #

ClickHouse Cloud ユーザー向けには、HyperDX がプライベートプレビューとして提供されており、リクエストに応じて有効化できます。HyperDX は任意のサービスに対して起動可能であり、認証は自動的に処理されるため、ユーザーがアカウントを別途作成する必要はありません。

本稿執筆時点では、Cloud 上で取り込みエンドポイントが直接提供されていないため、取り込み処理のために OTel コレクターをローカルで実行する必要があります。以下のコマンドを実行して開始してください。

1curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/deployment/_snippets/otel-cloud-config.yaml
2
3# modify to your cloud endpoint
4export CLICKHOUSE_ENDPOINT=
5export CLICKHOUSE_PASSWORD=
6# optionally modify 
7export CLICKHOUSE_DATABASE=default
8
9# osx
10docker run --rm -it \
11  -p 4317:4317 -p 4318:4318 \
12  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
13  -e CLICKHOUSE_USER=default \
14  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
15  -e CLICKHOUSE_DATABASE=${CLICKHOUSE_DATABASE} \
16  --user 0:0 \
17  -v "$(pwd)/otel-cloud-config.yaml":/etc/otel/config.yaml \
18  -v /var/log:/var/log:ro \
19  -v /private/var/log:/private/var/log:ro \
20  otel/opentelemetry-collector-contrib:latest \
21  --config /etc/otel/config.yaml

コレクターがデプロイされたら、HyperDX の UI に戻り、トレースとセッションのソースを作成します。

ブラウザ側の計装 #

今回の Next.js アプリケーションには、クライアント側とサーバー側の両方のコンポーネントがあります。クライアント側には ClickStack Browser SDK を使用します。素の OpenTelemetry SDK (ClickStack と完全な互換性あり) を使うこともできますが、ClickStack JavaScript SDK には大きな利点があります。それはセッションリプレイ機能と、簡単なフラグ設定で有効化できる HTTP リクエストのコンソールログやネットワークキャプチャなどの組み込み機能です。

計装に必要なコードはわずか数行です。まずパッケージをインストールします。

1npm install @hyperdx/browser

次に、アプリの起動時に確実に読み込まれる場所で SDK を初期化する必要があります。ClickPy の場合、何よりも先にクッキー同意バナーが表示されるようになっており、layout.js で追加されています。ここが初期化コードを追加するのに最適な場所です。

1import HyperDX from '@hyperdx/browser';
2
3HyperDX.init({
4 url: process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318',
5 apiKey: process.env.NEXT_PUBLIC_HYPERDX_API_KEY || '',
6 service: 'clickpy-frontend',
7 tracePropagationTargets: [
8   /localhost:\d+/i,
9   new RegExp(process.env.NEXT_PUBLIC_DOMAIN || 'localhost', 'i')
10 ],
11 consoleCapture: true,
12 advancedNetworkCapture: true,
13});

ここで注目すべき点がいくつかあります。

• サービス名 - ブラウザからのスパンには clickpy-frontend というタグが付けられ、サーバーで生成されたスパンと簡単に区別できます。
• OTLP エンドポイント – デフォルトでは、ローカルの OpenTelemetry コレクター (localhost:4318) にトレースを送信します。Vercel などのプラットフォームにデプロイする場合は、NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT 環境変数経由で設定します。
• API キー – ローカルコレクターで認証を使用していない場合は不要ですが、パブリックエンドポイントを使用し、ClickPy をインターネット上に公開する場合は必須です。これは NEXT_PUBLIC_HYPERDX_API_KEY で処理します。
• コンソールおよびネットワークキャプチャ – consoleCapture と advancedNetworkCapture を有効にすると、SDK がコンソールログおよびリクエスト/レスポンスの詳細 (ヘッダーやボディを含む) を自動的に記録します。
• トレース伝播 – ここが重要なポイントです。tracePropagationTargets を定義することで、ブラウザからサーバーへのリクエストに traceparent ヘッダーが確実に付与されます。これにより、ブラウザで生成されたスパンが同じトレースとしてサーバー側で生成されたスパンとリンクし、フロントエンドとバックエンドにまたがる完全な分散トレースが実現します。

OpenTelemetry のスパンとは、コンテキストやメタデータとともにキャプチャされる、HTTP リクエストやデータベースクエリなどの作業単位を表す計測された操作です。トレースは複数のスパンの集まりであり、サービス全体にわたるリクエストやワークフローのエンドツーエンドの経路を示します。トレース伝播を利用すると、クライアントとサーバーの双方からのスパン (たとえばユーザーがパッケージページでフィルターを適用した際など) が同じトレースにリンクされ、一連のインタラクションを完全に繋がった状態で把握できます。今回の例では、ユーザーがダッシュボードページで Python パッケージを開いたりフィルターをかけたりする操作がトレースとなり、ClickHouse へのクエリなどの作業単位がスパンとして表されます。

この設定だけで、ClickPy のすべてのページロード、ユーザーの操作、ブラウザ内のネットワーク呼び出しが ClickStack に直接送信され、サーバー側のトレースやログと関連付ける準備が整います。

Node.js サーバー側の計装 #

サーバー側でも同様にいくつかの選択肢があります。Node.js 向けの素の OpenTelemetry、Vercel の Next.js 向け SDK、または ClickStack Node.js SDK (OTel と完全互換で、便利なデフォルト設定を備えています) です。ClickPy は Vercel 上で動作するため、後者 2 つのいずれかが最も適しています。

この例では、HTTP リクエストとレスポンスのキャプチャを標準で備えている ClickStack SDK を使用します。ClickPy ではサーバーコンポーネントが HTTP 経由で ClickHouse にクエリを送信するため、リクエストボディに観測・分析対象としたい SQL クエリが含まれており、この機能が特に役立ちます。

ここでも対象のパッケージをインストールします。

1npm add @hyperdx/node-opentelemetry

今回はやや古いバージョンである Next.js 14 を使用しているため、instrumentation フックを有効にする必要があります。これには、next.config.js ファイルで適切なフラグを有効にするだけです。

以降のバージョン (Next.js 15 以上) では、この手順は不要です。

1/** @type {import('next').NextConfig} */
2const nextConfig = {
3  experimental: {
4    instrumentationHook: true,
5  },
6};
7
8module.exports = nextConfig;

これを有効にした上で、プロジェクトルート (構成によっては /src) に instrumentation.js を作成し、SDK を初期化する register 関数を用意します。この関数は、サーバー起動時に Next.js によって呼び出されます。

1// instrumentation.js
2export async function register() {
3  if (process.env.NEXT_RUNTIME === 'nodejs') {
4    const { initSDK } = await import('@hyperdx/node-opentelemetry');
5    initSDK({
6      service: 'clickpy',
7      // Auto-instruments Next.js + HTTP and captures headers/bodies
8      advancedNetworkCapture: true,
9      // You can add more instrumentations here if you need them later:
10    });
11  }
12}

service パラメータにより、サーバー側のスパンにはサービス名 clickpy が付与され、バックエンド由来であることが明確になります。advancedNetworkCapture を有効にすることで、ClickHouse の SQL クエリを含む HTTP リクエストとレスポンスの全容もキャプチャされるため、パフォーマンスのより深い可視化が可能になります。

SDK の詳細設定は、すべて環境変数を通じて行います。シェルまたは .env.local ファイルで 4 つの主要な変数を設定します。

1OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
2HYPERDX_API_KEY=38a8701c-3d72-49f8-8d96-aedaf77d0d55
3OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST=accept-encoding,host,traceparent,user-agent
4OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST=accept-encoding,host,traceparent,user-agent

ここでも、OTLP エンドポイントとオプションの API キーの設定を指定します。2 つのヘッダーキャプチャ用変数では、クライアントおよびサーバーの呼び出しでどのリクエストヘッダーを記録するかを指定します。これにより、authorization などの機密ヘッダーを除外しつつ、traceparent などの有用なコンテキストを確実に保持できます。リクエストやレスポンスのボディをマスキングする必要がある場合や、レスポンスヘッダーのキャプチャを制限したい場合にも、他のオプションが利用可能です。

計装の拡張 #

各 SDK は標準状態でも充実した計装機能を提供しますが、さらに詳細な情報が必要になる場合もあります。今回のケースでは、クエリをダッシュボード上の視覚コンポーネントと直接紐付けたいと考えました。各コンポーネントには名前とパラメータがあるため、これらもキャプチャします。また、返された行数やクエリ設定とともに、各 ClickHouse リクエスト全体の所要時間も記録したいと考えます。これを実現する最も簡単な方法は、各クエリが発行されるタイミングでカスタムスパンを作成し、クエリ完了時に閉じることです。ClickPy 内のすべてのクエリは、以下に示す単一の query 関数を経由するため、実装はシンプルです。

1async function query(query_name, query, query_params) {
2    const results = await clickhouse.query({
3        query: query,
4        query_params: query_params,
5        format: 'JSONEachRow',
6        clickhouse_settings: getQueryCustomSettings(query_name)
7    })
8    let query_link = `${process.env.NEXT_PUBLIC_QUERY_LINK_HOST || process.env.CLICKHOUSE_HOST}?query=${base64Encode(query)}`
9    if (query_params != undefined) {
10        const prefixedParams = Object.fromEntries(
11            Object.entries(query_params)
12                .filter(([, value]) => value !== undefined)
13                .map(([key, value]) => [`param_${key}`, Array.isArray(value) ? `['${value.join("','")}']` : value])
14        );
15        query_link = `${query_link}&tab=results&${Object.entries(prefixedParams).map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`).join('&')}`
16    }
17    return Promise.all([Promise.resolve(query_link), results.json()]);
18}

カスタムスパンを作成するには、query メソッドの開始時に現在の OpenTelemetry トレース上で startSpan を呼び出し、ClickHouse クエリが終了して関数が戻る直前に end() でクローズします。その間で、クエリ応答時間などの統計情報をスパン属性としてキャプチャします。コードの主要部分は以下のとおりです (関数全体のコードはこちら)。

1xport async function query(query_name, query, query_params) {
2  const span = tracer.startSpan(query_name, {
3    attributes: {
4      'db.system': 'clickhouse',
5      // Add a short/obfuscated statement if you want. Full SQL can be large/PII.
6      // 'db.statement': truncate(query),
7      'db.parameters': truncate(safeJson(query_params ?? {})), // ← your params
8    },
9  });
10
11  try {
12    const start = performance.now();
13    // run the query inside the span's context
14    const results = await context.with(trace.setSpan(context.active(), span), () =>
15      clickhouse.query({
16        query,
17        query_params,
18        format: 'JSONEachRow',
19        clickhouse_settings: getQueryCustomSettings(query_name),
20      })
21    );
22
23    const data = await results.json(); // materialize rows to count
24    const end = performance.now();
25    // annotate outcome
26    if (span.isRecording()) {
27      span.setAttribute('db.response_time_ms', Math.round(end - start));
28      span.setAttribute('db.rows_returned', Array.isArray(data) ? data.length : 0);
29      // attach useful customs
30      span.setAttribute('clickhouse.settings', truncate(safeJson(getQueryCustomSettings(query_name))));
31    }
32
33    span.setStatus({ code: SpanStatusCode.UNSET });
34    span.end();
35    return Promise.all([Promise.resolve(query_link), Promise.resolve(data)]);
36  } catch (err) {
37    if (span.isRecording()) {
38      span.recordException(err);
39      span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
40    }
41    span.end();
42    throw err;
43  }
44}

この計装の結果、HTTP リクエストとペイロードを記録する自動キャプチャの ClickHouse.query スパンと並ぶ形で、各 ClickHouse クエリごとに追加のカスタムスパンが生成されます。

データの分析 #

ClickPy の計装が完了したため、オブザーバビリティデータの収集と探索が可能になりました。アプリ自体は Vercel にデプロイされており、clickpy.clickhouse.com で一般公開されています。Vercel へのデプロイには、前述の環境変数を設定する必要があります。

テレメトリを受信するために、SSL 経由で OpenTelemetry コレクターのエンドポイントを実行しています。公開されている ClickPy インスタンスからのデータは、sql.clickhouse.com にあるパブリックデモクラスターの otel_clickpy データベースに取り込まれます。ご自身の SQL クエリを使って自由に探索してみてください。また、play-clickstack.clickhouse.com にある HyperDX のパブリックインスタンスで、このデータを直接可視化することもできます。トレースは ClickPy Traces、セッションリプレイは ClickPy Sessions というソース名で確認できます。

たとえば、ClickPy を開いて任意のパッケージに移動し、時間でフィルターをかけると、該当するセッションが HyperDX のパブリックインスタンスに表示されます。セッションを再生して各ユーザー操作を確認したり、処理の過程で生成されたトレースやスパンをドリルダウンしたりできます。これにより、ユーザーフローの全体像と各ステップにおける詳細なパフォーマンス内訳の両方が得られ、デバッグ、最適化、実際の利用状況の把握に威力を発揮します。

カスタム計装のおかげで、各 ClickHouse クエリの詳細を確認し、関連する可視化コンポーネントと発行されたクエリの両方を追跡できている点に注目してください。

セッションリプレイは個別のユーザー問題のデバッグに役立ちますが、データをより大局的に捉えることで傾向を把握し、アプリケーション全体のパフォーマンス向上につながる要素を特定することもできます。

ClickStack の強みの 1 つは柔軟性です。ClickHouse の JSON 型による Schema-on-Write と、Schema-on-Read の両方をサポートしています。後者は、挿入時にすべてを事前処理しない場合でも、ClickHouse 組み込みの文字列関数を使用してクエリ実行時に生の文字列から値を抽出できるため便利です。

ユーザーがパッケージページに移動するたびに、documentLoad スパンがトリガーされます。そのスパンの location.href 属性にはパッケージの URL が含まれています。SpanName: documentLoad でフィルタリングし、location.href からパッケージ名を抽出することで、各ユーザーがアクセスしたパッケージを確認できます。ClickHouse の SQL 関数である splitByChar を利用して URL からパッケージ名を切り出している点に注目してください。これにより、実質的に読み取り時にスキーマを生成しています。

各 ClickHouse クエリのスパンに可視化コンポーネント名をタグ付けすることで、異なる可視化コンポーネント間のパフォーマンスの推移を簡単に追跡・比較できます。db.response_time_ms を参照すれば、可視化タイプごとのクエリコストが分かります。以下では、SpanName (この場合は可視化名) でグループ化し、これを時系列でプロットしています。

getPackageRanking クエリが最も重く、平均して 4 秒以上かかっていることが一目で分かります。このコンポーネントは、総ダウンロード数に関してそのパッケージが同系統の中でどの位置にランク付けされているかを表示するものです。

ユーザー体験に基づき、このクエリが最も遅いのではないかと推測していました。このコンポーネントは非同期で読み込まれますが、ページ上の他のコンポーネントと比べてパフォーマンスの差がこれほど顕著であることが客観的に示されたため、パフォーマンス改善の取り組みが始まりました。

各可視化コンポーネントの時系列パフォーマンスを見ると、他のコンポーネントでもレイテンシが急激に跳ね上がっている箇所が見られます。可視化タイプを確認すると、それらはすべて clickpy.clickhouse.com のトップページに由来し、「急上昇 (emerging)」や「注目 (hot)」のパッケージを表示している部分でした。これはサイトのアクティビティとおおむね相関していますが、これらの急増の原因を究明するため、より詳細な調査を行う契機となりました。

ClickHouse Cloud サービスは多くの公開デモをホストしているため、クエリ負荷の変動が原因の特定を難しくする側面もあります。また、ユーザーが sql.clickhouse.com で公開データセットを探索する際に任意の SQL クエリを実行できる環境でもあります。こうしたレベルでアプリ内部を詳細に把握できた結果、いくつもの最適化作業が開始されました。

オブザーバビリティデータとアプリケーションデータの相関 #

可視化レイヤーとしての HyperDX の枠を超え、他の可視化ツールを使用して、まったく同一のオブザーバビリティデータに対して SQL でより高度な分析を行うこともできます。これは、オブザーバビリティデータを単なるデータ課題の 1 つとして扱うメリットを示す好例です。

以下の例では ClickHouse Cloud の可視化機能を使用していますが、Grafana や Superset などのツールを使っても同様の可視化を簡単に構築できます。

シンプルな問いの例: ユーザーが ClickPy で最も頻繁に探索している人気パッケージはどれか？

ここでも、location.href カラムからパッケージを抽出し、rum.sessionId の値を使用して過去 12 時間におけるユニークビジター数を特定します。

1SELECT splitByChar('/', SpanAttributes['location.href'])[-1] as Package, count() as visits, uniq(ResourceAttributes['rum.sessionId']) as sessions
2FROM otel_clickpy.otel_traces WHERE Package !=''
3GROUP BY Package 
4ORDER BY visits DESC 
5LIMIT 20

上記のシンプルな例は、大半のオブザーバビリティツールでも実現できるでしょう。しかし、さらに踏み込んで、アプリケーションデータとオブザーバビリティデータを相関させたい場合はどうでしょうか。

たとえば、人気の高いパッケージほど ClickPy の動作が目に見えて遅くなっていないか、という疑問を私たちは以前から抱いていました。人気の高いパッケージほど ClickHouse 内の行数が増えるため、直感的には遅くなりそうに思えます。しかし、増分マテリアライズドビューを採用していればその影響は相殺されるはずです。挿入時に集計を計算し、バックグラウンドマージを活用することで、プロジェクトあたりの行数を比較的一定に保てるからです。

増分マテリアライズドビューは、SELECT クエリの結果を永続化することで、計算処理をクエリ実行時から挿入時へとシフトさせます。新しい行が挿入されると定義された SQL クエリが即座に適用され、結果がターゲットテーブルに書き込まれます。重い計算はすでに実行済みであるため、このターゲットに対するクエリは大幅に高速化されます。その後、バックグラウンドマージによって同一の GROUP BY キーに対する部分集計が統合され、長期にわたって正確かつ効率的な結果が保証されます。詳細はドキュメントをご覧ください。

この検証には、ダウンロード数の多いパッケージ (約 1.8 兆行のデータへより多く寄与しているパッケージ) に対するクエリが、ダウンロード頻度の低いパッケージに対するクエリよりも遅くなっているかを問うクエリが必要です。ClickPy が適切に設計されていれば、大規模なパッケージであっても体感できるほどの遅延は生じないはずです。

これに答えるには、オブザーバビリティデータとアプリケーションデータを関連付ける必要があります。

まず、アプリケーションデータから各パッケージの総ダウンロード数 (pypi.pypi_downloads_per_day マテリアライズドビュー経由) を取得します。

1SELECT
2  project,
3  sum(count) AS total
4FROM pypi.pypi_downloads_per_day
5GROUP BY project

ClickPy におけるパッケージ単位のパフォーマンスを測定するには、ClickHouse からの平均クエリ応答時間、すなわち db.response_time_ms カラムを使用します。パッケージ名はスパン属性内に JSON 文字列として埋め込まれているため、JSONExtractString 関数を用いた Schema-on-Read により抽出します。

1SELECT
2  JSONExtractString(SpanAttributes['db.parameters'], 'package_name') AS project,
3  avg(toUInt64OrZero(SpanAttributes['db.response_time_ms'])) AS avg_performance
4FROM otel_clickpy.otel_traces
5WHERE JSONExtractString(SpanAttributes['db.parameters'], 'package_name') != ''
6  AND toUInt64OrZero(SpanAttributes['db.response_time_ms']) > 0
7GROUP BY project
8ORDER BY avg_performance DESC

これら 2 つのクエリ結果セットを INNER JOIN で結合し、ClickHouse Cloud 上で散布図 (X 軸にダウンロード数、Y 軸に平均応答時間) を作成して、人気度とページやクエリのレイテンシとの間に相関関係があるかを視覚的に確認します。設計どおりに機能していれば、左下から右上に線形増加するのではなく、ほぼフラットなトレンドになるはずです。

図に示すように、調査を要するいくつかの例外値を除けば、トレンドはおおむね平坦です。大規模なパッケージであってもパフォーマンスが劣化していないことが確認でき、心強い結果となりました。

最後のステップとして、ClickHouse の統計関数を活用して相関関係を検証します。corr 関数は 2 つの数値カラム間のピアソンの積率相関係数を計算します。値が 1 であれば強い正の線形相関、-1 であれば強い負の相関、0 であれば無相関を示します。

クエリを拡張し、パッケージのダウンロード数 (合計) と、ClickHouse クエリの平均応答時間および最大応答時間という 2 つのパフォーマンス指標との相関を計算します。

1SELECT
2    corr(total, max_performance),
3    corr(total, avg_performance)
4FROM
5(
6    SELECT
7        d.project,
8        d.total,
9        t.max_performance,
10        t.avg_performance
11    FROM
12    (
13        SELECT
14            project,
15            sum(count) AS total
16        FROM pypi.pypi_downloads_per_day
17        GROUP BY project
18        ORDER BY total DESC
19        LIMIT 1000
20    ) AS d
21    INNER JOIN
22    (
23        SELECT
24            JSONExtractString(SpanAttributes['db.parameters'], 'package_name') AS project,
25            max(toUInt64OrZero(SpanAttributes['db.response_time_ms'])) AS max_performance,
26            avg(toUInt64OrZero(SpanAttributes['db.response_time_ms'])) AS avg_performance,
27            quantile(0.9)(toUInt64OrZero(SpanAttributes['db.response_time_ms'])) AS p90_performance
28        FROM otel_clickpy.otel_traces
29        WHERE (JSONExtractString(SpanAttributes['db.parameters'], 'package_name') != '') AND (toUInt64OrZero(SpanAttributes['db.response_time_ms']) > 0)
30        GROUP BY project
31        ORDER BY max_performance DESC
32    ) AS t ON d.project = t.project
33    ORDER BY rand(), d.total ASC
34    LIMIT 1000
35)

これらの結果から、ダウンロード数と平均または最大の応答時間との間には、ごくわずかな相関しかないことが示唆されます。

まとめ #

OpenTelemetry と ClickStack を使ったアプリケーションの計装は、わずか数行のコードで完了するにもかかわらず、パフォーマンスや挙動に関する深い可視性を即座にもたらします。ClickHouse にトレースとセッションリプレイが集約されることで、遅延クエリの特定、異常値の調査、そして実際のユーザー体験のリアルタイムな把握が可能になります。

さらに重要な点として、ClickStack は従来のオブザーバビリティの枠を超えています。分析データとオブザーバビリティデータが同一エンジン内で並んで保持されるため、アプリケーションメトリクス (パッケージのダウンロード数など) とパフォーマンスメトリクス (クエリレイテンシなど) を直接関連付けることができます。この統合された視点によってオブザーバビリティは 1 つのデータ課題へと変貌します。これはオブザーバビリティコスト最適化プレイブックや Kubernetes オブザーバビリティ実践ガイドでも詳しく述べているコンセプトであり、ClickStack はまさにこの課題を解決するために作られています。シート課金から脱却し、自社でデータをコントロールしたいチームにとって、強力な New Relic 代替手段となります。

本記事ではトレースに焦点を当て、ログについては扱いませんでした。今後の記事では、ClickStack においてログを収集し、トレースと関連付けることがいかに簡単であり、デバッグや洞察の獲得において同様に強力であるかを紹介する予定です。