Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Vector によるインジェスト

View as MarkdownEdit this pageReport an issueSet up docs MCP

Vector は、高性能でベンダーニュートラルなオブザーバビリティデータパイプラインです。一般的に、さまざまなソースからログやメトリクスを収集・変換・ルーティングするために使用されており、特に柔軟性が高く、リソース消費が少ないことから、ログのインジェストで広く利用されています。

Vector を ClickStack と併用する場合、ユーザーは独自のスキーマを定義する必要があります。これらのスキーマは OpenTelemetry の規約に従うこともできますが、ユーザー定義のイベント構造を表す完全にカスタムなものにすることも可能です。実際には、Vector によるインジェストは ログ で使われることが最も多く、これはデータを ClickHouse に書き込む前に、パースやエンリッチメントを完全に制御したい場合に適しています。

このガイドでは、ClickStack Open Source と Managed ClickStack の両方を対象に、Vector を使って ClickStack にデータを取り込む方法に焦点を当てます。簡潔にするため、Vector のソースやパイプライン設定については詳しく扱いません。その代わりに、データを ClickHouse に書き込む sink の設定と、生成されるスキーマが ClickStack と互換性を持つようにすることに重点を置きます。

ClickStack で厳密に必要なのは、オープンソース版でもマネージド版でも、データに timestamp カラム (または同等の時刻フィールド) が含まれていることだけです。これは ClickStack UI でデータソースを設定する際に指定できます。

Vector を使用したデータの送信


以下のガイドは、Managed ClickStack のサービスを作成済みで、サービスの認証情報を控えていることを前提としています。まだ完了していない場合は、Managed ClickStack の Getting Started ガイドに従い、Vector の設定を促される手順まで進めてください。

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

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

まず、データベースを作成します。これは ClickHouse Cloud console から行えます。

以下の例では、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)

Vector 設定に ClickHouse シンクを追加

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

この設定は、上流の Vector パイプラインで、対象の ClickHouse スキーマに合うようにデータがすでに整えられていることを前提としています。つまり、フィールドは適切にパースされ、正しい名前が付けられ、insert できる型になっている必要があります。生のログ行を 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>"

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

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

利用可能な sink の設定オプションについては、Vector ドキュメントを確認することを推奨します。

データソースを作成する

ログ用のデータソースを作成します。データソースがまだ存在しない場合は、初回ログイン時に作成するよう求められます。すでにある場合は、Team Settings に移動して新しいデータソースを追加してください。

データソースの作成 - vector

上記の設定は、time_local カラムをタイムスタンプとして使用する Nginx スタイルのスキーマを前提としています。可能であれば、これは主キーで宣言されているタイムスタンプ用のカラムにしてください。このカラムは必須です。

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

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

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

データを確認する

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

ClickStack 内の Nginx ログ

Vector を使ったデータセットの例

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

以下のガイドは、Managed ClickStack のサービスを作成済みで、サービスの認証情報を控えていることを前提としています。まだ完了していない場合は、Managed ClickStack の Getting Started ガイドに従い、Vector の設定を求められる手順まで進めてください。

Vectorのインストール

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

インストールが完了したら、以下の設定手順に進む前に、vector バイナリがパスに含まれていて使用できることを確認してください。

これは ClickStack OTel collector と同じインスタンスにインストールできます。

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

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

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

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

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

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

まず、データベースを作成します。これは ClickHouse Cloud console から行えます。

データベース 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)

Vector の設定をコピー

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

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>"

Vector を起動する

ファイルオフセットを記録するため、まずデータディレクトリを作成してから、次のコマンドで Vector を起動します。

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

データソースを作成する

ログ用のデータソースを作成します。データソースがまだ1つもない場合は、初回ログイン時に作成するよう求められます。すでにある場合は、Team Settings に移動して新しいデータソースを追加してください。

データソースの作成 - 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, '"'
)

これにより、構造化されたフィールドからログ行を再構成します。

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

データを確認する

データを確認して ClickStack の利用を始めるには、October 20th, 2025 の Search view に移動してください。

HyperDX UI
Navigation