Skills: Monitoreo y Observabilidad

Después de publicar una Skill, ¿cómo saber si está funcionando bien? ¿Comete errores con frecuencia? ¿Qué pasos son los más lentos?

Este artículo presenta cómo establecer observabilidad para una Skill, comprendiendo el estado de ejecución mediante registros (logs) y métricas.


Las tres dimensiones de la observabilidad

DimensiónPregunta que respondeForma de implementación
Registros (Logs)¿Qué sucedió? ¿Qué salió mal?Archivo de registros JSON estructurado
Métricas (Metrics)¿Cuántas veces se ejecutó? ¿Cuánto tiempo tomó? ¿Cuál es la tasa de éxito?Anexar entradas al archivo de métricas
Traza de ejecución (Trace)¿Qué pasos se ejecutan en cada ejecución? ¿Cuánto tiempo consume cada paso?Registro de marcas de tiempo a nivel de paso

Especificación de salida de registros estructurados

El script de la Skill debe escribir los registros de ejecución en un archivo con una ruta fija para facilitar su consulta posterior.

Ejemplo

# Ruta del archivo: scripts/skill_logger.py
import json
import os
import sys
from datetime import datetime, timezone

LOG_FILE = "/home/claude/skill_run.log"

def log(level: str, event: str, skill: str = "", **context):
    """
Escribir una entrada de registro estructurado

Parámetros:
level: Nivel de registro (info / warning / error)
event: Nombre del evento (snake_case)
skill: Nombre de la Skill
context: Cualquier campo adicional
    """

    entry = {
        "ts":    datetime.now(timezone.utc).isoformat(),
        "level": level,
        "event": event,
        "skill": skill,
        **context
    }
    line = json.dumps(entry, ensure_ascii=False)

    # Se emite simultáneamente a stderr (visible en tiempo real) y al archivo de registro (persistente)
    print(line, file=sys.stderr)
    with open(LOG_FILE, "a", encoding="utf-8") as f:
        f.write(line + "\n")

# Ejemplo de uso
if __name__ == "__main__":
    log("info",    "skill_start",    skill="data-analyzer",
        file="/mnt/user-data/uploads/ejemplo.csv")
    log("info",    "step_complete",  skill="data-analyzer",
        step="clean", rows_removed=3, elapsed_ms=240)
    log("info",    "skill_complete", skill="data-analyzer",
        output="/mnt/user-data/outputs/report.xlsx", elapsed_ms=1830)
    log("error",   "step_failed",    skill="data-analyzer",
        step="generate_chart", error="openpyxl not found")
{"ts": "2026-05-18T10:23:05+00:00", "level": "info",  "event": "skill_start",    "skill": "data-analyzer", "file": "/mnt/user-data/uploads/ejemplo.csv"}
{"ts": "2026-05-18T10:23:05+00:00", "level": "info",  "event": "step_complete",  "skill": "data-analyzer", "step": "clean", "rows_removed": 3, "elapsed_ms": 240}
{"ts": "2026-05-18T10:23:07+00:00", "level": "info",  "event": "skill_complete", "skill": "data-analyzer", "output": "/mnt/user-data/outputs/report.xlsx", "elapsed_ms": 1830}
{"ts": "2026-05-18T10:23:07+00:00", "level": "error", "event": "step_failed",    "skill": "data-analyzer", "step": "generate_chart", "error": "openpyxl not found"}

Agregación de métricas: contar el número de ejecuciones y la tasa de éxito

Extraer métricas clave del archivo de registro para comprender el estado general de funcionamiento de la Skill.

Ejemplo

# Ruta del archivo: scripts/metrics_report.py
# Calcular las métricas de ejecución de la Skill a partir del archivo de registro

import json
import os
from collections import defaultdict

LOG_FILE = "/home/claude/skill_run.log"

