Logging do DataStore

Configurar o logging do DataStore para depuração e monitoramento

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)