HackerNews Analyzer デモ

Node.js アプリをエージェントでインストルメントし、ログ、トレース、メトリクス、セッションリプレイを ClickStack に送信する

要約

HackerNews Analyzerをクローンし、.env にOTLPエンドポイントとトークンを設定してから、agentのプロンプトを貼り付けます。バックエンドにOpenTelemetryのインポートは必要ありません。agentがプロセスの起動時に @hyperdx/node-opentelemetry を組み込みます。

所要時間：約10分

HackerNews Analyzerは、公開されているClickHouseデモでホストされるHackerNewsデータセットをクエリするNode.jsアプリです。すべてのチャート、テーブル、検索ボックスは実際のClickHouseクエリであるため、操作のたびにトレースが生成されます。そのメインspanは、バックエンドからClickHouseへのHTTPS呼び出しです。

これは、ローカルのDocker ClickStackに対してブラウザ専用アプリをインストルメントするセッションリプレイ demoとは異なるものです。ここでは、同じアプリでバックエンドのauto-instrumentation、ClickHouseクエリspan、セッションリプレイを利用できます。

​

前提条件

• Node 18 以降と npm
• ClickStack の OTLP/HTTP endpoint とインジェストトークン:
  • ClickHouse Cloud: service を開き、ClickStack → OpenTelemetry exporter を設定 → 環境変数の順に選択します。プロトコルは http/protobuf です。headers には authorization=<ingestion token> を指定し、Bearer プレフィックスは付けません。
  • ローカル collector: http://localhost:4318 を使用します。collector が保護されていない場合は、authorization= を空のままにします。

​

リポジトリをクローンする

HackerNews Analyzerをクローンし、依存関係をインストールして、環境変数テンプレートをコピーします。

git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env

次の手順で .env を設定した後、このディレクトリからインストルメントします。

​

アプリケーションをインストルメントする

1. アプリケーションを実行する

   クローンした hn-news-analyzer ディレクトリで、アプリを起動します。ClickHouse データソースはデフォルトでパブリックな読み取り専用デモクラスターを使用するため、追加の設定なしで実行できます。

   ./run.sh
   

   http://localhost:5001 を開きます。年セレクタ、サマリー統計、アクティビティチャート、上位ユーザーとドメインのテーブル、検索ボックスが表示されます。年を切り替えたり、ストーリーの詳細を確認したりしてみましょう。

   

   この時点ではアプリケーションは実行されていますが、インストルメントされていません。ClickStack にはまだデータが表示されません。テレメトリーの受信を待機しています。

2. 環境を構成する

   SDK は標準の OpenTelemetry エクスポーター変数を読み取ります。これらはソースコードにハードコードされていません。.env を開き、次のように設定します。

   OTEL_SERVICE_NAME=hn-analyzer-api
   OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
   OTEL_TRACES_EXPORTER=otlp
   OTEL_METRICS_EXPORTER=otlp
   OTEL_LOGS_EXPORTER=otlp
   

   OTEL_EXPORTER_OTLP_ENDPOINT は OTLP/HTTP エンドポイント (ポート 4318) です。OTEL_EXPORTER_OTLP_HEADERS は認証 header で、Bearer プレフィックスなしの authorization=<token> 形式です。

   collector で認証を強制していない場合は、token を空のままにします (OTEL_EXPORTER_OTLP_HEADERS=authorization=) 。変数自体は設定しておく必要があります。未設定または完全に空の場合、SDK は初期化をスキップします。

   Browser SDK ではこれらと同じ値を再利用します。vite.config.ts はビルド時にエンドポイントと token を Public bundle に埋め込むため、production 用ではなく、使い捨てのインジェスト token を使用してください。

