メインコンテンツへスキップ
メインコンテンツへスキップ

Vector を使用したインジェスト

Vector は、高性能でベンダーニュートラルなオブザーバビリティ向けデータパイプラインです。幅広いソースからログやメトリクスを収集・変換・ルーティングするためによく使われており、とくに柔軟性と低いリソースフットプリントから、ログのインジェスト用途で人気があります。

ClickStack と組み合わせて Vector を使用する場合、スキーマ定義の責任はユーザー側にあります。これらのスキーマは OpenTelemetry のコンベンションに従うこともできますが、ユーザー定義のイベント構造を表す、完全に独自のものにすることも可能です。実際には、Vector によるインジェストは、ログ に対して最も一般的に利用されており、データが ClickHouse に書き込まれる前に、ユーザーがパースやエンリッチメントを完全に制御したいケースで使われます。

このガイドは、ClickStack オープンソース版およびマネージド版 ClickStack の両方に対して、Vector を用いてデータを ClickStack に取り込む方法に焦点を当てています。説明を簡潔にするため、Vector のソースやパイプライン設定の詳細は扱いません。その代わり、データを ClickHouse に書き込む sink の設定と、その結果として得られるスキーマが ClickStack と互換性を持つようにする点に重点を置きます。

ClickStack における唯一の厳格な要件は、オープンソース版かマネージドデプロイメントかに関わらず、データに タイムスタンプカラム（または同等の時間フィールド）が含まれていることです。これは ClickStack の UI でデータソースを設定する際に宣言できます。

Vector を使ったデータ送信​


以下のガイドは、Managed ClickStackサービスを既に作成し、サービス認証情報を記録済みであることを前提としています。まだ作成していない場合は、Managed ClickStackのはじめにガイドに従い、Vectorの設定を促されるまで進めてください。

データベースとテーブルを作成する​

Vectorでは、データをインジェストする前にテーブルとスキーマを定義しておく必要があります。

まず、データベースを作成します。これは ClickHouse Cloud コンソールで実行できます。

以下の例では logs を使用します:

CREATE DATABASE IF NOT EXISTS logs

データ用のテーブルを作成します。これはデータの出力スキーマと一致させる必要があります。以下の例では、標準的なNginx構造を想定しています。スキーマのベストプラクティスに従い、データに応じて適宜調整してください。プライマリキーの概念を理解した上で、こちらに記載されているガイドラインに基づいてプライマリキーを選択することを強く推奨します。

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)
Nginx プライマリキー

上記のプライマリキーは、ClickStack UI における Nginx ログの典型的なアクセスパターンを想定していますが、本番環境のワークロードによっては調整が必要になる場合があります。

Vector設定にClickHouseシンクを追加する​

Vectorの設定を変更してClickHouseシンクを含めるようにし、既存のパイプラインからイベントを受信できるようinputsフィールドを更新します。

この設定は、上流のVectorパイプラインが既に対象のClickHouseスキーマに合わせてデータを準備済みであることを前提としています。つまり、フィールドが解析され、正しく命名され、挿入に適した型が付与されている必要があります。生のログ行を解析してClickStackに適したスキーマに正規化する完全な例については、以下のNginxの例を参照してください。

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

デフォルトでは、json_each_row 形式の使用を推奨します。この形式は、各イベントを1行につき1つのJSONオブジェクトとしてエンコードします。これはClickStackでJSONデータを取り込む際のデフォルトかつ推奨される形式であり、文字列としてエンコードされたJSONオブジェクトなどの代替形式よりも優先すべきです。

ClickHouseシンクはArrowストリームエンコーディングもサポートしています(現在ベータ版)。これにより高いスループットを実現できますが、重要な制約があります。データベースとテーブルは静的である必要があり、スキーマは起動時に一度だけ取得されるため、動的ルーティングはサポートされていません。このため、Arrowエンコーディングは、固定された明確に定義されたインジェストパイプラインに最適です。

利用可能なシンク設定オプションについては、Vectorドキュメントを確認してください:

注記

上記の例では、Managed ClickStack のデフォルトユーザーを使用しています。本番環境へのデプロイメントでは、適切な権限と制限を持つ専用のインジェストユーザーの作成を推奨します。

ClickStack UIに移動する​

マネージドClickStackサービスに移動し、左側のメニューから「ClickStack」を選択します。オンボーディングが既に完了している場合は、新しいタブでClickStack UIが起動し、自動的に認証されます。完了していない場合は、オンボーディングを進め、入力ソースとしてVectorを選択した後に「Launch ClickStack」を選択します。

Vector 用の ClickStack を起動する

データソースの作成​

ログデータソースを作成します。データソースが存在しない場合、初回ログイン時に作成を求められます。それ以外の場合は、チーム設定に移動し、新しいデータソースを追加してください。

