Logging de DataStore - ClickHouse Documentation

DataStore usa el módulo estándar logging de Python. En esta guía se muestra cómo configurar el logging para depuración.

Inicio 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 el logging de depuración
config.enable_debug()

# Ahora todas las operaciones registrarán detalles
ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).to_df()

Niveles de log

Nivel	Valor	Descripción
`DEBUG`	10	Información detallada para la depuración
`INFO`	20	Información general de funcionamiento
`WARNING`	30	Mensajes de advertencia (predeterminado)
`ERROR`	40	Mensajes de error
`CRITICAL`	50	Fallos críticos

Configurar el nivel de registro

import logging
from chdb.datastore.config import config

# Usando niveles de registro estándar
config.set_log_level(logging.DEBUG)
config.set_log_level(logging.INFO)
config.set_log_level(logging.WARNING)  # Predeterminado
config.set_log_level(logging.ERROR)

# Usando configuración rápida
config.enable_debug()  # Establece el nivel DEBUG + formato detallado

Formato del log

Formato simple (predeterminado)

Query

config.set_log_format("simple")

Response

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

Formato detallado

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

Qué se registra

Nivel DEBUG

Consultas SQL generadas
Selección del motor de ejecución
Operaciones de caché (aciertos/fallos)
Duración de las operaciones
Información de la fuente de datos

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)

Nivel INFO

Finalización de operaciones importantes
Cambios de configuración
Conexiones a fuentes de datos

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

Nivel WARNING

Uso de funcionalidades obsoletas
Advertencias de rendimiento
Problemas no 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

Nivel ERROR

Fallos en la ejecución de consultas
Errores de conexión
Errores de conversión de datos

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

Configuración personalizada de logging

Uso de logging en Python

import logging

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

# Obtener el logger de DataStore
ds_logger = logging.getLogger('chdb.datastore')
ds_logger.setLevel(logging.DEBUG)

Registrar en un archivo

import logging

# Crear manejador de archivo
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'
))

# Agregar al logger de DataStore
ds_logger = logging.getLogger('chdb.datastore')
ds_logger.addHandler(file_handler)

Deshabilitar el logging

import logging

# Suprimir todos los logs de DataStore
logging.getLogger('chdb.datastore').setLevel(logging.CRITICAL)

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

Escenarios de depuración

Depurar la generación de SQL

config.enable_debug()

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

Salida del 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 la selección del motor

config.enable_debug()

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

Salida del 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)

Depuración de operaciones de caché

config.enable_debug()

# Primera ejecución
result1 = ds.filter(ds['age'] > 25).to_df()
# DEBUG - Fallo de caché para el hash de consulta abc123
# DEBUG - Ejecutando consulta...
# DEBUG - Almacenando resultado en caché (key: abc123, size: 1.2MB)

# Segunda ejecución (misma consulta)
result2 = ds.filter(ds['age'] > 25).to_df()
# DEBUG - Acierto de caché para el hash de consulta abc123
# DEBUG - Devolviendo resultado en caché

Solucionar problemas de rendimiento

config.enable_debug()
config.enable_profiling()

# Los registros mostrarán el tiempo de cada operación
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('region')
    .agg({'amount': 'sum'})
    .to_df()
)

Salida del log:

DEBUG - filter: 0.002ms
DEBUG - groupby: 0.001ms
DEBUG - agg: 0.003ms
DEBUG - SQL generation: 0.012ms
DEBUG - SQL execution: 89.456ms  <- Aquí es donde se concentra el tiempo
DEBUG - Result conversion: 2.345ms

Configuración de producción

Configuración recomendada

import logging
from chdb.datastore.config import config

# Producción: logging mínimo
config.set_log_level(logging.WARNING)
config.set_log_format("simple")
config.set_profiling_enabled(False)

Rotación de logs

import logging
from logging.handlers import RotatingFileHandler

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

# Agregar al logger de DataStore
logging.getLogger('chdb.datastore').addHandler(handler)

Variables de entorno

También puedes configurar el logging mediante variables de entorno:

# Establecer el nivel de log
export CHDB_LOG_LEVEL=DEBUG

# Establecer el formato de log
export CHDB_LOG_FORMAT=verbose

import os
import logging

# Leer desde el entorno
log_level = os.environ.get('CHDB_LOG_LEVEL', 'WARNING')
config.set_log_level(getattr(logging, log_level))

Resumen

Tarea	Comando
Activar depuración	`config.enable_debug()`
Configurar nivel	`config.set_log_level(logging.DEBUG)`
Configurar formato	`config.set_log_format("verbose")`
Registrar en un archivo	Usar controladores de logging de Python
Suprimir logs	`config.set_log_level(logging.CRITICAL)`

​Inicio rápido

​Niveles de log

​Configurar el nivel de registro

​Formato del log

​Formato simple (predeterminado)

​Formato detallado

​Qué se registra

​Nivel DEBUG

​Nivel INFO

​Nivel WARNING

​Nivel ERROR

​Configuración personalizada de logging

​Uso de logging en Python

​Registrar en un archivo

​Deshabilitar el logging

​Escenarios de depuración

​Depurar la generación de SQL

​Depurar la selección del motor

​Depuración de operaciones de caché

​Solucionar problemas de rendimiento

​Configuración de producción

​Configuración recomendada

​Rotación de logs

​Variables de entorno

​Resumen

Inicio rápido

Niveles de log

Configurar el nivel de registro

Formato del log

Formato simple (predeterminado)

Formato detallado

Qué se registra

Nivel DEBUG

Nivel INFO

Nivel WARNING

Nivel ERROR

Configuración personalizada de logging

Uso de logging en Python

Registrar en un archivo

Deshabilitar el logging

Escenarios de depuración

Depurar la generación de SQL

Depurar la selección del motor

Depuración de operaciones de caché

Solucionar problemas de rendimiento

Configuración de producción

Configuración recomendada

Rotación de logs

Variables de entorno

Resumen