> ## 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.

# Extensão vsql_stat_ch para MySQL

> A extensão vsql_stat_ch registra um evento por instrução MySQL concluída e envia lotes ao ClickHouse pelo seu protocolo nativo ou por HTTP.

O `vsql_stat_ch` registra um evento para cada instrução que o servidor conclui
e os envia ao ClickHouse em lotes. O histórico de consultas passa então a
ficar em um lugar onde você pode agregá-lo, sem um processo coletor entre os
dois. Ele fala o protocolo nativo do ClickHouse ou HTTP, e você pode alternar
entre eles com o servidor em execução.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-stat-ch](https://github.com/villagesql/vsql-stat-ch) |
| **Licença** | GPL-2.0 |
| **Capability** | Preview |

> [!WARNING]
>
> Esta extensão usa quatro capabilities Preview, então o servidor precisa ser
> iniciado com `--vsql_allow_preview_extensions=ON`. Caso contrário, o
> `INSTALL EXTENSION` é recusado.

## Instalar

O `vsql_stat_ch` não vem incluído com o servidor, então compile-o antes de
instalá-lo. Clone o repositório com os seus submódulos, porque ele traz um
cliente ClickHouse incorporado:

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

Copie o `vsql_stat_ch.veb` resultante para o diretório indicado pela variável
de sistema `veb_dir` e, em seguida, instale-o:

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

Confirme que ele está lá:

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

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

## O que ela adiciona

Ela adiciona um caminho de captura, um conjunto de configurações e um conjunto
de contadores de status, e nenhuma função SQL.

| Configuração | Padrão | O que controla |
| - | - | - |
| `vsql_stat_ch.enabled` | `OFF` | Se as instruções são capturadas |
| `vsql_stat_ch.transport` | `native` | `native` para a porta 9000, ou `http` para a interface HTTP |
| `vsql_stat_ch.clickhouse_host` | `localhost` | O host do ClickHouse, para o transporte nativo |
| `vsql_stat_ch.clickhouse_port` | `9000` | A sua porta |
| `vsql_stat_ch.clickhouse_url` | vazio | A URL base, para o transporte HTTP |
| `vsql_stat_ch.clickhouse_database` | `default` | O banco de dados de destino |
| `vsql_stat_ch.clickhouse_table` | `events_raw` | A tabela de destino |
| `vsql_stat_ch.clickhouse_user`, `vsql_stat_ch.clickhouse_password` | `default`, vazio | As credenciais |
| `vsql_stat_ch.compression` | `1` | 0 para nenhuma, 1 para LZ4, 2 para zstd |
| `vsql_stat_ch.batch_max` | `10000` | Quantos eventos vão em um lote |
| `vsql_stat_ch.flush_interval_ms` | `1000` | Por quanto tempo um lote parcial espera |
| `vsql_stat_ch.queue_capacity` | `100000` | Quantos eventos podem esperar na memória, no mínimo `1000`; defina-o antes de o primeiro evento ser capturado ou com `SET PERSIST` e uma reinicialização |
| `vsql_stat_ch.statement_max_bytes` | `4096` | Onde o texto da instrução é truncado |
| `vsql_stat_ch.http_timeout_secs` | `10` | O timeout do transporte HTTP |

## Exemplo

Aponte-o para uma instância do ClickHouse e comece a capturar:

```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;
```

Acompanhe o que ele está fazendo pelos contadores de status:

```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     |
+-------------------------------+-------+
```

Um `events_dropped` crescente significa que a fila encheu mais rápido do que
esvaziou, então ou o ClickHouse está lento para responder ou o
`queue_capacity` é pequeno demais para a taxa de instruções.

> [!NOTE]
>
> O texto da instrução é truncado em `statement_max_bytes`, e o texto da
> instrução pode carregar literais dos seus dados. Decida o que a sua tabela
> do ClickHouse pode guardar antes de ativar a captura.

## Veja também

* [Gerenciando extensões](https://villagesql.com/docs/pt-BR/extensions/managing.md) — como as configurações de extensão são lidas e gravadas
* [Capabilities Preview](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities.md) — o que o flag de preview ativa e o que ele promete
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-stat-ch](https://github.com/villagesql/vsql-stat-ch) — código-fonte, o schema de eventos e as limitações conhecidas


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