Merge pull request #1532 from future-architect/feature

HyperDXを試す

Author: ma91n

source/_posts/20250616a_CNCF連載2025.md

@@ -87,7 +87,7 @@ Graduatedが31、Incubatingが36、Sandboxが143という内訳のようです
 |-----------|------------|-----------------|
 | 6/17 (火) | 真野隼記   | [Notary v2（Notation）によるコンテナイメージ署名](/articles/20250616b/)          |
 | 6/18 (水) | 伊藤太斉   | [KubeCon参加レポート](/articles/20250617a/) |
-| 6/19 (木) | 澁川喜規   | HyperDXについて         |
+| 6/19 (木) | 澁川喜規   | [HyperDXについて](/articles/20250618a/)         |
 | 🐋       |           |                 |
 | 6/23 (月) | 村田靖拓   | 未定            |
 | 6/24 (火) | 大前七奈   | 未定            |

source/_posts/20250618a_HyperDXを試す.md

@@ -0,0 +1,162 @@
+---
+title: "HyperDXを試す"
+date: 2025/06/18 00:00:00
+postid: a
+tag:
+  - HyperDX
+  - CNCF
+  - オブサーバビリティ
+  - OpenTelemetry
+category:
+  - Programming
+thumbnail: /images/20250618a/thumbnail.png
+author: 澁川喜規
+lede: "HyperDXはいわゆるオブザーバービリティに属すプロダクトです。この領域のプロダクトはかなりのデータ量を扱う必要があったり、可用性のために、ストレージとビューアが分かれていたり、大量のツールと連携させる必要があったりします。"
+---
+[CNCF連載](/articles/20250616a/) 3日目はHyperDXを試してみたという記事です。とはいっても、HyperDX自体はCNCFに登録されたプロダクトでもなんでもないのですが(OpenTelemetry関連という接点はあり)、興味あったので試してみました。
+
+HyperDXはいわゆるオブザーバービリティに属すプロダクトです。この領域のプロダクトはかなりのデータ量を扱う必要があったり、可用性のために、ストレージとビューアが分かれていたり、大量のツールと連携させる必要があったりします。
+
+ELKスタックだと、ElasticsearchとLokiとKibana。GrafanaはLokiとPrometheusを連携させたり。OpenTelemetryのときによくデモされたJaegerはDBとビューを持ってトレースの機能を備えていてオールインワンです。
+
+本番環境はSaaSにまるっと運用をお任せというのが良いとは思いますが、ローカルの作ったり壊したりする環境用良さそうなツールを探してみて見つけたのがHyperDXでした。
+
+* ログ、メトリックス、トレースに対応
+* ストレージもUIも持っている
+* OpenTelemetry対応
+
+HyperDX自身はプロダクション環境でも使えるレベルのプロダクトのようです。管理画面のユーザー管理も厳しいパスワード条件の要求などもしてきます。今回はローカル開発で気軽に使いたい、という目的だったので、管理ユーザーもないローカル版を入れます。ユーザー管理付きのオールインワン版とか、クラウドのClickHouseストレージを使うバージョンとかもあります。
+
+以下のDockerコマンドで起動します。
+
+```sh
+$ 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で作ります。
+
+```shell
+mkdir pysample
+uv init
+uv add fastapi --extra standard
+```
+
+OpenTelemetryのトレースのspanを追加するために、traceパッケージを利用します。いまどきのOpenTelemetryは[ゼロコードコンフィグ](https://opentelemetry.io/docs/zero-code/python/)ということで、接続先の情報はプログラムに書いたりしないという方法が追加されたようです。言語によって手法は違うようですが、モンキーパッチやeBPFなんかを利用するようです。なので接続情報はこのコードにはありません。
+
+```shell
+uv add opentelemetry-api opentelemetry-sdk
+```
+
+```py
+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の場合はちょっと問題があって[回避の手順が別のページ](https://opentelemetry.io/docs/zero-code/python/troubleshooting/#bootstrap-using-uv)にあります。その手順の通りに行います。`uv pip install`は`uv add`とは異なり`pyproject.toml`にパッケージは追加しません。opentelemetry-bootstrapというコマンドが[有名どころのPythonライブラリを検知して、それに対応した計装ライブラリをピックアップ](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/opentelemetry-instrumentation/src/opentelemetry/instrumentation/bootstrap_gen.py)します。なかなか力技。
+
+```sh
+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/ で起動してログを送ります。[設定](https://opentelemetry.io/docs/zero-code/python/configuration/)は環境変数と`opentelemetry-instrument`コマンドラッパーの`--service_name`といった引数で渡す方法が選べますが、真設定は環境変数にしといた方がDockerとかにするときに便利かと思って環境変数にしています。
+
+デフォルトのOTLPのプロトコルはgrpcですが、この場合はhttpsになってしまい証明書エラーが出てしまいます。今回はローカルなので証明書はいらないhttp/protobufもしくはhttp/jsonにします。
+
+```sh
+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です。
+
+<img src="/images/20250618a/スクリーンショット_2025-06-13_19.13.05.png" alt="スクリーンショット_2025-06-13_19.13.05.png" width="1200" height="685" loading="lazy">
+
+引き続きデータソース入力が表示されます。最初は二進も三進もわからなかったのですが、[こちら](https://clickhouse.com/docs/use-cases/observability/clickstack/config#datasource-settings)の情報を見れば少しは歯が立ちます。
+
+<img src="/images/20250618a/スクリーンショット_2025-06-13_19.16.16.png" alt="スクリーンショット_2025-06-13_19.16.16.png" width="1200" height="685" loading="lazy">
+
+以下の2つのソースを設定しました。名前、ソースタイプ、テーブル以外はデフォルトのままです。
+
+* Name: Logs
+  * Data Source Type: Logs
+  * Table: ``otel_logs``
+* Name: Traces
+  * Data Source Type: Trace
+  * Table: ``otel_traces``
+
+# ログを見てみる
+
+左上のメニューでSearchを選び、データソースを選択すると出力したログ一覧が見れます。クリックすると時間や出力したサービスなど詳細な情報が見れます。いちいちデータソース選択とか面倒と思われるかもしれませんが、プロダクションで超大規模サービスを想定してでしょうね。同じ種類のデータでも日ごとにパーティションを切って別テーブルに、とかそういうのを想定しているのかと思います。
+
+<img src="/images/20250618a/log.png" alt="log.png" width="1200" height="522" loading="lazy">
+
+トレースは、それぞれのログをクリックしたあとに、トレースのタグを選択します。右側でトレースのデータソースを選択すると、いつものトレースが見られます。ログのデータソース設定のオプショナル中くれている設定に関連するトレースデータソースを設定できるので、そこを設定しておくとクリックは不要になります。動作は軽快です。
+
+<img src="/images/20250618a/trace.png" alt="trace.png" width="1200" height="629" loading="lazy">
+
+# まとめ
+
+ローカルでログやトレースが見れるHyperDXを試してみました。メトリクスも本当は見られたりするのですがダッシュボード設定が難しくまた今度にしようかと。あと、ウェブの操作画面を記録するセッション機能とやらもあるのですが、機能とかが多くてちょっとこちらも時間を設けてゆっくり調べてみようと思います。
+
+OpenTelemetryでデータ投入できるので、本番環境のクラウドサービスのログ基盤とかにもスムーズに遷移できる気がします。
+
+設定がyamlかなにかで軽く共有できれば開発用Dockerとかで気軽に立ち上げてみんなで見るとかやりたいところですが、ちょっとそこはローカル専用にするにはちょっと不便。