メインコンテンツまでスキップ
メインコンテンツまでスキップ

設定オプション

以下の設定オプションは、ClickStackの各コンポーネントに利用できます。

設定の変更​

Docker​

All in One、HyperDX Only、またはLocal Modeを使用している場合、希望の設定を環境変数を介して指定します。たとえば：

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

Docker Compose​

Docker Compose 配置ガイドを使用している場合、.env ファイルを使用して設定を変更できます。

または、docker-compose.yaml ファイル内で明示的に設定を上書きすることもできます。たとえば：

例:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... other settings

Helm​

値のカスタマイズ (オプション)​

--set フラグを使用して設定をカスタマイズできます。たとえば：

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

または values.yaml を編集します。デフォルトの値を取得するには：

helm show values hyperdx/hdx-oss-v2 > values.yaml

設定の例：

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

HyperDX​

データソース設定​

HyperDX は、各可観測性データタイプ/ピラーのソースをユーザーが定義することに依存しています：

  • Logs
  • Traces
  • Metrics
  • Sessions

この設定は、Team Settings -> Sources 内のアプリケーションから行うことができます。以下にログの例を示します：

HyperDX Source configuration

これらの各ソースは、作成時に指定されたテーブルと、HyperDXがデータをクエリできるカラムのセットを少なくとも1つ必要とします。

デフォルトのOpenTelemetry (OTel) スキーマを使用してClickStackに付属している場合、これらのカラムは各ソースに対して自動的に推測できます。もしスキーマを変更するか、カスタムスキーマを使用している場合は、ユーザーがこれらのマッピングを指定し、更新する必要があります。

注記

ClickStackに付属しているClickHouseのデフォルトスキーマは、OTel コレクター用のClickHouseエクスポーターによって作成されたスキーマです。これらのカラム名は、公式のOTel仕様に記載されているものと相関します。詳細はこちらを参照してください。

各ソースに利用可能な設定は以下の通りです：

Logs​

設定説明必要デフォルトスキーマでの推測推測される値
Nameソース名。はいいいえ–
Server Connectionサーバ接続名。はいいいえDefault
DatabaseClickHouseデータベース名。はいはいdefault
Table対象のテーブル名。デフォルトスキーマを使用する場合は otel_logs に設定します。はいいいえ
Timestamp Column主キーの一部となる日時カラムまたは式。はいはいTimestampTime
Default Selectデフォルトの検索結果に表示されるカラム。はいはいTimestamp, ServiceName, SeverityText, Body
Service Name Expressionサービス名のための式またはカラム。はいはいServiceName
Log Level Expressionログレベルのための式またはカラム。はいはいSeverityText
Body Expressionログメッセージのための式またはカラム。はいはいBody
Log Attributes Expressionカスタムログ属性のための式またはカラム。はいはいLogAttributes
Resource Attributes Expressionリソースレベルの属性のための式またはカラム。はいはいResourceAttributes
Displayed Timestamp ColumnUI表示に使用されるタイムスタンプカラム。はいはいResourceAttributes
Correlated Metric Source関連付けられたメトリクソース (例: HyperDX メトリクス)。いいえいいえ–
Correlated Trace Source関連付けられたトレースソース (例: HyperDX トレース)。いいえいいえ–
Trace Id ExpressionトレースIDを抽出するための式またはカラム。はいはいTraceId
Span Id ExpressionスパンIDを抽出するための式またはカラム。はいはいSpanId
Implicit Column Expressionフルテキスト検索に使用されるカラム (フィールドが指定されていない場合)。通常はログ本文。はいはいBody

Traces​

