Logging do DataStore - ClickHouse Documentation

O DataStore usa o módulo de logging padrão do Python. Este guia mostra como configurar o logging para depuração.

Início rápido

from pathlib import Path
Path("data.csv").write_text("""\
name,age,city,salary,department
Alice,25,NYC,55000,Engineering
Bob,30,LA,65000,Product
Charlie,35,NYC,80000,Engineering
Diana,28,SF,70000,Design
Eve,42,NYC,95000,Product
""")

from chdb import datastore as pd
from chdb.datastore.config import config

# Habilitar logging de depuração
config.enable_debug()

# Agora todas as operações vão registrar detalhes
ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).to_df()

Níveis de log

Nível	Valor	Descrição
`DEBUG`	10	Informações detalhadas para depuração
`INFO`	20	Informações gerais de operação
`WARNING`	30	Mensagens de aviso (padrão)
`ERROR`	40	Mensagens de erro
`CRITICAL`	50	Falhas críticas

Definindo o nível de log

import logging
from chdb.datastore.config import config

# Usando níveis de logging padrão
config.set_log_level(logging.DEBUG)
config.set_log_level(logging.INFO)
config.set_log_level(logging.WARNING)  # Padrão
config.set_log_level(logging.ERROR)

# Usando predefinição rápida
config.enable_debug()  # Define o nível DEBUG + formato detalhado

Formato do log

Formato simples (padrão)

Query

config.set_log_format("simple")

Response

DEBUG - Executing SQL query
DEBUG - Cache miss for key abc123

Formato detalhado

Query

config.set_log_format("verbose")

Response

2024-01-15 10:30:45.123 DEBUG datastore.core - Executing SQL query
2024-01-15 10:30:45.456 DEBUG datastore.cache - Cache miss for key abc123

O que é registrado nos logs

Nível DEBUG

Consultas SQL geradas
Seleção do mecanismo de execução
Operações de cache (acertos/falhas)
Tempos das operações
Informações sobre a fonte de dados

DEBUG - Creating DataStore from file 'data.csv'
DEBUG - SQL: SELECT * FROM file('data.csv', 'CSVWithNames') WHERE age > 25
DEBUG - Using engine: chdb
DEBUG - Execution time: 0.089s
DEBUG - Cache: Storing result (key: abc123)

Nível INFO

Conclusão de operações importantes
Alterações de configuração
Conexões com fontes de dados

INFO - Loaded 1,000,000 rows from data.csv
INFO - Execution engine set to: chdb
INFO - Connected to MySQL: localhost:3306/mydb

Nível WARNING

Uso de funcionalidade obsoleta
Avisos de desempenho
Problemas não críticos

WARNING - Large result set (>1M rows) may cause memory issues
WARNING - Cache TTL exceeded, re-executing query
WARNING - Column 'date' has mixed types, using string

Nível ERROR

Falhas na execução de consultas
Erros de conexão
Erros de conversão de dados

ERROR - Failed to execute SQL: syntax error near 'FORM'
ERROR - Connection to MySQL failed: timeout
ERROR - Cannot convert column 'price' to float

Configuração personalizada do logging

Usando o logging do Python

import logging

# Configurar o root logger
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('datastore.log'),
        logging.StreamHandler()
    ]
)

# Obter o logger do DataStore
ds_logger = logging.getLogger('chdb.datastore')
ds_logger.setLevel(logging.DEBUG)

Registrar em um arquivo

import logging

# Criar handler de arquivo
file_handler = logging.FileHandler('datastore_debug.log')
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
))

# Adicionar ao logger do DataStore
ds_logger = logging.getLogger('chdb.datastore')
ds_logger.addHandler(file_handler)

Suprimir logging

import logging

# Suprimir todos os logs do DataStore
logging.getLogger('chdb.datastore').setLevel(logging.CRITICAL)

# Ou usando config
config.set_log_level(logging.CRITICAL)

Cenários de depuração