データソースの作成 - Vector

上記の設定は、タイムスタンプとして使用される time_local カラムを持つNginx形式のスキーマを前提としています。このカラムは、可能な限りプライマリキーで宣言されたタイムスタンプカラムである必要があります。このカラムは必須です。

また、Default SELECTを更新して、ログビューで返されるカラムを明示的に定義することを推奨します。サービス名、ログレベル、bodyカラムなどの追加フィールドが利用可能な場合は、これらも設定できます。タイムスタンプ表示カラムは、テーブルのプライマリキーで使用されるカラムと異なる場合、上記で設定したカラムを上書きすることもできます。

上記の例では、データ内にBodyカラムは存在しません。代わりに、利用可能なフィールドからNginxログ行を再構築するSQL式を使用して定義されています。

その他の利用可能なオプションについては、設定リファレンスを参照してください。

データを探索する​

ログビューに移動してデータを確認し、ClickStackの使用を開始します。

ClickStack での Nginx ログ

Vector を使用したサンプルデータセット​

より具体的な例として、以下では Nginx のログファイル を使用します。

以下のガイドは、Managed ClickStackサービスを既に作成し、サービス認証情報を記録済みであることを前提としています。まだ作成していない場合は、Managed ClickStackのはじめにガイドに従い、Vectorの設定を促されるまで進めてください。

Vectorのインストール​

先に進む前に、インジェストパイプラインを実行する予定のシステムに Vector がインストールされていること を確認してください。お使いの環境に適した事前ビルド済みバイナリまたはパッケージをインストールするには、公式の Vector インストールガイドに従ってください。

インストールが完了したら、以下の設定手順を続行する前に、vector バイナリが PATH に通っていることを確認してください。

これは ClickStack OTel collector と同じインスタンスにインストールしてかまいません。

Vector を本番環境に移行する際は、アーキテクチャおよびセキュリティに関するベストプラクティスに従ってください。

サンプルデータをダウンロードする​

サンプルデータセットで試してみたい場合は、以下の nginx サンプルをダウンロードしてください。

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
注記

このデータは、解析を容易にするためにログを JSON 形式で出力するよう構成された Nginx インスタンスから収集されたものです。これらのログ用の Nginx 設定については、「Monitoring Nginx Logs with ClickStack」 を参照してください。

データベースとテーブルを作成する​

Vectorでは、データをインジェストする前にテーブルとスキーマを定義しておく必要があります。

まずデータベースを作成します。これは ClickHouse Cloud コンソールから実行できます。

データベース logs を作成します:

CREATE DATABASE IF NOT EXISTS logs

データ用のテーブルを作成してください。

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)
Nginx プライマリキー

上記のプライマリキーは、ClickStack UI における Nginx ログの典型的なアクセスパターンを想定していますが、本番環境のワークロードによっては調整が必要になる場合があります。

Vector設定をコピー​

Vectorの設定をコピーし、nginx.yamlファイルを作成した上で、CLICKHOUSE_ENDPOINTとCLICKHOUSE_PASSWORDを設定します。

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"
注記

上記の例では、Managed ClickStackのデフォルトユーザーを使用しています。本番環境へのデプロイメントでは、適切な権限と制限を持つ専用のインジェストユーザーの作成を推奨します。

Vectorを起動する​

以下のコマンドでVectorを起動します。その前に、ファイルオフセットを記録するためのデータディレクトリを作成してください。

mkdir ./.vector-data
vector --config nginx.yaml

ClickStack UIに移動する​

Managed ClickStackサービスに移動し、左側のメニューから"ClickStack"を選択します。オンボーディングが既に完了している場合は、新しいタブでClickStack UIが起動し、自動的に認証されます。完了していない場合は、オンボーディングを進め、入力ソースとしてVectorを選択した後に「Launch ClickStack」を選択します。

Vector 向けに ClickStack を起動する

データソースの作成​

ログデータソースを作成します。データソースが存在しない場合、初回ログイン時に作成を促すメッセージが表示されます。既にデータソースが存在する場合は、チーム設定に移動して新しいデータソースを追加してください。

データソースの作成 - Vector

この設定は、タイムスタンプとして使用されるtime_localカラムを持つNginxスキーマを想定しています。これはプライマリキーで宣言されているタイムスタンプカラムです。このカラムは必須です。

また、デフォルトの select を time_local, remote_addr, status, request に指定しており、これによりログビューで返されるカラムを定義しています。

上記の例では、Bodyカラムはデータ内に存在しません。代わりに、SQL式として定義されています:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

構造化フィールドからログ行を再構築します。

その他のオプションについては、設定リファレンスを参照してください。

データを探索する​

October 20th, 2025の検索ビューに移動し、データを探索してClickStackの使用を開始します。

HyperDX UI