設定説明必要デフォルトスキーマでの推測推測される値
Nameソース名。はいいいえ–
Server Connectionサーバ接続名。はいいいえDefault
DatabaseClickHouseデータベース名。はいはいdefault
Table対象のテーブル名。デフォルトスキーマを使用する場合は otel_traces に設定します。はいはい-
Timestamp Column主キーの一部となる日時カラムまたは式。はいはいTimestamp
TimestampTimestamp Column のエイリアス。はいはいTimestamp
Default Selectデフォルトの検索結果に表示されるカラム。はいはいTimestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName
Duration Expressionスパンの持続時間を計算するための式。はいはいDuration
Duration Precision持続時間式の精度 (例: ナノ秒、マイクロ秒)。はいはいns
Trace Id ExpressionトレースIDのための式またはカラム。はいはいTraceId
Span Id ExpressionスパンIDのための式またはカラム。はいはいSpanId
Parent Span Id Expression親スパンIDのための式またはカラム。はいはいParentSpanId
Span Name Expressionスパン名のための式またはカラム。はいはいSpanName
Span Kind Expressionスパンの種類のための式またはカラム (例: クライアント、サーバー)。はいはいSpanKind
Correlated Log Sourceオプション。関連付けられたログソース (例: HyperDX ログ)。いいえいいえ–
Correlated Session Sourceオプション。関連付けられたセッションソース。いいえいいえ–
Correlated Metric Sourceオプション。関連付けられたメトリクソース (例: HyperDX メトリクス)。いいえいいえ–
Status Code Expressionスパンのステータスコードのための式。はいはいStatusCode
Status Message Expressionスパンのステータスメッセージのための式。はいはいStatusMessage
Service Name Expressionサービス名のための式またはカラム。はいはいServiceName
Resource Attributes Expressionリソースレベル属性のための式またはカラム。はいはいResourceAttributes
Event Attributes Expressionイベント属性のための式またはカラム。はいはいSpanAttributes
Span Events Expressionスパンイベントを抽出するための式。通常は Nested タイプのカラムです。対応する言語SDKで例外スタックトレースをレンダリングできます。はいはいEvents
Implicit Column Expressionフルテキスト検索に使用されるカラム (フィールドが指定されていない場合)。通常はログの本文です。はいはいSpanName

Metrics​

設定説明必要デフォルトスキーマでの推測推測される値
Nameソース名。はいいいえ–
Server Connectionサーバ接続名。はいいいえDefault
DatabaseClickHouseデータベース名。はいはいdefault
Gauge Tableガウジ型メトリクスを格納するテーブル。はいいいえotel_metrics_gauge
Histogram Tableヒストグラム型メトリクスを格納するテーブル。はいいいえotel_metrics_histogram
Sum Table合計型 (カウンター) メトリクスを格納するテーブル。はいいいえotel_metrics_sum
Correlated Log Sourceオプション。関連付けられたログソース (例: HyperDX ログ)。いいえいいえ–

Sessions​

設定説明必要デフォルトスキーマでの推測推測される値
Nameソース名。はいいいえ–
Server Connectionサーバ接続名。はいいいえDefault
DatabaseClickHouseデータベース名。はいはいdefault
Tableセッションデータの対象テーブル。デフォルトスキーマを使用する場合は hyperdx_sessions に設定します。はいはい-
Timestamp Column主キーの一部となる日時カラムまたは式。はいはいTimestampTime
Log Attributes Expressionセッションデータからログレベル属性を抽出するための式。はいはいLogAttributes
LogAttributesログ属性を格納するために使用されるエイリアスまたはフィールド参照。はいはいLogAttributes
Resource Attributes Expressionリソースレベルメタデータを抽出するための式。はいはいResourceAttributes
Correlated Trace Sourceオプション。セッション相関のための関連付けられたトレースソース。いいえいいえ–
Implicit Column Expressionフルテキスト検索に使用されるカラム (フィールドが指定されていない場合)。はいはいBody

相関ソース​

ClickStackでフルクロスソース相関を可能にするためには、ユーザーはログ、トレース、メトリクス、およびセッションのための相関ソースを設定する必要があります。これにより、HyperDXは関連データを関連付け、イベントをレンダリングする際に豊かなコンテキストを提供します。

  • Logs: トレースやメトリクスと相関できます。
  • Traces: ログ、セッション、メトリクスと相関できます。
  • Metrics: ログと相関できます。
  • Sessions: トレースと相関できます。

これらの相関を設定することにより、HyperDXは例えば、トレースに関連するログを一緒にレンダリングしたり、セッションに関連するメトリクスの異常をサーフェスしたりすることができます。適切な設定により、統一感のある文脈的な可観測性体験が保証されます。

以下に、相関ソースで構成されたLogsソースの例を示します：

HyperDX Source correlated

アプリケーション設定​

HyperDX in ClickHouse Cloud

