Vector によるインジェスト - ClickHouse Documentation

Vector は、高性能でベンダーニュートラルなオブザーバビリティデータパイプラインです。一般的に、さまざまなソースからログやメトリクスを収集・変換・ルーティングするために使用されており、特に柔軟性が高く、リソース消費が少ないことから、ログのインジェストで広く利用されています。 Vector を ClickStack と併用する場合、ユーザーは独自のスキーマを定義する必要があります。これらのスキーマは OpenTelemetry の規約に従うこともできますが、ユーザー定義のイベント構造を表す完全にカスタムなものにすることも可能です。実際には、Vector によるインジェストはログで使われることが最も多く、これはデータを ClickHouse に書き込む前に、パースやエンリッチメントを完全に制御したい場合に適しています。このガイドでは、ClickStack Open Source と Managed ClickStack の両方を対象に、Vector を使って ClickStack にデータを取り込む方法に焦点を当てます。簡潔にするため、Vector のソースやパイプライン設定については詳しく扱いません。その代わりに、データを ClickHouse に書き込む sink の設定と、生成されるスキーマが ClickStack と互換性を持つようにすることに重点を置きます。 ClickStack で厳密に必要なのは、オープンソース版でもマネージド版でも、データに timestamp カラム (または同等の時刻フィールド) が含まれていることだけです。これは ClickStack UI でデータソースを設定する際に指定できます。

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

Managed ClickStack
オープンソース版 ClickStack

以下のガイドは、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)

Nginx の主キー上記の主キーは、ClickStack UI で Nginx のログを扱う際の一般的なアクセスパターンを前提としていますが、本番環境ではワークロードに応じて調整が必要になる場合があります。

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 ドキュメントを確認することを推奨します。

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

ClickStack UI に移動する

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

データソースを作成する

ログ用のデータソースを作成します。データソースがまだ存在しない場合は、初回ログイン時に作成するよう求められます。すでにある場合は、Team Settings に移動して新しいデータソースを追加してください。上記の設定は、time_local カラムをタイムスタンプとして使用する Nginx スタイルのスキーマを前提としています。可能であれば、これは主キーで宣言されているタイムスタンプ用のカラムにしてください。このカラムは必須です。また、ログビューで返すカラムを明示的に定義するために、Default SELECT を更新することも推奨します。サービス名、ログレベル、body カラムなどの追加フィールドが利用可能な場合は、それらも設定できます。タイムスタンプの表示カラムも、テーブルの主キーで使用されるカラムや上記で設定したカラムと異なる場合は、上書きできます。上記の例では、データ内に Body カラムは存在しません。代わりに、利用可能なフィールドから Nginx のログ行を再構成する SQL 式を使って定義しています。利用可能なその他のオプションについては、設定リファレンスを参照してください。

データを確認する

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

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

Vector では、データをインジェストする前に、テーブルとスキーマをあらかじめ定義しておく必要があります。まず、データベースを作成します。これは、ClickHouse Web UI の http://localhost:8123/play から行えます。ユーザー名とパスワードには、デフォルトの api:api を使用します。以下の例では、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 sink を追加する

Vector から ClickStack へのインジェストは、collector が公開する OTLP endpoint を経由せず、ClickHouse に直接送信する必要があります。Vector の設定を変更して ClickHouse sink を追加し、inputs フィールドを更新して既存の pipeline からイベントを受信するようにしてください。この設定は、上流の Vector pipeline ですでに対象の ClickHouse スキーマに合うようにデータが準備されていることを前提としています。つまり、フィールドがパースされ、正しい名前が付けられ、挿入に適した型になっている必要があります。生のログ行を ClickStack に適したスキーマへパースして正規化する一連の流れについては、以下の Nginx の例を参照してください。

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "http://localhost:8123"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "api"
      password: "api"

デフォルトでは、各イベントを 1 行につき 1 つの JSON オブジェクトとしてエンコードする json_each_row フォーマットの使用を推奨します。これは、JSON データを取り込む際の ClickStack のデフォルトかつ推奨されるフォーマットであり、JSON オブジェクトを文字列としてエンコードするような代替フォーマットより優先して使用してください。ClickHouse sink は Arrow stream encoding (現在ベータ) にも対応しています。これはより高いスループットを実現できる可能性がありますが、重要な制約があります。スキーマは起動時に 1 回だけ取得されるため、データベースとテーブルは固定である必要があり、動的ルーティングはサポートされません。このため、Arrow stream encoding は、固定的で明確に定義されたインジェストパイプラインに最適です。利用可能な sink の設定オプションについては、Vector のドキュメントを確認することを推奨します。

