未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
ClickStack と HyperDX
Loom は常に OpenTelemetry を出力します。HyperDX のソース、ダッシュボード、消去ステップについては設定が必要です。
Loom は操作ごとにスパンを出力し、ログとメトリクスも出力します。スパンには loom.operation、loom.org、loom.namespace、loom.agent、loom.request_id が含まれ、存在する場合は loom.user_id / enduser.id も含まれます。デフォルトでは、Loom はこれらを自身の ClickHouse サービス上の default.otel_* テーブルに、コレクターのスキーマで直接挿入するため、HyperDX は実行すべきコレクターなしでそれらを読み取れます。LOOM_CLICKSTACK_DATABASE を設定すると、ここおよび以下のすべてのクエリで、テーブルは default ではなくそのデータベースに置かれます。カラム構成は schemas/otel/clickstack_otel_tables.sql にあります。ClickStack がスキーマを変更した場合は、このファイルも合わせて更新する必要があります。
モデル呼び出しのスパンには、OpenTelemetry GenAI 属性(テレメトリ)が含まれます。これらは、HyperDX の LLM ビューがプロバイダー、操作、トークン使用量、プロンプトキャッシュの割合、コストを読み取る際に使うキーで出力されます。
エクスポート経路の選択
LOOM_OTEL_EXPORTER |
動作 |
|---|---|
ch |
同じサービス上の default.otel_traces、otel_logs、otel_metrics_sum、otel_metrics_histogram、otel_metrics_gauge に挿入します |
otlp |
LOOM_OTEL_EXPORTER_OTLP_ENDPOINT に送信します(ヘッダーは LOOM_OTEL_EXPORTER_OTLP_HEADERS)。コレクターや別のバックエンド向けです |
| 空(デフォルト) | エンドポイントが設定されている場合は otlp、それ以外は ch になります |
ch モードでは、Loom はまず default.otel_traces が存在することを確認します。存在しない場合、エクスポーターは1行のログを出力した後、自身を無効にします。テーブルを作成するには、次を実行します。
clickhouse-client --multiquery < schemas/otel/clickstack_otel_tables.sql
GET /v1/health?include=otel で、解決されたエクスポーターを確認できます。その他の OTel 設定(エクスポート間隔、テンポラリティ、ゲージのハートビート、サービス名)については、テレメトリを参照してください。
HyperDX をテーブルに向ける
行はすでにサービス内にあるため、コレクターと取り込みキーの手順は省略できます。HyperDX の 3 つのソースを作成します。otel_traces に対するトレース、otel_logs に対するログ、otel_metrics_* に対するメトリクスです。deploy/clickstack_sources.sh は、HyperDX API を通じてこれらを作成し、相関も設定します(ホスト型 ClickStack は、コンソールのセッション cookie である HDX_COOKIE で認証します)。各ソースのフィールドマッピングは、deploy/hyperdx_dashboards.md を参照してください。
ダッシュボードとアラート
deploy/hyperdx_dashboards.md がレシピ集です。
- Loom — Memory Health:検索品質の推移(
loom.search.top_similarity)、操作とトランスポートごとの呼び出し数とエラー数、システム状態、コストとトークン、検索プレーンごとのレイテンシ、書き込み結果、リクエストのパネル(レート、レイテンシ、エラー、最も遅いリクエスト、テナントごとのトラフィック、トレースのログ)。 - Loom — Code Plane:インデックスのラグ、ティアのラグ、その他の
loom.code.*ゲージ。JSON 定義はdeploy/dashboards/code_plane.jsonです。 - ブートストラップの順序と保存済み検索。
独自のタイルを作成するときの注意点が 2 つあります。
- カウンターは累積値です。
LOOM_OTEL_METRICS_DELTA_TEMPORALITY=trueを設定しない限り、カウンターの行はその時点までの累計です。レートを求めるには合計ではなく、連続するポイント間の差分が必要です。この設定とダッシュボードは一緒に切り替えてください。 - HyperDX では空の結果が 0 として扱われます。 アラートの最小サンプル数のガードは、行なしではなく正常範囲内の値を返す必要があります。そうしないと、データがないだけでアラートが発火します。
メトリクス名と推奨しきい値はメトリクスカタログにあります。
消去
LOOM_CLICKSTACK_DATABASE が必要です。ClickStack にはユーザーデータを削除するための管理 API がないため、バックエンド(server/erasure/app/backends.py の ClickStackBackend)は、そのデータベース内の OTel テーブルに対して軽量な DELETE FROM 文を実行します。
| テーブル | 検索する属性カラム |
|---|---|
otel_logs |
LogAttributes |
otel_traces |
SpanAttributes |
otel_metrics_gauge, _sum, _histogram, _exponential_histogram, _summary |
Attributes |
hyperdx_sessions |
ResourceAttributes |
- ユーザースコープ は、
LOOM_CLICKSTACK_USER_ID_KEYSのいずれかのキー(デフォルトはuser_id,user.id,enduser.id,loom.user_id,langfuse.user.id)に OR で一致します。SDK ごとにキー名が異なるためです。Loom のリクエストスパンはenduser.idを持ち、モデル呼び出しスパンはloom.user_idとlangfuse.user.idを持ちます。Langfuse が設定されている場合は、呼び出し元が解決された後にそのリクエストが開く他のすべてのスパンも同様です。これらはいずれもloom.orgを持つため、下記の org ガードが適用されます。 - 名前空間スコープ は
loom.namespaceまたはservice.namespaceに一致します。Loom のエクスポーターはservice.namespaceを定数loomに設定し、テナントはloom.namespaceに格納します。service.namespaceは同じ ClickStack に書き込む他のエミッターをカバーするためのもので、その値loomに一致することはありません。 - org ガード。 別の org の
loom.orgが付いた行は消去されません。loom.namespaceに一致した行は、消去を実行する org のloom.orgを持っている必要があります。Loom の op メトリクスとドメインメトリクス(カウンターとヒストグラム)はloom.namespaceを持ちますが org を持たないため、名前空間の消去では対象になりません。これらにメモリの内容は含まれませんが、loom.namespaceラベルは名前空間名であり、個人用名前空間の場合はユーザーのメールアドレスに由来します。コレクターテーブル自体に TTL がある場合は、その TTL で削除されるまで残ります。loom.orgタグがなく、ユーザーキーまたはservice.namespace(他のエミッター)に一致した行は、対象のユーザーのデータを含む可能性があるため消去されます。
軽量削除が書き込むのは行の存在マスクだけなので、行はすべての読み取りから直ちに見えなくなり、バイトは次回のマージで削除されます。ALTER TABLE … DELETE は、影響を受けるすべてのパートを書き直します。述語は、属性マップの値に bloom filter がないテーブル(メトリクスのテーブルにはありません)をすべてスキャンします。loom doctor がそれらのテーブルを示します。
このステップは、削除の前に行数を数え、その件数を報告します。テーブルまたはデータベースが存在しない場合は、消去対象なしとして扱います。それ以外の失敗ではステップは fail closed となり、erasure_recovery ワーカーが再試行します。
デフォルトに頼る前に、実際のデータがどのユーザー ID キーを持っているかを確認してください。
SELECT DISTINCT arrayJoin(mapKeys(LogAttributes))
FROM default.otel_logs WHERE TimestampTime > now() - INTERVAL 1 DAY
このステップが属するサガについては、保持と消去を参照してください。
設定
| 設定 | デフォルト | 効果 |
|---|---|---|
LOOM_OTEL_EXPORTER |
"" |
ch、otlp、または自動 |
LOOM_OTEL_EXPORTER_OTLP_ENDPOINT |
"" |
コレクターのベース URL |
LOOM_OTEL_EXPORTER_OTLP_HEADERS |
"" |
カンマ区切りの K=V ヘッダー |
LOOM_OTEL_ENABLED |
true |
マスタースイッチ |
LOOM_CLICKSTACK_DATABASE |
"" |
OTel テーブルのデータベース。消去を有効にする |
LOOM_CLICKSTACK_USER_ID_KEYS |
user_id,user.id,enduser.id,loom.user_id,langfuse.user.id |
ユーザー単位の消去が照合する属性キー |