Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Logging do DataStore

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)

Querypython
config.set_log_format("simple")
Responsetext
DEBUG - Executing SQL query
DEBUG - Cache miss for key abc123

Formato detalhado

Querypython
config.set_log_format("verbose")
Responsetext
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

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)
Navigation