Registro Estructurado de Prompts, Respuestas y Conteo de Tokens

Un registro estructurado es un registro consistente y analizable por máquina de una llamada a la API de Claude: el prompt, la respuesta, los conteos de tokens, el modelo, la latencia y un ID de solicitud.

Sin esa consistencia, cada sitio de llamada registra algo ligeramente diferente, y responder "¿cuántos tokens usamos ayer?" se convierte en buscar en texto inconsistente en lugar de ejecutar una consulta.

Resumen

El objetivo del registro estructurado es un esquema fijo aplicado a cada llamada, no un mensaje de registro de mejor esfuerzo.

Cada campo del esquema se gana su lugar: el prompt y la respuesta para depurar problemas de calidad, los conteos de tokens para el costo, la latencia para el rendimiento, el nombre del modelo para comparar entre versiones del modelo y un ID de solicitud para correlacionar con rastreos o tickets de soporte.

Un logging.Logger de Python con un formateador JSON, o una función adaptadora de registro dedicada, es suficiente para aplicar esto sin adoptar un nuevo framework.

El patrón se generaliza más allá de una sola llamada a messages.create: las respuestas en streaming, las conversaciones de múltiples turnos y los bucles de agentes que usan herramientas necesitan el mismo esquema aplicado por llamada, no por conversación.

Esta página crea un adaptador de registro reutilizable, y luego lo extiende a casos de múltiples turnos y streaming.

Receta

import json
import logging
import time
import uuid
 
logger = logging.getLogger("claude.calls")
 
def log_call(*, request_id, model, prompt, response_text, usage, latency_ms, status="ok"):
    logger.info(json.dumps({
        "request_id": request_id,
        "model": model,
        "prompt": prompt,
        "response": response_text,
        "input_tokens": usage.input_tokens,
        "output_tokens": usage.output_tokens,
        "latency_ms": latency_ms,
        "status": status,
    }))

Cuándo usar esto:

• Tienes más de un sitio de llamada realizando llamadas a la API de Claude y deseas un formato de registro consistente y consultable.
• Necesitas responder "¿cuántos tokens usó esta característica la semana pasada?" desde los registros, no volviendo a ejecutar las solicitudes.
• Estás a punto de agregar paneles de rastreo o costos, ambos dependen de que este esquema exista primero.
• Quieres registros de errores y éxitos con la misma forma para que una sola consulta cubra ambos.

Ejemplo de Trabajo

import json
import logging
import time
import uuid
 
import anthropic
 
logging.basicConfig(level=logging.INFO, format="%(message)s")
logger = logging.getLogger("claude.calls")
 
client = anthropic.Anthropic()
 
 
def log_entry(**fields) -> None:
    """Emite una línea de registro JSON estructurada, omitiendo cualquier campo que sea None."""
    logger.info(json.dumps({k: v for k, v in fields.items() if v is not None}))
 
 
def call_claude(prompt: str, model: str = "claude-sonnet-5") -> str:
    """Realiza una llamada a Claude y registra una entrada estructurada para ella, éxito o fracaso."""
    request_id = str(uuid.uuid4())
    start = time.monotonic()
 
    try:
        response = client.messages.create(
            model=model,
            max_tokens=500,
            messages=[{"role": "user", "content": prompt}],
        )
    except anthropic.APIStatusError as exc:
        log_entry(
            request_id=request_id,
            model=model,
            prompt=prompt,
            response=None,
            input_tokens=None,
            output_tokens=None,
            latency_ms=round((time.monotonic() - start) * 1000, 1),
            status="error",
            error_type=exc.__class__.__name__,
            status_code=exc.status_code,
        )
        raise
 
    response_text = response.content[0].text
    log_entry(
        request_id=request_id,
        model=response.model,
        prompt=prompt,
        response=response_text,
        input_tokens=response.usage.input_tokens,
        output_tokens=response.usage.output_tokens,
        cache_read_input_tokens=getattr(response.usage, "cache_read_input_tokens", None),
        latency_ms=round((time.monotonic() - start) * 1000, 1),
        status="ok",
    )
    return response_text
 
 
def call_claude_multi_turn(messages: list[dict], model: str = "claude-sonnet-5") -> dict:
    """Mismo esquema, aplicado a un turno de una conversación de múltiples turnos."""
    request_id = str(uuid.uuid4())
    start = time.monotonic()
 
    response = client.messages.create(
        model=model,
        max_tokens=500,
        messages=messages,
    )
 
    log_entry(
        request_id=request_id,
        model=response.model,
        prompt=messages[-1]["content"],
        response=response.content[0].text if response.content else "",
        input_tokens=response.usage.input_tokens,
        output_tokens=response.usage.output_tokens,
        latency_ms=round((time.monotonic() - start) * 1000, 1),
        status="ok",
        turn_count=len(messages),
    )
    return {"request_id": request_id, "response": response}
 
 
if __name__ == "__main__":
    call_claude("Summarize the tradeoffs of microservices in two sentences.")

