Referencia de Comandos

Peeka proporciona una serie de potentes comandos de diagnóstico, cada comando se centra en un escenario de diagnóstico específico. Este documento cubre los 14 comandos centrales.

Tabla de Contenidos

Resumen de Comandos
Parámetros Generales
Flujo de Uso de Comandos
1. Flujo de Diagnóstico Estándar
2. Flujo Interactivo TUI
Expresiones Condicionales
Impacto en el Rendimiento
Siguientes Pasos

Resumen de Comandos

Comando	Función	Escenario de Aplicación
attach	Adjuntar al proceso objetivo	Primer paso para todos los escenarios
watch	Observar llamadas a funciones	Ver parámetros, valores de retorno, tiempo de ejecución
trace	Rastrear cadena de llamadas	Analizar relación de llamadas de funciones y distribución de tiempo consumido
stack	Rastrear pila de llamadas	Rastrear quién llamó a la función
monitor	Estadísticas de rendimiento	Monitorear en tiempo real métricas de rendimiento de funciones
logger	Gestión de registros	Ajustar dinámicamente el nivel de registro
memory	Análisis de memoria	Analizar uso de memoria y fugas
inspect	Inspección de objetos	Inspeccionar atributos de objetos en tiempo de ejecución
search	Buscar clases y métodos (sc/sm)	Exploración y descubrimiento de código
thread	Análisis de hilos	Enumerar hilos y ver pila de hilos
top	Muestreo de rendimiento de funciones	Análisis de puntos calientes de rendimiento a nivel de función
detach	Desconectar conexión	Salir de forma segura de la sesión de diagnóstico
reset	Restablecer inyección	Restaurar funciones observadas
run	Iniciar y adjuntar	Iniciar un programa Python y entrar automáticamente en una sesión de diagnóstico

Parámetros Generales

Todos los comandos comparten el siguiente formato de parámetros:

Formato de Pattern

Patrón para especificar la función objetivo:

# Método de clase
module.ClassName.method_name

# Función de módulo
module.function_name

# Soporta comodines
module.ClassName.*
module.*
*.method_name

Formato de Salida

Todos los comandos generan salida en formato JSONL (JSON Lines), un objeto JSON por línea:

{"type":"status","level":"info","message":"..."}
{"type":"success","command":"attach","data":{...}}
{"type":"observation","watch_id":"...","data":{...}}

Tipos de Mensaje

Tipo	Descripción
`status`	Información de estado (no crítica)
`success`	Comando exitoso
`error`	Comando falló
`event`	Evento de control (started, stopped)
`observation`	Datos de observación
`result`	Resultado de consulta

Flujo de Uso de Comandos

Flujo de Diagnóstico Estándar

# 1. Adjuntar al proceso
peeka-cli attach <pid>

# 2. Usar comando de diagnóstico específico
peeka-cli watch "module.func"

# 3. Analizar resultados
peeka-cli watch "module.func" | jq 'select(.type == "observation")'

# 4. (Opcional) Restablecer inyección
peeka-cli reset "module.func"

Flujo Interactivo TUI

# Iniciar TUI
peeka

# Usa teclas numéricas para cambiar de vista
# 1 - Panel Dashboard
# 2 - Vista Watch de observación
# 3 - Vista Trace de rastreo
# 4 - Vista Stack de pila de llamadas
# 5 - Vista Monitor de monitoreo de rendimiento
# 6 - Vista Memory de análisis de memoria
# 7 - Vista Logger de gestión de registros
# 8 - Vista Inspect de inspección de objetos
# 9 - Vista Threads de análisis de hilos
# 0 - Vista Top de puntos calientes de funciones

Para más detalles, consulta Guía de Uso de TUI.

Expresiones Condicionales

Muchos comandos soportan el parámetro --condition, que se usa para filtrar resultados de observación.

Variables Disponibles

Variable	Descripción	Tipo
`params`	Lista de parámetros de función	list
`kwargs`	Diccionario de parámetros de palabras clave	dict
`returnObj`	Valor de retorno	any
`throwExp`	Objeto de excepción	Exception or None
`cost`	Tiempo de ejecución (milisegundos)	float
`target`	Objeto objetivo (método de instancia)	object

Ejemplos de Condiciones

# Filtrado de parámetros
--condition "params[0] > 100"
--condition "len(params) > 2"
--condition "kwargs.get('debug') == True"

# Filtrado de valor de retorno
--condition "returnObj is not None"
--condition "len(returnObj) > 10"

# Filtrado de tiempo de ejecución
--condition "cost > 100"  # Más de 100ms
--condition "cost > 10 and cost < 100"  # 10-100ms

# Filtrado de excepción
--condition "throwExp is not None"
--condition "type(throwExp).__name__ == 'ValueError'"

# Combinar condiciones
--condition "params[0] > 100 and cost > 50"
--condition "len(params) > 2 or returnObj is None"

Restricciones de Seguridad

La expresión condicional usa la biblioteca simpleeval para evaluación segura, no soporta:

❌ Funciones peligrosas como __import__, eval, exec
❌ Operaciones de archivos (open, read, write)
❌ Operaciones de reflexión (__class__, __subclasses__)
✅ Operaciones aritméticas, comparación, operaciones lógicas
✅ Operaciones de cadenas, indexación de listas
✅ Funciones incorporadas seguras (len, str, int, etc.)

Impacto en el Rendimiento

Comando	Sobrecoste de rendimiento	Descripción
`watch`	< 1%	Inyección de decorador, sobrecoste extremadamente pequeño
`trace`	< 5% (3.12+)	Usa la API sys.monitoring
`trace`	< 20% (3.8.1-3.11)	Usa sys.settrace
`stack`	< 1%	Solo captura pila de llamadas
`monitor`	< 1%	Estadísticas periódicas
`logger`	0%	No afecta el rendimiento
`memory`	Configurable	Depende de la frecuencia de muestreo

Siguientes Pasos

Selecciona el comando que necesitas para ver la documentación detallada:

O consulta Inicio Rápido para conocer el método de uso básico.