Depuração da geração de SQL

config.enable_debug()

ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').sum()

Saída do log:

DEBUG - Creating DataStore from file 'data.csv'
DEBUG - Building filter: age > 25
DEBUG - Building groupby: city
DEBUG - Building aggregation: sum
DEBUG - Generated SQL:
        SELECT city, SUM(*) 
        FROM file('data.csv', 'CSVWithNames')
        WHERE age > 25
        GROUP BY city

Depurar a escolha do mecanismo

config.enable_debug()

result = ds.filter(ds['x'] > 10).apply(custom_func)

Saída de log:

DEBUG - filter: selecting engine (eligible: chdb, pandas)
DEBUG - filter: using chdb (SQL-compatible)
DEBUG - apply: selecting engine (eligible: pandas)
DEBUG - apply: using pandas (custom function)

Depurar operações de cache

config.enable_debug()

# Primeira execução
result1 = ds.filter(ds['age'] > 25).to_df()
# DEBUG - Cache miss para hash de consulta abc123
# DEBUG - Executando consulta...
# DEBUG - Armazenando resultado em cache (key: abc123, size: 1.2MB)

# Segunda execução (mesma consulta)
result2 = ds.filter(ds['age'] > 25).to_df()
# DEBUG - Cache hit para hash de consulta abc123
# DEBUG - Retornando resultado em cache

Solucione problemas de desempenho

config.enable_debug()
config.enable_profiling()

# Os logs mostrarão o tempo de cada operação
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('region')
    .agg({'amount': 'sum'})
    .to_df()
)

Saída do Log:

DEBUG - filter: 0.002ms
DEBUG - groupby: 0.001ms
DEBUG - agg: 0.003ms
DEBUG - SQL generation: 0.012ms
DEBUG - SQL execution: 89.456ms  <- Principal tempo gasto aqui
DEBUG - Result conversion: 2.345ms

Configuração para produção

Configurações recomendadas

import logging
from chdb.datastore.config import config

# Produção: logging mínimo
config.set_log_level(logging.WARNING)
config.set_log_format("simple")
config.set_profiling_enabled(False)

Rotação de logs

import logging
from logging.handlers import RotatingFileHandler

# Criar handler de arquivo rotativo
handler = RotatingFileHandler(
    'datastore.log',
    maxBytes=10*1024*1024,  # 10MB
    backupCount=5
)
handler.setLevel(logging.WARNING)

# Adicionar ao logger do DataStore
logging.getLogger('chdb.datastore').addHandler(handler)

Variáveis de ambiente

Você também pode configurar o logging por meio de variáveis de ambiente:

# Definir nível de log
export CHDB_LOG_LEVEL=DEBUG

# Definir formato de log
export CHDB_LOG_FORMAT=verbose

import os
import logging

# Lê da variável de ambiente
log_level = os.environ.get('CHDB_LOG_LEVEL', 'WARNING')
config.set_log_level(getattr(logging, log_level))

Resumo

Tarefa	Comando
Ativar depuração	`config.enable_debug()`
Definir nível	`config.set_log_level(logging.DEBUG)`
Definir formato	`config.set_log_format("verbose")`
Gravar em arquivo	Usar handlers de logging do Python
Suprimir logs	`config.set_log_level(logging.CRITICAL)`

​Início rápido

​Níveis de log

​Definindo o nível de log

​Formato do log

​Formato simples (padrão)

​Formato detalhado

​O que é registrado nos logs

​Nível DEBUG

​Nível INFO

​Nível WARNING

​Nível ERROR

​Configuração personalizada do logging

​Usando o logging do Python

​Registrar em um arquivo

​Suprimir logging

​Cenários de depuração

​Depuração da geração de SQL

​Depurar a escolha do mecanismo

​Depurar operações de cache

​Solucione problemas de desempenho

​Configuração para produção

​Configurações recomendadas

​Rotação de logs

​Variáveis de ambiente

​Resumo