これらの設定は、ClickHouse CloudでHyperDXが管理されている場合には変更できません。

  • HYPERDX_API_KEY

    • デフォルト: なし (必須)
    • 説明: HyperDX APIの認証キー。
    • ガイダンス:
    • テレメトリーとロギングのために必要
    • ローカル開発時には空でない値を使用できます
    • 本番環境では安全でユニークなキーを使用してください
    • アカウント作成後、チーム設定ページから入手できます

  • HYPERDX_LOG_LEVEL

    • デフォルト: info
    • 説明: ロギングの詳細レベルを設定します。
    • オプション: debug, info, warn, error
    • ガイダンス:
    • 詳細なトラブルシューティングには debug を使用します
    • 通常の操作には info を使用します
    • 本番環境では、ログ量を減らすために warn または error を使用します

  • HYPERDX_API_PORT

    • デフォルト: 8000
    • 説明: HyperDX APIサーバのポート。
    • ガイダンス:
    • このポートがホストで使用可能であることを確認してください
    • ポートの競合がある場合には変更してください
    • APIクライアント設定のポートと一致させる必要があります

  • HYPERDX_APP_PORT

    • デフォルト: 8000
    • 説明: HyperDXフロントエンドアプリのポート。
    • ガイダンス:
    • このポートがホストで使用可能であることを確認してください
    • ポートの競合がある場合には変更してください
    • ブラウザからアクセスできる必要があります

  • HYPERDX_APP_URL

    • デフォルト: http://localhost
    • 説明: フロントエンドアプリのベースURL。
    • ガイダンス:
    • 本番環境ではあなたのドメインに設定してください
    • プロトコルを含めてください (http/https)
    • スラッシュを後ろに付けないでください

  • MONGO_URI

    • デフォルト: mongodb://db:27017/hyperdx
    • 説明: MongoDB接続文字列。
    • ガイダンス:
    • Dockerでのローカル開発にはデフォルトを使用してください
    • 本番環境では安全な接続文字列を使用してください
    • 必要に応じて認証を含めてください
    • 例: mongodb://user:pass@host:port/db

  • MINER_API_URL

    • デフォルト: http://miner:5123
    • 説明: ログパターンマイニングサービスのURL。
    • ガイダンス:
    • Dockerでのローカル開発にはデフォルトを使用してください
    • 本番環境ではマイナーサービスのURLに設定してください
    • APIサービスからアクセスできる必要があります

  • FRONTEND_URL

    • デフォルト: http://localhost:3000
    • 説明: フロントエンドアプリのURL。
    • ガイダンス:
    • ローカル開発ではデフォルトを使用してください
    • 本番環境ではあなたのドメインに設定してください
    • APIサービスからアクセスできる必要があります

  • OTEL_SERVICE_NAME

    • デフォルト: hdx-oss-api
    • 説明: OpenTelemetryインストゥルメンテーションのサービス名。
    • ガイダンス:
    • HyperDXサービスのために説明的な名前を使用してください。HyperDXが自動計測を行う場合に適用されます。
    • テレメトリデータにおいてHyperDXサービスを特定するのに役立ちます

  • NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

    • デフォルト: http://localhost:4318
    • 説明: OpenTelemetryコレクターのエンドポイント。
    • ガイダンス:
    • 自動計測を行うHyperDXに該当します。
    • ローカル開発ではデフォルトを使用してください
    • 本番環境ではコレクターのURLに設定してください
    • HyperDXサービスからアクセスできる必要があります

  • USAGE_STATS_ENABLED

    • デフォルト: true
    • 説明: 使用統計の収集を切り替えます。
    • ガイダンス:
    • 使用追跡を無効にするには false に設定します
    • プライバシーに敏感なデプロイメントに役立ちます
    • 製品改善のためにデフォルトは true です

  • IS_OSS

    • デフォルト: true
    • 説明: OSSモードで実行されているかどうかを示します。
    • ガイダンス:
    • オープンソースデプロイメントでは true のままにします
    • エンタープライズデプロイメントでは false に設定します
    • 機能の可用性に影響します

  • IS_LOCAL_MODE

    • デフォルト: false
    • 説明: ローカルモードで実行されているかどうかを示します。
    • ガイダンス:
    • ローカル開発には true に設定します
    • 特定の本番機能が無効になります
    • テストと開発に役立ちます

  • EXPRESS_SESSION_SECRET

    • デフォルト: hyperdx is cool 👋
    • 説明: Expressセッション管理のためのシークレット。
    • ガイダンス:
    • 本番環境では変更してください
    • 強力でランダムな文字列を使用してください
    • 秘密にして安全に保ってください

  • ENABLE_SWAGGER

    • デフォルト: false
    • 説明: Swagger APIドキュメントを切り替えます。
    • ガイダンス:
    • APIドキュメントを有効にするには true に設定します
    • 開発およびテストに役立ちます
    • 本番環境では無効にしてください

  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED

    • デフォルト: false
    • 説明: HyperDXにおけるJSON型のBetaサポートを有効にします。OTel コレクターでJSONサポートを有効にするにはOTEL_AGENT_FEATURE_GATE_ARGも参照してください。
    • ガイダンス:
    • ClickStackにおけるJSONサポートを有効にするには true に設定します。

