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 detalhadoFormato do log
Formato simples (padrão)
config.set_log_format("simple")DEBUG - Executing SQL query
DEBUG - Cache miss for key abc123Formato detalhado
config.set_log_format("verbose")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 abc123O 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/mydbNí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 stringNí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 floatConfiguraçã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 cityDepurar 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 cacheSolucione 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.345msConfiguraçã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=verboseimport 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) |