> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL 用 vsql_stat_ch 拡張機能

> vsql_stat_ch 拡張機能は、完了した MySQL ステートメントごとに 1 つのイベントを記録し、ネイティブプロトコルまたは HTTP 経由で ClickHouse にバッチで送信します。

`vsql_stat_ch` は、サーバーが完了するすべてのステートメントについて 1 つのイベントを記録し、それらをバッチで ClickHouse に送信します。クエリ履歴は、2 つの間にコレクタープロセスを置くことなく、集計できる場所に置かれます。ClickHouse のネイティブプロトコルまたは HTTP を話し、サーバーの実行中にそれらを切り替えられます。

| | |
| - | - |
| **メンテナー** | VillageSQL |
| **ソースと完全なドキュメント** | [villagesql/vsql-stat-ch](https://github.com/villagesql/vsql-stat-ch) |
| **ライセンス** | GPL-2.0 |
| **機能** | プレビュー |

> [!WARNING]
>
> この拡張機能は 4 つのプレビュー機能を使用するため、サーバーを `--vsql_allow_preview_extensions=ON` で起動する必要があります。そうでない場合、`INSTALL EXTENSION` は拒否されます。

## インストール

`vsql_stat_ch` はサーバーに同梱されていないため、インストールする前にビルドしてください。ClickHouse クライアントを同梱しているため、サブモジュールごとリポジトリをクローンします。

```bash theme={null}
git clone --recurse-submodules https://github.com/villagesql/vsql-stat-ch.git
cd vsql-stat-ch
VillageSQL_BUILD_DIR=/path/to/villagesql/build ./build.sh
```

生成された `vsql_stat_ch.veb` をシステム変数 `veb_dir` が示すディレクトリにコピーし、インストールします。

```sql theme={null}
INSTALL EXTENSION vsql_stat_ch;
```

インストールされたことを確認します。

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_stat_ch';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_stat_ch   |
+----------------+
```

## 追加される機能

キャプチャ経路、一連の設定、および一連のステータスカウンターを追加します。SQL 関数は追加しません。

| 設定 | デフォルト | 制御内容 |
| - | - | - |
| `vsql_stat_ch.enabled` | `OFF` | ステートメントをキャプチャするかどうか |
| `vsql_stat_ch.transport` | `native` | ポート 9000 向けの `native`、または HTTP インターフェイス向けの `http` |
| `vsql_stat_ch.clickhouse_host` | `localhost` | ClickHouse のホスト。ネイティブトランスポート用 |
| `vsql_stat_ch.clickhouse_port` | `9000` | そのポート |
| `vsql_stat_ch.clickhouse_url` | 空 | ベース URL。HTTP トランスポート用 |
| `vsql_stat_ch.clickhouse_database` | `default` | 送信先データベース |
| `vsql_stat_ch.clickhouse_table` | `events_raw` | 送信先テーブル |
| `vsql_stat_ch.clickhouse_user`, `vsql_stat_ch.clickhouse_password` | `default`, 空 | 認証情報 |
| `vsql_stat_ch.compression` | `1` | 0 はなし、1 は LZ4、2 は zstd |
| `vsql_stat_ch.batch_max` | `10000` | 1 つのバッチに入れるイベント数 |
| `vsql_stat_ch.flush_interval_ms` | `1000` | 上限に満たないバッチが待つ時間 |
| `vsql_stat_ch.queue_capacity` | `100000` | メモリ内で待機できるイベント数。最小 `1000`。最初のイベントがキャプチャされる前に設定するか、`SET PERSIST` と再起動で設定する |
| `vsql_stat_ch.statement_max_bytes` | `4096` | ステートメントのテキストを切り詰める位置 |
| `vsql_stat_ch.http_timeout_secs` | `10` | HTTP トランスポートのタイムアウト |

## 例

送信先の ClickHouse インスタンスを指定して、キャプチャを開始します。

```sql theme={null}
SET GLOBAL vsql_stat_ch.clickhouse_host = 'clickhouse';
SET GLOBAL vsql_stat_ch.clickhouse_database = 'default';
SET GLOBAL vsql_stat_ch.clickhouse_table = 'events_raw';
SET GLOBAL vsql_stat_ch.enabled = ON;
```

ステータスカウンターで動作を監視します。

```sql theme={null}
SHOW STATUS LIKE 'vsql_stat_ch%';
```

```
+-------------------------------+-------+
| Variable_name                 | Value |
+-------------------------------+-------+
| vsql_stat_ch.events_archived  | 0     |
| vsql_stat_ch.events_captured  | 0     |
| vsql_stat_ch.events_dropped   | 0     |
| vsql_stat_ch.flush_errors     | 0     |
| vsql_stat_ch.last_flush_utime | 0     |
| vsql_stat_ch.queue_depth      | 0     |
+-------------------------------+-------+
```

`events_dropped` が増え続けるのは、キューが排出されるより速く満たされたことを意味します。ClickHouse の応答が遅いか、`queue_capacity` がステートメントの頻度に対して小さすぎるかのどちらかです。

> [!NOTE]
>
> ステートメントのテキストは `statement_max_bytes` で切り詰められ、ステートメントのテキストにはあなたのデータのリテラルが含まれることがあります。キャプチャを有効にする前に、ClickHouse のテーブルに何を保持させてよいかを決めてください。

## 関連項目

* [拡張機能の管理](https://villagesql.com/docs/ja/extensions/managing.md) — 拡張機能の設定の読み書き方法
* [プレビュー機能](https://villagesql.com/docs/ja/extensions/build/preview-capabilities.md) — プレビューフラグが有効にするものと、それが約束するもの
* [利用可能な拡張機能](https://villagesql.com/docs/ja/extensions/catalog) — 完全なカタログ
* [villagesql/vsql-stat-ch](https://github.com/villagesql/vsql-stat-ch) — ソース、イベントスキーマ、および既知の制限事項


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.