Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickStack で JVM メトリクスを監視する

View as MarkdownEdit this pageReport an issueSet up docs MCP

既存のJVMアプリケーションとのインテグレーション

このセクションでは、OpenTelemetry Java agent を使用して既存のJVMアプリケーションから ClickStack にメトリクスを送信するための設定方法を説明します。

本番環境のセットアップを行う前にインテグレーションを試したい場合は、デモデータセットのセクションにあるデモデータセットを使用してテストできます。

前提条件
  • 稼働中の ClickStack インスタンス
  • 既存の Java アプリケーション (Java 8 以降)
  • JVM の起動引数を変更できること

ClickStack の API key を取得する

OpenTelemetry Java agent はデータを ClickStack の OTLP エンドポイントに送信しますが、その際に認証が必要です。

  1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
  2. 必要に応じてアカウントを作成するか、ログインします
  3. Team Settings → API Keys に移動します
  4. インジェスト API key をコピーします
ClickStack API key

OpenTelemetry Java agent をダウンロードする

OpenTelemetry Java agent の JAR ファイルをダウンロードします。

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar

これにより、agent は現在のディレクトリにダウンロードされます。デプロイ先に応じて適切な場所 (例: /opt/opentelemetry/ やアプリケーションの JAR と同じ場所) に配置できます。

JVM の起動引数を設定する

Java agent を JVM の起動コマンドに追加します。agent は JVM メトリクスを自動的に収集し、ClickStack に送信します。

オプション 1: コマンドラインフラグ
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-java-app \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=none \
  -Dotel.traces.exporter=none \
  -jar my-application.jar

以下を置き換えてください。

  • opentelemetry-javaagent.jar → agent JAR のフルパス (例: /opt/opentelemetry/opentelemetry-javaagent.jar)
  • my-java-app → サービスが識別しやすい名前 (例: payment-service, user-api)
  • YOUR_API_KEY → 上記の手順で取得した ClickStack の API key
  • my-application.jar → アプリケーションの JAR ファイル名
  • http://localhost:4318 → ClickStack のエンドポイント (ClickStack が同じマシンで動作している場合は localhost:4318、それ以外の場合は http://your-clickstack-host:4318 を使用します)
オプション 2: 環境変数

または、環境変数を使用します。

export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="my-java-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"
export OTEL_TRACES_EXPORTER="none"

java -jar my-application.jar

以下を置き換えてください。

  • opentelemetry-javaagent.jar → agent JAR のフルパス
  • my-java-app → サービス名
  • YOUR_API_KEY → ClickStack の API key
  • http://localhost:4318 → ClickStack のエンドポイント
  • my-application.jar → アプリケーションの JAR ファイル名

HyperDX でメトリクスを確認する

アプリケーションを agent 付きで起動したら、メトリクスが ClickStack に送られていることを確認します。

  1. http://localhost:8080 (または ClickStack の URL) で HyperDX を開きます
  2. Chart Explorer に移動します
  3. jvm. で始まるメトリクスを検索します (例: jvm.memory.used, jvm.gc.duration, jvm.thread.count)

デモデータセット

アプリケーションをインストルメントする前に JVM メトリクスのインテグレーションを試したいユーザー向けに、安定して中程度のトラフィックがある中規模マイクロサービスにおける、現実的な JVM の挙動を示す事前生成済みメトリクスを含むサンプルデータセットを提供しています。

サンプルデータセットをダウンロードする

# Gauge メトリクス（メモリ、スレッド、CPU、クラス）をダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

# sum メトリクス（GC イベント）をダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl

このデータセットには 24 時間分の JVM メトリクスが含まれており、次の内容を確認できます。

  • 定期的なガベージコレクションイベントに伴うヒープメモリの増加
  • スレッド数の変動
  • 現実的な GC 一時停止時間
  • クラス読み込みのアクティビティ
  • CPU 使用率のパターン

ClickStack を起動する

まだ ClickStack を起動していない場合は、次を実行します。

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

ClickStack が完全に起動するまで少し待ってください。

デモデータセットをインポートする

# Gauge メトリクス（メモリ、スレッド、CPU、クラス）をインポート
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
" < jvm-metrics-gauge.jsonl

# sum メトリクス（GC イベント）をインポート
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
" < jvm-metrics-sum.jsonl

これにより、メトリクスが ClickStack の Metrics テーブルに直接インポートされます。

デモデータを確認する

インポート後は、次の手順で確認します。

  1. http://localhost:8080 で HyperDX を開き、ログインします (必要に応じてアカウントを作成してください)
  2. Search ビューに移動し、ログソースを Metrics に設定します
  3. 時間範囲を 2025-12-06 14:00:00 - 2025-12-09 14:00:00 に設定します
  4. jvm.memory.used または jvm.gc.duration を検索します

デモサービスのメトリクスが表示されるはずです。

ダッシュボードと可視化

ClickStack で JVM アプリケーションを監視できるように、JVM メトリクスの主要な可視化を含む、あらかじめ用意されたダッシュボードを提供しています。

ダッシュボード設定をダウンロードする

ダッシュボード設定ファイルをダウンロード。

あらかじめ用意されたダッシュボードをインポートする

  1. HyperDX を開き、Dashboards セクションに移動します
  2. 右上の三点メニューから Import Dashboard をクリックします
ダッシュボードのインポートボタン
  1. jvm-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします
インポートを完了

ダッシュボードを表示する

ダッシュボードは、すべての可視化が事前に設定された状態で作成されます。

Kafka メトリクス ダッシュボード

トラブルシューティング

Agent が起動しない

agent JAR が存在することを確認してください:

ls -lh /path/to/opentelemetry-javaagent.jar

Javaのバージョン互換性を確認してください (Java 8以降が必要です) ：

java -version

agent の起動時のログメッセージを確認してください: アプリケーションが起動すると、次のようなメッセージが表示されるはずです:

[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started

HyperDX にメトリクスが表示されない

ClickStack が稼働中で、アクセス可能であることを確認します。

docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics

メトリクスエクスポーターが設定されていることを確認してください:

# 環境変数を使用している場合は、次のコマンドで確認してください:
echo $OTEL_METRICS_EXPORTER
# 期待される出力: otlp

アプリケーションログでOpenTelemetryのエラーを確認する: アプリケーションログを確認し、OpenTelemetry または OTLP のエクスポート失敗に関連するエラーメッセージがないか確認してください。

ネットワーク接続を確認する: ClickStack がリモートホスト上にある場合は、アプリケーションサーバーからポート 4318 にアクセスできることを確認してください。

agent のバージョンを確認する: 最新の安定版agentバージョン (現在は 2.22.0) を使用していることを確認してください。新しいバージョンにはパフォーマンス改善が含まれていることがよくあります。

次のステップ

本番環境への移行

このガイドでは、ローカルテスト向けに OpenTelemetry Java agent を設定する方法を説明します。本番環境にデプロイする場合は、管理しやすいように agent JAR をコンテナーイメージに含め、環境変数で設定してください。JVM インスタンスが多数ある大規模環境では、ClickStack に直接送信する代わりに、一元化された OpenTelemetry Collector をデプロイし、複数のアプリケーションからのメトリクスをバッチ処理して転送してください。

本番環境でのデプロイパターンと collector の設定例については、OpenTelemetry を使用した取り込みを参照してください。

Navigation