メインコンテンツへスキップ
要点OpenTelemetry Java agentを使用して、ClickStackでJVMアプリケーションを監視します。デモデータセットとあらかじめ用意されたダッシュボードが含まれています。

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

このセクションでは、OpenTelemetry Java agent を使用して既存のJVMアプリケーションから ClickStack にメトリクスを送信するための設定方法を説明します。 本番環境のセットアップを行う前にインテグレーションを試したい場合は、デモデータセットのセクションにあるデモデータセットを使用してテストできます。
前提条件
  • 稼働中の ClickStack インスタンス
  • 既存の Java アプリケーション (Java 8 以降)
  • JVM の起動引数を変更できること
1

​
ClickStack の API key を取得する

OpenTelemetry Java agent はデータを ClickStack の OTLP エンドポイントに送信しますが、その際に認証が必要です。
  1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
  2. 必要に応じてアカウントを作成するか、ログインします
  3. Team Settings → API Keys に移動します
  4. インジェスト API key をコピーします
2

​
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 と同じ場所) に配置できます。
3

​
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 ファイル名
OpenTelemetry Java agent は、次の JVM メトリクスを自動的に収集します。
  • メモリ: jvm.memory.used, jvm.memory.limit, jvm.memory.committed, jvm.memory.used_after_last_gc
  • ガベージコレクション: jvm.gc.duration
  • スレッド: jvm.thread.count
  • クラス: jvm.class.count, jvm.class.loaded, jvm.class.unloaded
  • CPU: jvm.cpu.time, jvm.cpu.count
4

​
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 の挙動を示す事前生成済みメトリクスを含むサンプルデータセットを提供しています。
1

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

# 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 使用率のパターン
2

​
ClickStack を起動する

まだ ClickStack を起動していない場合は、次を実行します。
docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest
ClickStack が完全に起動するまで少し待ってください。
3

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

# 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 テーブルに直接インポートされます。
4

​
デモデータを確認する

インポート後は、次の手順で確認します。
  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 を検索します
デモサービスのメトリクスが表示されるはずです。
タイムゾーン表示HyperDX はタイムスタンプをブラウザーのローカルタイムゾーンで表示します。デモデータの対象期間は 2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC) です。場所に関係なくデモメトリクスを確実に表示するには、時間範囲を 2025-12-06 14:00:00 - 2025-12-09 14:00:00 に設定してください。メトリクスが表示されたら、より見やすく可視化するために範囲を 24 時間に絞れます。

​
ダッシュボードと可視化

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

​
ダッシュボード設定

2

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

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

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

ダッシュボードは、すべての可視化が事前に設定された状態で作成されます。
デモデータセットでは、時間範囲を 2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC) に設定してください。ローカルのタイムゾーンに応じて調整してください。

​
トラブルシューティング

​
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 での取り込み を参照してください。
最終更新日 2026年6月10日