def generate_metrics_report(log_file: str) -> dict:
    """Lee el archivo de registro y genera un resumen de métricas"""
    if not os.path.exists(log_file):
        return {"error": f"El archivo de registro no existe: {log_file}"}

    counts  = defaultdict(int)        # Recuento de cada tipo de evento
    errors  = []                       # Registro de errores
    elapsed = []                       # Lista de tiempos de ejecución (ms)

    with open(log_file, encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            try:
                entry = json.loads(line)
            except json.JSONDecodeError:
                continue

            event = entry.get("event", "")
            counts[event] += 1

            if entry.get("level") == "error":
                errors.append({
                    "ts":    entry.get("ts"),
                    "event": event,
                    "error": entry.get("error", ""),
                    "step":  entry.get("step", "")
                })

            if event == "skill_complete" and "elapsed_ms" in entry:
                elapsed.append(entry["elapsed_ms"])

    total_runs   = counts.get("skill_start", 0)
    total_errors = len(errors)
    success_rate = round((total_runs - total_errors) / total_runs * 100, 1) \
                   if total_runs > 0 else 0

    return {
        "total_runs":    total_runs,
        "total_errors":  total_errors,
        "success_rate":  f"{success_rate}%",
        "avg_elapsed_ms": round(sum(elapsed) / len(elapsed)) if elapsed else 0,
        "recent_errors": errors[-5:]   # Últimos 5 errores
    }

if __name__ == "__main__":
    report = generate_metrics_report(LOG_FILE)
    print(json.dumps(report, ensure_ascii=False, indent=2))
{
  "total_runs":     42,
  "total_errors":   3,
  "success_rate":   "92.9%",
  "avg_elapsed_ms": 1650,
  "recent_errors": [
    {"ts": "2026-05-18T09:12:00+00:00", "event": "step_failed", "step": "generate_chart", "error": "openpyxl not found"}
  ]
}

Traza de ejecución: registrar el tiempo consumido en cada paso

Cuando una ejecución es especialmente lenta, el registro de tiempos a nivel de paso permite localizar rápidamente el cuello de botella.

Ejemplo

# Ruta del archivo: scripts/tracer.py
import time
import json
import sys
from skill_logger import log

class ExecutionTracer:
    """Registra el tiempo consumido por cada paso en una ejecución de Skill"""

    def __init__(self, skill_name: str):
        self.skill_name = skill_name
        self.steps      = []
        self.start_time = time.perf_counter()

    def step(self, step_name: str):
        """Marca el inicio de un paso y registra automáticamente el tiempo del paso anterior"""
        now = time.perf_counter()
        if self.steps:
            # Calcular el tiempo del paso anterior
            self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
            del self.steps[-1]["_start"]

        self.steps.append({"name": step_name, "_start": now})
        log("info", "step_start", skill=self.skill_name, step=step_name)

    def finish(self):
        """Marca el final de la ejecución y genera el informe de traza completo"""
        now = time.perf_counter()
        if self.steps:
            self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
            del self.steps[-1]["_start"]

        total_ms = int((now - self.start_time) * 1000)
        report   = {"skill": self.skill_name,
                    "total_ms": total_ms, "steps": self.steps}

        log("info", "trace_complete", skill=self.skill_name,
            total_ms=total_ms, steps=self.steps)
        return report

# Ejemplo de uso
if __name__ == "__main__":
    tracer = ExecutionTracer("data-analyzer")

    tracer.step("Leer archivo")
    time.sleep(0.3)   # Simular operación que consume tiempo

    tracer.step("Limpieza de datos")
    time.sleep(0.1)

    tracer.step("Generar informe")
    time.sleep(0.8)

    report = tracer.finish()
    print(json.dumps(report, ensure_ascii=False, indent=2))
{
  "skill": "data-analyzer",
  "total_ms": 1203,
  "steps": [
    {"name": "读取文件",  "elapsed_ms": 312},
    {"name": "数据清洗",  "elapsed_ms": 108},
    {"name": "生成报告",  "elapsed_ms": 783}
  ]
}

La observabilidad no es algo que solo necesiten los sistemas a gran escala. Incluso para una Skill de uso personal, un archivo de registro claro a menudo puede reducir el tiempo de diagnóstico de varias horas a unos minutos.

Otras extensiones