3. アプリケーションをインストルメントする

   いずれかの方法を選んでください。どの方法でも、最終的には同じインストルメント済みアプリケーションになります。

   エージェントによるインストルメンテーション

   リポジトリをクローンし、.envを設定したら、アプリケーションをインストルメントするため、そのディレクトリでこのプロンプトをコーディングエージェントに貼り付けてください。

   手動インストルメンテーション

   インストルメンテーションは、SDK のインストール、起動コマンドの切り替え、ブラウザ SDK の有効化の3つで構成されます。いずれもアプリケーションのビジネスロジックを変更しません。

   ​

   Node SDK をインストールする

   npm install @hyperdx/node-opentelemetry
   

   ​

   run.sh でラッパーを有効にする

   run.shの末尾にはexec行が2つあります。通常のnode行をコメントアウトし、インストルメント済みの行をコメント解除します。

    # 変更前: 通常の node、インストルメンテーションなし:
   -exec node scripts/entrypoint.js
   +# exec node scripts/entrypoint.js
   
    # 変更後: 同じソースを opentelemetry-instrument でラップ:
   -# exec npx opentelemetry-instrument scripts/entrypoint.js
   +exec npx opentelemetry-instrument scripts/entrypoint.js
   

   引き続きscripts/entrypoint.jsを介して起動してください。このシムはrequire('console')を呼び出すため、コンソールキャプチャによってconsole.logがラップされます。opentelemetry-instrumentでdist/server/index.jsを直接指定するとトレースは送信されますが、ログは通知なく失われます。

   ​

   ブラウザ SDK を有効にする

   npm install @hyperdx/browser
   

   src/web/telemetry.tsで、インポート、HyperDX.init({...})ブロック、およびrecordAction()内のHyperDX.addActionをコメント解除します。

   -// import HyperDX from '@hyperdx/browser';
   +import HyperDX from '@hyperdx/browser';
   
    export function initTelemetry(): void {
   -  // HyperDX.init({
   -  //   url: __OTLP_ENDPOINT__,
   -  //   apiKey: __OTLP_AUTH_TOKEN__,
   -  //   service: 'hn-analyzer-web',
   -  //   tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
   -  //   consoleCapture: true,
   -  //   advancedNetworkCapture: true,
   -  // });
   +  HyperDX.init({
   +    url: __OTLP_ENDPOINT__,
   +    apiKey: __OTLP_AUTH_TOKEN__,
   +    service: 'hn-analyzer-web',
   +    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
   +    consoleCapture: true,
   +    advancedNetworkCapture: true,
   +  });
    }
   

   __OTLP_ENDPOINT__と__OTLP_AUTH_TOKEN__は、バックエンドで使用するものと同じOTEL_EXPORTER_OTLP_*値から、vite.config.tsによって注入されるコンパイル時定数です。

   インジェストトークンは公開ブラウザバンドルに埋め込まれるため、ネットワークタブを確認すれば誰でも読み取れます。使い捨てのトークンを使用してください。

   事前インストルメント済みブランチを使用する

   インストルメンテーションを省略し、すでにインストルメント済みのアプリケーションから始めるには、instrumentedブランチをチェックアウトします。

   git checkout instrumented
   npm install
   

   SDK を削除する場合を除き、このブランチで./reset.shを実行しないでください。

4. トラフィックを生成してテレメトリーを表示する

   新しい起動コマンドとビルドし直したブラウザーバンドルを反映するには、アプリケーションを再起動します。

   # Ctrl-C the previous run, then:
   ./run.sh
   

   起動バナーに、/v1/traces、/v1/metrics、/v1/logs について「Health check passed」が3行表示されることを確認します。ブラウザのタブを再読み込みしてViteが更新済みのバンドルを配信するようにし、年を切り替えてストーリーをクリックし、トラフィックを生成します。

   ClickStack UIを開きます。

   1. Search に移動し、過去5分間に絞り込みます。hn-analyzer-api のログがストリーミング表示されます。

   

   2. リクエストをクリックして、トレースを上流にたどります。Expressハンドラーのスパン、実際のネットワーク所要時間を示す sql-clickhouse.clickhouse.com 向けの子HTTPスパン、および同じトレース上で相関付けられた console.log レコードが表示されます。

   

   3. Session Replay を開くと、トレースタイムラインと同期したブラウザセッションの動画をシークしながら再生できます。

   

   ログ、メトリクス、トレース、セッションリプレイはすべて同じUIに集約され、同じクエリ言語を使用し、自動的に相関付けられます。

​

詳しくはこちら

• HackerNews Analyzer: このガイドでインストルメントするデモリポジトリ。
• セッションリプレイ: 機能の概要、SDK オプション、プライバシー制御。
• セッションリプレイ Demo: ローカルの ClickStack インスタンスで試せる自己完結型デモ。
• ClickStack 入門: ClickStack をデプロイし、最初のデータを取り込むためのガイド。
• サンプルデータセット一覧: そのほかのサンプルデータセットとガイド。