Future Tech Blog
フューチャー技術ブログ
Programmingカテゴリ

HyperDXを試す

CNCF連載 3日目はHyperDXを試してみたという記事です。とはいっても、HyperDX自体はCNCFに登録されたプロダクトでもなんでもないのですが(OpenTelemetry関連という接点はあり)、興味あったので試してみました。

HyperDXはいわゆるオブザーバービリティに属すプロダクトです。この領域のプロダクトはかなりのデータ量を扱う必要があったり、可用性のために、ストレージとビューアが分かれていたり、大量のツールと連携させる必要があったりします。

ELKスタックだと、ElasticsearchとLokiとKibana。GrafanaはLokiとPrometheusを連携させたり。OpenTelemetryのときによくデモされたJaegerはDBとビューを持ってトレースの機能を備えていてオールインワンです。

本番環境はSaaSにまるっと運用をお任せというのが良いとは思いますが、ローカルの作ったり壊したりする環境用良さそうなツールを探してみて見つけたのがHyperDXでした。

  • ログ、メトリックス、トレースに対応
  • ストレージもUIも持っている
  • OpenTelemetry対応

HyperDX自身はプロダクション環境でも使えるレベルのプロダクトのようです。管理画面のユーザー管理も厳しいパスワード条件の要求などもしてきます。今回はローカル開発で気軽に使いたい、という目的だったので、管理ユーザーもないローカル版を入れます。ユーザー管理付きのオールインワン版とか、クラウドのClickHouseストレージを使うバージョンとかもあります。

以下のDockerコマンドで起動します。

$ docker run -p 4318:4318 -p 4317:4317 -p 8080:8080
    -v ./mongodb:/data/db
    docker.hyperdx.io/hyperdx/hyperdx-local

(略)

Send OpenTelemetry data via:
  http/protobuf: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
  gRPC: OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Exporting data to ClickHouse:
  Endpoint: tcp://ch-server:9000?dial_timeout=10s
  Database: default

Waiting for ClickHouse to be ready...
ClickHouse is ready!

Visit the HyperDX UI at http://localhost:8080

ウェブのインタフェースが8080ポート、gRPCの情報受付が4317ポートです。

なお、このイメージは永続化可能なパスが3つあります。ローカルで気軽に使いたいという用途なのでログ自身は消えても良いので管理画面のデータだけ永続化するようにしています。

  • /data/db (HyperDXの管理画面で設定する情報を保持するMongoDBのデータ)
  • /var/lib/clickhouse (バックエンドのDBのClickHouseのデータ)
  • /var/log/clickhouse-server (バックエンドのDBのClickHouseのログ)

Pythonアプリケーションを作る

OpenTelemetryで情報を出力するPythonアプリケーションを作ります。FastAPIで作ります。

mkdir pysample
uv init
uv add fastapi --extra standard

OpenTelemetryのトレースのspanを追加するために、traceパッケージを利用します。いまどきのOpenTelemetryはゼロコードコンフィグということで、接続先の情報はプログラムに書いたりしないという方法が追加されたようです。言語によって手法は違うようですが、モンキーパッチやeBPFなんかを利用するようです。なので接続情報はこのコードにはありません。

uv add opentelemetry-api opentelemetry-sdk
import logging

from fastapi import FastAPI

from opentelemetry import trace

app = FastAPI()

from time import perf_counter, sleep

# ここがエンドポイント本体！
@app.get("/")
async def read_root():
    sleep(0.1)
    # トレースを手動で設定
    with trace.get_tracer_provider().get_tracer("sleep").start_as_current_span(__name__) as span:
        sleep(0.2)
        logging.info("read_root")
        logging.warning("I am hungry")
    sleep(0.1)
    return {"message": "Hello, world!"}

今回はuvを使っていますが、uvの場合はちょっと問題があって回避の手順が別のページにあります。その手順の通りに行います。uv pip installはuv addとは異なりpyproject.tomlにパッケージは追加しません。opentelemetry-bootstrapというコマンドが有名どころのPythonライブラリを検知して、それに対応した計装ライブラリをピックアップします。なかなか力技。

uv pip install opentelemetry-distro opentelemetry-exporter-otlp
uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -

これはuv pip installで入れているのでuv pip compile pyproject.tomlには出てきません。uv pip freeze > requirements.txtでrequirements.txtを作る必要があります。

以下のコマンドで起動して、 http://localhost:8000/ で起動してログを送ります。設定は環境変数とopentelemetry-instrumentコマンドラッパーの--service_nameといった引数で渡す方法が選べますが、真設定は環境変数にしといた方がDockerとかにするときに便利かと思って環境変数にしています。

デフォルトのOTLPのプロトコルはgrpcですが、この場合はhttpsになってしまい証明書エラーが出てしまいます。今回はローカルなので証明書はいらないhttp/protobufもしくはhttp/jsonにします。

export OTEL_SERVICE_NAME=hyperdx-demo
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # 省略可能
export OTEL_PYTHON_LOG_CORRELATION=true
export OTEL_PYTHON_LOG_LEVEL=info
export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

$ uv run opentelemetry-instrument fastapi run --port 8000

結構はまったのですが、fastapi devの開発モードだとログとかは出てこないですね。ちょっと不便。

UIの設定

ローカルモードだとユーザー設定などはありませんので、いきなりコネクション選択が表示されます。オールインワンのイメージだとパスワード設定などがあります。このコネクションは緑のCreateを押せばOKです。

スクリーンショット_2025-06-13_19.13.05.png

引き続きデータソース入力が表示されます。最初は二進も三進もわからなかったのですが、こちらの情報を見れば少しは歯が立ちます。

スクリーンショット_2025-06-13_19.16.16.png

以下の2つのソースを設定しました。名前、ソースタイプ、テーブル以外はデフォルトのままです。

  • Name: Logs
    • Data Source Type: Logs
    • Table: otel_logs
  • Name: Traces
    • Data Source Type: Trace
    • Table: otel_traces

ログを見てみる

左上のメニューでSearchを選び、データソースを選択すると出力したログ一覧が見れます。クリックすると時間や出力したサービスなど詳細な情報が見れます。いちいちデータソース選択とか面倒と思われるかもしれませんが、プロダクションで超大規模サービスを想定してでしょうね。同じ種類のデータでも日ごとにパーティションを切って別テーブルに、とかそういうのを想定しているのかと思います。

log.png

トレースは、それぞれのログをクリックしたあとに、トレースのタグを選択します。右側でトレースのデータソースを選択すると、いつものトレースが見られます。ログのデータソース設定のオプショナル中くれている設定に関連するトレースデータソースを設定できるので、そこを設定しておくとクリックは不要になります。動作は軽快です。

trace.png

まとめ

ローカルでログやトレースが見れるHyperDXを試してみました。メトリクスも本当は見られたりするのですがダッシュボード設定が難しくまた今度にしようかと。あと、ウェブの操作画面を記録するセッション機能とやらもあるのですが、機能とかが多くてちょっとこちらも時間を設けてゆっくり調べてみようと思います。

OpenTelemetryでデータ投入できるので、本番環境のクラウドサービスのログ基盤とかにもスムーズに遷移できる気がします。

設定がyamlかなにかで軽く共有できれば開発用Dockerとかで気軽に立ち上げてみんなで見るとかやりたいところですが、ちょっとそこはローカル専用にするにはちょっと不便。