Text-to-Chart | ClickHouse Docs

ClickStack の Text-to-Chart 機能では、表示したい内容をプレーンテキストで説明するだけで可視化を作成できます。メトリクス、フィルタ、グループ化フィールドを手動で選択する代わりに、"過去 24 時間のサービス別エラー率" のようなプロンプトを入力すると、ClickStack が対応するチャートを自動的に生成します。

この機能は、大規模言語モデル (LLM) を使用してテキストプロンプトをクエリに変換し、その後 Chart Explorer で可視化を作成します。設定済みのデータソースであれば、どのデータソースでも利用できます。

前提条件

Text-to-Chart を使用するには、Anthropic APIキーが必要です。ClickStack の起動時に ANTHROPIC_API_KEY 環境変数を設定してください。

オープンソース環境でデプロイする場合は、キーを環境変数として渡します。設定方法はデプロイタイプによって異なります。

docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local

変数を .env ファイルに追加するか、docker-compose.yaml に直接設定してください。

services:
  app:
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

--set を使用してキーを渡します。

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set env[0].name=ANTHROPIC_API_KEY \
  --set env[0].value=<YOUR_KEY>

Text-to-Chart を使う

Chart Explorer に移動する

HyperDX の左側のメニューから Chart Explorer を選択します。

データソースを選択する

可視化したいデータソースを選択します。たとえばログ、トレース、メトリクス などです。

テキストプロンプトを入力する

Chart Explorer の上部にある AI Assistant の入力欄に、作成したいチャートの内容を自然言語で入力します。たとえば次のように入力します。

Show error rates by service over the last 24 hours
Latency breakdown by endpoint
Count of events over time grouped by severity

ClickStack はプロンプトをクエリに変換し、自動的に可視化を表示します。

デモデータで試す

Text-to-Chart を手早く試すには、ローカルモードの Dockerイメージと、リモートのデモデータセットを使うのが最も簡単です。

docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 clickhouse/clickstack-local:latest

localhost:8080 にアクセスします。デモデータに接続するには、Team Settings に移動し、次の内容で新しい接続を作成します。

Connection Name: Demo
Host: https://sql-clickhouse.clickhouse.com
Username: otel_demo
Password: 空のままにします

続いて、各ログソース — ログ、トレース、メトリクス、Sessions — が otel_v2 データベースを使用するように変更します。ログソースの設定方法の詳細については、リモートのデモデータセットガイドを参照してください。

接続したら、Chart Explorer を開き、利用可能なログ、トレース、メトリクスに対してプロンプトを試してみてください。

プロンプトの例

以下のプロンプトは、オブザーバビリティデータを扱う際の一般的なユースケースを示しています。

プロンプト	データソース	説明
`Error count by service over time`	ログ	サービスごとのエラー発生頻度の推移をチャート化します
`Average request duration grouped by endpoint`	トレース	エンドポイントごとのレイテンシの傾向を表示します
`P99 latency by service`	トレース	サービスごとのテールレイテンシを特定します
`Count of 5xx status codes over the last 6 hours`	ログ	過去 6 時間のサーバーエラーの傾向を追跡します

プロンプトでは、設定済みのデータソースで利用可能な任意のカラムや属性を参照できます。プロンプトが具体的であるほど、生成されるチャートの精度は高くなります。

制限事項

Text-to-Chart は現在、LLMプロバイダーとして Anthropic のみをサポートしています。OpenAI を含む追加のプロバイダーへの対応は、今後のリリースで予定されています。
データソースとしてサポートされているのは、ログとトレースのみです。Prometheus メトリクスにはまだ対応していません。
チャートの精度は、プロンプトの明確さと基盤となるデータの構造に依存します。生成されたチャートが期待どおりでない場合は、プロンプトを言い換えるか、カラム名を明示的に指定してみてください。

参考資料

テキストからチャートへ: ClickStack でよりすばやく可視化する方法 — この機能を紹介するブログ記事
ダッシュボードと可視化 — Chart Explorer を使った手動でのチャート作成
Search — 全文検索とプロパティ検索の構文
Configuration — ClickStack のすべての環境変数