上記の例では、ClickStack Open Source で api ユーザーを使用しています。本番環境へのデプロイでは、適切な権限と制限を持つ専用のインジェストユーザーを作成することを推奨します。また、上記の設定は Vector が ClickStack と同じホスト上で実行されていることを前提としていますが、本番環境では異なる構成になる可能性が高いでしょう。データはセキュアな HTTPS ポート 8443 経由で送信することを推奨します。

ClickStack UI にアクセスする

http://localhost:8080 で ClickStack UI にアクセスします。オンボーディングが完了していない場合は、ユーザーを作成してください。

データソースを作成する

Team Settings に移動し、新しいデータソースを追加します。上記の設定は、タイムスタンプとして time_local カラムを使用する Nginx 形式のスキーマを前提としています。可能であれば、このカラムには主キーで指定されているタイムスタンプ用のカラムを使用してください。このカラムは必須です。また、ログビューで返すカラムを明示的に定義するため、Default SELECT を更新することも推奨します。service name、ログレベル、本文カラムなどの追加フィールドが利用可能な場合は、それらも設定できます。タイムスタンプ表示用のカラムが、テーブルの主キーで使用され、上記で設定したカラムと異なる場合は、その設定を上書きすることもできます。上記の例では、データ内に Body カラムは存在しません。代わりに、利用可能なフィールドから Nginx のログ行を再構成する SQL 式を使って定義されています。その他のオプションについては、設定リファレンスを参照してください。

データを調べる

ログビューに移動してデータを調べ、ClickStack を使い始めましょう。

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

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

Managed ClickStack
オープンソース版 ClickStack

以下のガイドは、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

このデータは、パースしやすいようにログを JSON フォーマットで出力するよう設定された Nginx インスタンスから収集されたものです。これらのログに対応する Nginx の設定については、“ClickStack で Nginx ログを監視する”を参照してください。

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

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)

Nginxの主キー上記の主キーは、ClickStack UIにおけるNginxログの一般的なアクセスパターンを前提としていますが、本番環境ではワークロードに応じて調整が必要になる場合があります。

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に適したDateTimeフォーマット
      .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” を選択します。

データソースを作成する

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

以下のガイドは、Getting Started ガイドを参照してClickStack Open Sourceをセットアップ済みであることを前提としています。

Vectorのインストール

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

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

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

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

Vector では、データをインジェストする前に、テーブルとスキーマを定義しておく必要があります。まず、データベースを作成します。これは、ClickHouse Web UI の http://localhost:8123/play から実行できます。デフォルトのユーザー名とパスワード api:api を使用してください。データベース 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 から ClickStack へのインジェストは、collector が公開する OTLP endpoint を経由せず、ClickHouse に直接送信する必要があります。Vector の設定をコピーし、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に適したDateTimeフォーマット
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "http://localhost:8123"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "api"
      password: "api"

上記の例では、ClickStack Open Source で api ユーザーを使用しています。本番環境へのデプロイでは、適切な権限と制限を持つ専用のインジェスト用ユーザーを作成することをおすすめします。また、この設定は Vector が ClickStack と同じホスト上で動作していることを前提としていますが、本番環境ではそうでない可能性が高いでしょう。データは安全な HTTPS ポート 8443 経由で送信することをおすすめします。

Vector を起動する

次のコマンドを実行して Vector を起動します。

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

データソースを作成する

Team -> Sources からログ用のデータソースを作成しますこの設定は、タイムスタンプとして 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 UIにアクセスする

http://localhost:8080 で ClickStack UI にアクセスします。オンボーディングが完了していない場合は、ユーザーを作成してください。

データを確認する

2025年10月20日 の検索ビューに移動してデータを確認し、ClickStack を使い始めましょう。

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

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

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

​ClickStack UI に移動する

​データソースを作成する

​データを確認する

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

​Vector の設定に ClickHouse sink を追加する

​ClickStack UI にアクセスする

​データソースを作成する

​データを調べる

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

​Vectorのインストール

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

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

​Vector の設定をコピー

​Vector を起動する

​ClickStack UIに移動する

​データソースを作成する

​データを確認する

​Vectorのインストール

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

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

​Vector の設定をコピー

​Vector を起動する

​データソースを作成する

​ClickStack UIにアクセスする

​データを確認する

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

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

Vector 設定に ClickHouse シンクを追加

ClickStack UI に移動する

データソースを作成する

データを確認する

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

Vector の設定に ClickHouse sink を追加する

ClickStack UI にアクセスする

データソースを作成する

データを調べる

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

Vectorのインストール

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

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

Vector の設定をコピー

Vector を起動する

ClickStack UIに移動する

データソースを作成する

データを確認する

Vectorのインストール

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

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

Vector の設定をコピー

Vector を起動する

データソースを作成する

ClickStack UIにアクセスする

データを確認する