OpenTelemetryコレクター​

詳細については"ClickStack OpenTelemetry Collector"を参照してください。

  • CLICKHOUSE_ENDPOINT

    • デフォルト: スタンドアロンイメージの場合はなし (必須)。All-in-oneまたはDocker Compose配布の場合は統合されたClickHouseインスタンスに設定されています。
    • 説明: テレメトリーデータをエクスポートするためのClickHouseインスタンスのHTTPS URL。
    • ガイダンス:
      • ポートを含む完全なHTTPSエンドポイントである必要があります (例: https://clickhouse.example.com:8443)
      • コレクターがデータをClickHouseに送信するために必須です

  • CLICKHOUSE_USER

    • デフォルト: default
    • 説明: ClickHouseインスタンスに対する認証に使用されるユーザー名。
    • ガイダンス:
      • ユーザーが INSERT および CREATE TABLE 権限を持っていることを確認してください
      • 取り込み用に専用のユーザーを作成することを推奨します

  • CLICKHOUSE_PASSWORD

    • デフォルト: なし (認証が有効な場合は必須)
    • 説明: 指定されたClickHouseユーザーのパスワード。
    • ガイダンス:
      • ユーザーアカウントにパスワードが設定されている場合は必須です
      • 本番環境で安全に保管してください

  • HYPERDX_LOG_LEVEL

    • デフォルト: info
    • 説明: コレクターのログ詳細レベル。
    • ガイダンス:
      • debug, info, warn, error などの値を受け入れます
      • トラブルシューティングの際は debug を使用します

  • OPAMP_SERVER_URL

    • デフォルト: なし (必須) スタンドアロンイメージの場合。All-in-oneまたはDocker Compose配布の場合、デプロイされたHyperDXインスタンスを指します。
    • 説明: コレクターを管理するために使用されるOpAMPサーバのURL (例: HyperDXインスタンス)。デフォルトではポート 4320 です。
    • ガイダンス:
      • あなたのHyperDXインスタンスを指す必要があります
      • 動的な設定と安全な取り込みを有効にします

  • HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

    • デフォルト: default
    • 説明: コレクターがテレメトリーデータを書き込むClickHouseのデータベース。
    • ガイダンス:
      • カスタムデータベース名を使用する場合は設定してください
      • 指定されたユーザーがこのデータベースにアクセスできることを確認してください

  • OTEL_AGENT_FEATURE_GATE_ARG

    • デフォルト: <空文字列>
    • 説明: コレクターで有効にする機能フラグを有効にします。--feature-gates=clickhouse.jsonに設定すると、コレクター内でのJSON型のBetaサポートが有効になり、スキーマがその型で作成されます。HyperDXでのJSONサポートを有効にするにはBETA_CH_OTEL_JSON_SCHEMA_ENABLEDも参照してください。
    • ガイダンス:
    • ClickStackにおけるJSONサポートを有効にするには true に設定します。

ClickHouse​

ClickStackはマルチテラバイトスケールに最適化されたデフォルトのClickHouse構成を提供しますが、ユーザーは仕事の負荷に合わせて変更および最適化することができます。

ClickHouseを効果的に調整するためには、ユーザーはparts、partitions、shards and replicasなどの主要なストレージの概念、およびmergesが挿入時にどのように発生するかを理解しておく必要があります。 primary indices、sparse secondary indices、およびデータスキッピングインデックスの基本を確認し、TTLライフサイクルなどのデータライフサイクル管理の技術を利用することをお勧めします。

ClickStackはスキーマカスタマイズをサポートしており、ユーザーはカラムの型を変更したり、新しいフィールド (例えばログから) を抽出したり、コーデックや辞書を適用したり、プロジェクションを使用してクエリを加速したりすることができます。

さらに、マテリアライズドビューを使用して、データがビューのソーステーブルに書き込まれ、アプリケーションがターゲットテーブルから読み取る限り、取り込み時にデータを変換またはフィルタリングすることができます。

詳細については、スキーマ設計、インデックス戦略、およびデータ管理のベストプラクティスに関するClickHouseのドキュメントを参照してください。これらの多くはClickStackのデプロイメントに直接適用されます。