Lo que esto demuestra:

• Una única función log_entry que aplica un esquema, llamada tanto desde las rutas de éxito como de error.
• Omitir los campos None evita que las líneas de registro de errores contengan campos de respuesta/token vacíos engañosos.
• request_id generado antes de la llamada, por lo que existe incluso cuando la llamada falla.
• cache_read_input_tokens capturado con getattr ya que solo está presente una vez que se aplica el almacenamiento en caché del prompt.
• El mismo esquema reutilizado para una llamada de múltiples turnos, con un campo turn_count adicional, que muestra que el esquema se extiende en lugar de reemplazarse por tipo de llamada.

Inmersión Profunda

Cómo Funciona

• El esquema es solo un diccionario de Python serializado a JSON; no se requiere ninguna biblioteca especial, aunque una biblioteca de registro JSON dedicada (python-json-logger, structlog) elimina el código repetitivo manual de json.dumps a escala.
• Centralizar la llamada de registro en una sola función (log_entry) es lo que realmente aplica el esquema; si cada sitio de llamada construye su propio diccionario en línea, los campos se desvían con el tiempo.
• Se utiliza logging.Logger (no print) porque se integra con el filtrado de niveles de registro, manejadores y la mayoría de los agentes de agregación de registros (Datadog Agent, Fluent Bit, CloudWatch Logs agent) listos para usar.
• Las rutas de error y éxito utilizan el mismo conjunto de campos, distinguiéndolos el campo status, por lo que una sola consulta como status:error o una agregación sobre input_tokens funciona independientemente del resultado.

Referencia del Esquema

Notas de Python

• Prefiere logging.Logger sobre print incluso para scripts; no cuesta nada extra y significa que el mismo código funciona sin modificaciones una vez que agregas manejadores para un agregador de registros real.
• Usa logger.info(json.dumps(...)) para una configuración mínima; para servicios de alto rendimiento, una subclase de logging.Formatter que codifica en JSON el LogRecord completo evita la doble serialización y mantiene las trazas de pila intactas en caso de errores.
• Redacta o trunca los campos prompt/response antes de registrar si tu aplicación maneja datos de usuario regulados o sensibles; un esquema estructurado facilita esto, ya que la redacción se convierte en una función, no en una decisión por sitio de llamada.

Trampas Comunes

• Construir el diccionario de registro en línea en cada sitio de llamada. Sin una función log_entry compartida, un sitio de llamada agrega un campo y otro no, y tu esquema se desvía silenciosamente. Solución: centraliza la construcción del registro en una función o una pequeña clase adaptadora de registro.
• Registrar los campos usage antes de verificar si hay una excepción. Si la llamada falla, response nunca se asigna, y hacer referencia a response.usage en un bloque finally genera un error NameError. Solución: calcula los campos de tokens solo dentro de la rama de éxito y registra None para ellos en la ruta de error.
• La falta de cache_read_input_tokens rompe las matemáticas de costos posteriores. Los campos de uso relacionados con el caché no siempre están presentes en el objeto de respuesta dependiendo de la versión del SDK y de si se aplicó el caché. Solución: accédelos con getattr(response.usage, "cache_read_input_tokens", None) en lugar de acceso directo al atributo.
• Registrar el texto completo del prompt/respuesta con un nivel de registro muy alto en producción. Esto puede aumentar drásticamente los costos de almacenamiento de registros y, si los prompts contienen PII del usuario, crea una superficie de cumplimiento que no pretendías. Solución: aplica la redacción/truncamiento antes de registrar y confirma tu política de retención de registros para esta transmisión de acuerdo con tus requisitos de manejo de datos.
• Reutilizar print(json.dumps(...)) en lugar del módulo de registro. Esto omite el filtrado de niveles de registro y la mayoría de los agentes de agregación de registros, que esperan la salida en stdout/stderr a través de un framework de registro o esperan un formato de archivo específico. Solución: siempre enruta a través de logging.Logger, incluso para un script rápido.

Alternativas

Preguntas Frecuentes

try:
    response = client.messages.create(...)
except anthropic.APIStatusError as exc:
    # response nunca fue asignado; registra None para los campos de uso en su lugar
    log_entry(status="error", error_type=exc.__class__.__name__, input_tokens=None)
    raise

Relacionado

• Conceptos Básicos de Observabilidad - la versión más pequeña y de una sola función de este patrón.
• Cómo Funciona la Observabilidad para Aplicaciones LLM - dónde encaja el registro estructurado en relación con el rastreo y la alerta.
• Instrumentación de Bucles de Agente con Rastreo OpenTelemetry - unir estas líneas de registro a tramos de rastreo a través del ID de solicitud.
• Integración de Paneles de Uso y Costos de Claude con Datadog - envío de los campos de tokens de este esquema a un panel de costos.
• Mejores Prácticas de Observabilidad - una lista de verificación consolidada para esta sección.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de modelos, precios y versiones de SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.