> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ClickStack 向けの Vector によるデータインジェスト - ClickHouse オブザーバビリティ スタック
# Vector によるインジェスト
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
[Vector](https://vector.dev) は、高性能でベンダーニュートラルなオブザーバビリティデータパイプラインです。一般的に、さまざまなソースからログやメトリクスを収集・変換・ルーティングするために使用されており、特に柔軟性が高く、リソース消費が少ないことから、ログのインジェストで広く利用されています。
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](/docs/ja/clickstack/getting-started/managed) ガイドに従い、Vector の設定を促される手順まで進めてください。
Vector では、データをインジェストする前に、テーブルとスキーマを定義しておく必要があります。
まず、データベースを作成します。これは [ClickHouse Cloud console](/docs/ja/products/cloud/features/sql-console-features/sql-console) から行えます。
以下の例では、`logs` を使用します。
```sql theme={null}
CREATE DATABASE IF NOT EXISTS logs
```
データ用のテーブルを作成します。これはデータの出力スキーマに一致している必要があります。以下の例では、一般的な Nginx の構造を前提としています。[スキーマのベストプラクティス](/docs/ja/concepts/best-practices/select-data-type)に従い、実際のデータに合わせて適宜調整してください。[主キーの概念](/docs/ja/concepts/core-concepts/primary-indexes)を理解したうえで、[こちら](/docs/ja/clickstack/managing/performance-tuning#choosing-a-primary-key)に示されているガイドラインに基づいて主キーを選択することを**強く推奨**します。
```sql theme={null}
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 シンクを追加し、既存のパイプラインからイベントを受信するよう `inputs` フィールドを更新します。
この設定は、上流の Vector パイプラインで、**対象の ClickHouse スキーマに合うようにデータがすでに整えられている**ことを前提としています。つまり、フィールドは適切にパースされ、正しい名前が付けられ、insert できる型になっている必要があります。生のログ行を ClickStack に適したスキーマへパースして正規化する一連の流れについては、[**以下の Nginx の例**](#example-dataset-with-vector)を参照してください。
```yaml theme={null}
sinks:
clickhouse:
type: clickhouse
inputs:
- your_input
endpoint: ""
database: logs
format: json_each_row
table: nginx_logs
skip_unknown_fields: true
auth:
strategy: "basic"
user: "default"
password: ""
```
デフォルトでは、各イベントを1行につき1つの JSON オブジェクトとしてエンコードする **`json_each_row`** フォーマットの使用を推奨します。これは JSON データを取り込む際の ClickStack のデフォルトかつ推奨のフォーマットであり、JSON オブジェクトを文字列としてエンコードするような代替フォーマットより優先して使用してください。
ClickHouse sink は **Arrow ストリームエンコーディング** (現在ベータ) もサポートしています。これにより、より高いスループットが得られる可能性がありますが、重要な制約があります。スキーマは起動時に一度だけ取得されるため、データベースとテーブルは固定である必要があり、動的ルーティングはサポートされません。そのため、Arrow エンコーディングは、固定されていて明確に定義されたインジェストパイプラインに最適です。
利用可能な sink の設定オプションについては、[Vector ドキュメント](https://vector.dev/docs/reference/configuration/sinks/clickhouse)を確認することを推奨します。
上記の例では、Managed ClickStack のデフォルトユーザーを使用しています。本番環境へのデプロイでは、適切な権限と制限を持つ[専用のインジェストユーザーを作成する](/docs/ja/clickstack/ingesting-data/collector#creating-an-ingestion-user)ことを推奨します。
Managed ClickStack サービスに移動し、左側のメニューから "ClickStack" を選択します。すでにオンボーディングを完了している場合は、新しいタブで ClickStack UI が開き、自動的に認証されます。まだ完了していない場合は、オンボーディングを進め、入力ソースとして Vector を選択した後に「Launch ClickStack」を選択してください。
ログ用のデータソースを作成します。データソースがまだ存在しない場合は、初回ログイン時に作成するよう求められます。すでにある場合は、Team Settings に移動して新しいデータソースを追加してください。
上記の設定は、`time_local` カラムをタイムスタンプとして使用する Nginx スタイルのスキーマを前提としています。可能であれば、これは主キーで宣言されているタイムスタンプ用のカラムにしてください。このカラムは必須です。
また、ログビューで返すカラムを明示的に定義するために、`Default SELECT` を更新することも推奨します。サービス名、ログレベル、body カラムなどの追加フィールドが利用可能な場合は、それらも設定できます。タイムスタンプの表示カラムも、テーブルの主キーで使用されるカラムや上記で設定したカラムと異なる場合は、上書きできます。
上記の例では、データ内に `Body` カラムは存在しません。代わりに、利用可能なフィールドから Nginx のログ行を再構成する SQL 式を使って定義しています。
利用可能なその他のオプションについては、[設定リファレンス](/docs/ja/clickstack/managing/config) を参照してください。
ログビューに移動してデータを確認し、ClickStack の利用を開始します。
Vector では、データをインジェストする前に、テーブルとスキーマをあらかじめ定義しておく必要があります。
まず、データベースを作成します。これは、[ClickHouse Web UI](/docs/ja/concepts/features/interfaces/http#web-ui) の [http://localhost:8123/play](http://localhost:8123/play) から行えます。ユーザー名とパスワードには、デフォルトの `api:api` を使用します。
以下の例では、`logs` を使用します。
```sql theme={null}
CREATE DATABASE IF NOT EXISTS logs
```
データ用のテーブルを作成します。これはデータの出力スキーマに一致している必要があります。以下の例では、一般的な Nginx の構造を前提としています。[スキーマのベストプラクティス](/docs/ja/concepts/best-practices/select-data-type)に従い、実際のデータに合わせて適宜調整してください。[主キーの概念](/docs/ja/concepts/core-concepts/primary-indexes)を理解したうえで、[こちら](/docs/ja/clickstack/managing/performance-tuning#choosing-a-primary-key)に示されているガイドラインに基づいて主キーを選択することを**強く推奨**します。
```sql theme={null}
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 から ClickStack へのインジェストは、collector が公開する OTLP endpoint を経由せず、ClickHouse に直接送信する必要があります。
Vector の設定を変更して ClickHouse sink を追加し、`inputs` フィールドを更新して既存の pipeline からイベントを受信するようにしてください。
この設定は、上流の Vector pipeline ですでに**対象の ClickHouse スキーマに合うようにデータが準備されている**ことを前提としています。つまり、フィールドがパースされ、正しい名前が付けられ、挿入に適した型になっている必要があります。生のログ行を ClickStack に適したスキーマへパースして正規化する一連の流れについては、[**以下の Nginx の例**](#example-dataset-with-vector)を参照してください。
```yaml theme={null}
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 のドキュメント](https://vector.dev/docs/reference/configuration/sinks/clickhouse)を確認することを推奨します。
上記の例では、ClickStack Open Source で `api` ユーザーを使用しています。本番環境へのデプロイでは、適切な権限と制限を持つ[専用のインジェストユーザーを作成する](/docs/ja/clickstack/ingesting-data/collector#creating-an-ingestion-user)ことを推奨します。また、上記の設定は Vector が ClickStack と同じホスト上で実行されていることを前提としていますが、本番環境では異なる構成になる可能性が高いでしょう。データはセキュアな HTTPS ポート 8443 経由で送信することを推奨します。
[http://localhost:8080](http://localhost:8080) で ClickStack UI にアクセスします。オンボーディングが完了していない場合は、ユーザーを作成してください。
Team Settings に移動し、新しいデータソースを追加します。
上記の設定は、タイムスタンプとして `time_local` カラムを使用する Nginx 形式のスキーマを前提としています。可能であれば、このカラムには主キーで指定されているタイムスタンプ用のカラムを使用してください。このカラムは必須です。
また、ログビューで返すカラムを明示的に定義するため、`Default SELECT` を更新することも推奨します。service name、ログレベル、本文カラムなどの追加フィールドが利用可能な場合は、それらも設定できます。タイムスタンプ表示用のカラムが、テーブルの主キーで使用され、上記で設定したカラムと異なる場合は、その設定を上書きすることもできます。
上記の例では、データ内に `Body` カラムは存在しません。代わりに、利用可能なフィールドから Nginx のログ行を再構成する SQL 式を使って定義されています。
その他のオプションについては、[設定リファレンス](/docs/ja/clickstack/managing/config)を参照してください。
ログビューに移動してデータを確認し、ClickStack の利用を開始します。
## Vector を使ったデータセットの例
より具体的な例として、以下では **Nginx のログファイル** を使用します。
以下のガイドは、Managed ClickStack のサービスを作成済みで、サービスの認証情報を控えていることを前提としています。まだ完了していない場合は、Managed ClickStack の [Getting Started](/docs/ja/clickstack/getting-started/managed) ガイドに従い、Vector の設定を求められる手順まで進めてください。
先に進む前に、インジェスト パイプラインを実行するシステムに **Vector がインストールされている**ことを確認してください。ご利用の環境に適したビルド済みバイナリまたはパッケージをインストールするには、[Vector の公式インストールガイド](https://vector.dev/docs/setup/installation/)に従ってください。
インストールが完了したら、以下の設定手順に進む前に、`vector` バイナリがパスに含まれていて使用できることを確認してください。
これは ClickStack OTel collector と同じインスタンスにインストールできます。
[Vector を本番環境に移行する](https://vector.dev/docs/setup/going-to-prod/)際は、アーキテクチャとセキュリティのベストプラクティスに従ってください。
サンプルデータセットで試す場合は、次の nginx サンプルをダウンロードしてください。
```bash theme={null}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
```
このデータは、パースしやすいようにログを JSON フォーマットで出力するよう設定された Nginx インスタンスから収集されたものです。これらのログに対応する Nginx の設定については、["ClickStack で Nginx ログを監視する"](/docs/ja/clickstack/integration-examples/nginx-logs#configure-nginx)を参照してください。
Vector では、データのインジェスト前にテーブルとスキーマを定義しておく必要があります。
まず、データベースを作成します。これは [ClickHouse Cloud console](/docs/ja/products/cloud/features/sql-console-features/sql-console) から行えます。
データベース `logs` を作成します。
```sql theme={null}
CREATE DATABASE IF NOT EXISTS logs
```
データを格納するテーブルを作成します。
```sql theme={null}
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_ENDPOINT` と `CLICKHOUSE_PASSWORD` を設定した `nginx.yaml` ファイルを作成します。
```yaml theme={null}
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: ""
database: logs
format: json_each_row
table: nginx_logs
skip_unknown_fields: true
auth:
strategy: "basic"
user: "default"
password: ""
```
上記の例では、Managed ClickStack のデフォルトユーザーを使用しています。本番環境へのデプロイメントでは、適切な権限と制限を設定した[専用のインジェスト用ユーザーを作成する](/docs/ja/clickstack/ingesting-data/collector#creating-an-ingestion-user)ことを推奨します。
ファイルオフセットを記録するため、まずデータディレクトリを作成してから、次のコマンドで Vector を起動します。
```bash theme={null}
mkdir ./.vector-data
vector --config nginx.yaml
```
Managed ClickStack サービスに移動し、左側のメニューから "ClickStack" を選択します。すでにオンボーディングを完了している場合は、新しいタブで ClickStack UI が起動し、自動的に認証されます。まだ完了していない場合は、入力ソースとして Vector を選択したらオンボーディングを進め、"Launch ClickStack" を選択します。
ログ用のデータソースを作成します。データソースがまだ1つもない場合は、初回ログイン時に作成するよう求められます。すでにある場合は、Team Settings に移動して新しいデータソースを追加してください。
この設定では、`time_local` カラムをタイムスタンプとして使用する Nginx スキーマを前提としています。これは主キーで宣言されているタイムスタンプ用のカラムです。このカラムは必須です。
また、デフォルトの select として `time_local, remote_addr, status, request` を指定しています。これにより、ログビューで返されるカラムが定義されます。
上の例では、`Body` カラムはデータ内に存在しません。代わりに、次の SQL 式として定義されています。
```sql theme={null}
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, '"'
)
```
これにより、構造化されたフィールドからログ行を再構成します。
そのほかのオプションについては、[設定リファレンス](/docs/ja/clickstack/managing/config)を参照してください。
データを確認して ClickStack の利用を始めるには、`October 20th, 2025` の Search view に移動してください。
以下のガイドは、[Getting Started ガイド](/docs/ja/clickstack/getting-started/oss)を参照してClickStack Open Sourceをセットアップ済みであることを前提としています。
先に進む前に、インジェスト パイプラインを実行するシステムに **Vector がインストールされている**ことを確認してください。ご利用の環境に適したビルド済みバイナリまたはパッケージをインストールするには、[Vector の公式インストールガイド](https://vector.dev/docs/setup/installation/)に従ってください。
インストールが完了したら、以下の設定手順に進む前に、`vector` バイナリがパスに含まれていて使用できることを確認してください。
これは ClickStack OTel collector と同じインスタンスにインストールできます。
[Vector を本番環境に移行する](https://vector.dev/docs/setup/going-to-prod/)際は、アーキテクチャとセキュリティのベストプラクティスに従ってください。
サンプルデータセットで試す場合は、次の nginx サンプルをダウンロードしてください。
```bash theme={null}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
```
このデータは、パースしやすいようにログを JSON フォーマットで出力するよう設定された Nginx インスタンスから収集されたものです。これらのログに対応する Nginx の設定については、["ClickStack で Nginx ログを監視する"](/docs/ja/clickstack/integration-examples/nginx-logs#configure-nginx)を参照してください。
Vector では、データをインジェストする前に、テーブルとスキーマを定義しておく必要があります。
まず、データベースを作成します。これは、[ClickHouse Web UI](/docs/ja/concepts/features/interfaces/http#web-ui) の [http://localhost:8123/play](http://localhost:8123/play) から実行できます。デフォルトのユーザー名とパスワード `api:api` を使用してください。
データベース `logs` を作成します。
```sql theme={null}
CREATE DATABASE IF NOT EXISTS logs
```
データを格納するテーブルを作成します。
```sql theme={null}
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 から ClickStack へのインジェストは、collector が公開する OTLP endpoint を経由せず、ClickHouse に直接送信する必要があります。
Vector の設定をコピーし、`nginx.yaml` ファイルを作成します。
```yaml theme={null}
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: "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` ユーザーを使用しています。本番環境へのデプロイでは、適切な権限と制限を持つ[専用のインジェスト用ユーザーを作成する](/docs/ja/clickstack/ingesting-data/collector#creating-an-ingestion-user)ことをおすすめします。また、この設定は Vector が ClickStack と同じホスト上で動作していることを前提としていますが、本番環境ではそうでない可能性が高いでしょう。データは安全な HTTPS ポート 8443 経由で送信することをおすすめします。
次のコマンドを実行して Vector を起動します。
```bash theme={null}
mkdir ./.vector-data
vector --config nginx-local.yaml
```
`Team -> Sources` からログ用のデータソースを作成します
この設定は、タイムスタンプとして `time_local` カラムを使用する Nginx スキーマを前提としています。これは主キーで宣言されているタイムスタンプ用のカラムです。このカラムは必須です。
また、デフォルトの SELECT として `time_local, remote_addr, status, request` を指定しています。これにより、ログビューで返されるカラムが定義されます。
上の例では、データ内に `Body` カラムは存在しません。代わりに、これは次の SQL 式として定義されています。
```sql theme={null}
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, '"'
)
```
これにより、構造化されたフィールドからログ行を再構成します。
そのほかのオプションについては、[設定リファレンス](/docs/ja/clickstack/managing/config)を参照してください。
[http://localhost:8080](http://localhost:8080) で ClickStack UI にアクセスします。オンボーディングが完了していない場合は、ユーザーを作成してください。
データを確認して ClickStack の利用を始めるには、`October 20th, 2025` の Search view に移動してください。