Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.

Depurar una solicitud

Loom etiqueta todo lo que hace una solicitud con el mismo id, por lo que rastrear una solicitud es un join. Esta página sigue una solicitud desde los encabezados de su respuesta hasta el componente que decidió la respuesta. Cuando el despliegue en sí no está sano, empieza por solución de problemas; cuando un worker no se ha ejecutado, consulta estado de los workers.

flowchart TD
    A["Response headers<br/>X-Request-Id, X-Trace-Id, Server-Timing"] --> B["loom.agent_events<br/>request_id"]
    B --> C["system.query_log<br/>log_comment = 'op request_id'"]
    B --> D["default.otel_traces<br/>loom.request_id"]
    B --> E["Langfuse trace metadata<br/>request_id"]
    B --> F["loom.audit_log<br/>writes only"]
    G["memory.search explain=true<br/>per-component scores"] -.-> B

1. Captura los ids de la solicitud

Cada respuesta HTTP incluye:

Header Significado
X-Request-Id El id de la solicitud. Envía el tuyo (de 1 a 64 letras, dígitos, ., _ o -) y Loom lo devuelve igual, de modo que tu log y las filas de Loom comparten una misma clave; cualquier otro valor se sustituye por un id generado.
X-Trace-Id El id de traza de OpenTelemetry del árbol de spans de la solicitud.
Server-Timing app (tiempo del handler) y ch (tiempo de ClickHouse, número de sentencias, bytes leídos) cuando la solicitud tiene éxito.
X-Loom-Hint, X-Loom-Hint-Code La sugerencia del mentor para esta llamada, cuando la hay; los SDKs la registran en el log.
curl -si "$LOOM_BASE_URL/v1/memory.search" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' -H 'X-Request-Id: dbg-0001' \
  -d '{"org":"acme","namespace":"support","agent":"bot","query":"refund window"}' \
  | grep -iE '^(x-request-id|x-trace-id|server-timing)'

Server-Timing suele responder a la pregunta "por qué fue lenta". Una duración o un número de bytes de ch elevados apuntan a la consulta. Un app alto con un ch bajo apunta a una llamada a un proveedor (embedding, rerank, LLM).

2. Unir la solicitud entre sistemas

El mismo id está en loom.agent_events.request_id, en los metadatos del trace de Langfuse y en el atributo de span loom.request_id de default.otel_traces.

-- the ledger row: operation, identity, latency, success, error_code, tokens, cost, model
SELECT * FROM loom.agent_events WHERE request_id = 'dbg-0001';

-- every ClickHouse statement the request issued
SELECT query_duration_ms, read_rows, read_bytes, substring(query, 1, 200) AS q
FROM system.query_log
WHERE type = 'QueryFinish' AND log_comment LIKE '% dbg-0001%'
ORDER BY event_time_microseconds;

-- its spans
SELECT SpanName, Duration, SpanAttributes['loom.operation'] AS op
FROM default.otel_traces
WHERE SpanAttributes['loom.request_id'] = 'dbg-0001'
ORDER BY Timestamp;

Las etiquetas de log_comment se enumeran en atribución de consultas. Los spans van a default.otel_traces (en LOOM_CLICKSTACK_DATABASE cuando está definida) cuando LOOM_OTEL_EXPORTER se resuelve como ch, o al endpoint OTLP. Si Langfuse está configurado, también van a Langfuse.

Nota: el ledger nunca almacena el texto de las consultas. loom.agent_events reemplaza cada argumento de texto libre con una forma sha256:<16 hex>/<length>. Para ver qué se preguntó, usa el registro de trazas de búsqueda que aparece más abajo o el registro de tu propio cliente.

3. Explicar una respuesta de búsqueda

¿Por qué quedó en esta posición? memory.search con explain=true adjunta score_components a cada resultado devuelto: las señales de ranking y, tras un reranker, su desplazamiento (rerank_from, rerank_pos, rerank_delta) y, cuando el reranker cambió el orden, su propia puntuación fusionada (rank_score_pre_rerank). Una fila que bajó de posición porque cambió el código enlazado lleva los lugares que descendió (code_changed_places).

out = await agent.call("memory.search", {"query": "refund window", "explain": True})
for h in out["results"]:
    c = h["score_components"]
    print(
        h["memory_key"],
        h["similarity"],
        h["rank_score"],
        c.get("rerank_from"),
        c.get("rank_score_pre_rerank"),
    )

memory.search_trace recibe los argumentos de memory.search y puntúa únicamente la rama vectorial (sin fusión, ensamblado ni reranker), y devuelve, por cada resultado, similarity, distance, entity_boost, rank_score, rank y source.

¿Por qué se abstuvo? Lee la propia respuesta de memory.search:

Campo Qué te indica
abstain, abstain_code Qué umbral se activó: no_match, below_threshold, entity_absent, low_calibrated_confidence, page_expired.
retrieval_risk, retrieval_confidence Qué tan lejos está el mejor resultado de los umbrales.
calibration_explanation Qué umbrales de similitud estaban en vigor (calibrados a partir del embedder, o los valores escalares de respaldo).
degraded Proveedores que recurrieron a un respaldo en esta lectura, y qué hizo la respuesta en su lugar.
pending_extraction Lotes diferidos de set_from_messages que aún no se han extraído; si es mayor que 0, una respuesta vacía no prueba la ausencia.
namespaces_searched, candidates_total Si la búsqueda llegó a los espacios de nombres y las filas que esperabas.

calibration.get muestra los umbrales vigentes para un espacio de nombres y qué nivel (espacio de nombres, clúster, escalar) los produjo. Recuperación y ranking explica cada término.

¿Qué buscó un agente a lo largo del tiempo? Requiere LOOM_SEARCH_TRACE_LOG_ENABLED=true (desactivado por defecto). memory.search_trace_log(since_hours=, agent=, run_id=) devuelve una fila por búsqueda: returned_keys, returned_scores, abstain, retrieval_risk, latency_ms, y el query cuando LOOM_LANGFUSE_CAPTURE_IO_LEVEL no es off (su valor por defecto es off, así que por defecto las filas incluyen claves y puntuaciones, pero no la pregunta).

4. Explicar una escritura

  • La respuesta propia de la escritura. memory.set devuelve status, conflict_verdict, peers, duplicate_of, merged_into_key, noop y advisories. Una escritura que "desapareció" normalmente se fusionó con una coincidencia canónica o se marcó como duplicada. advisories señala un valor con doble codificación o de tamaño excesivo.
  • Su historial. memory.history lista las versiones de una clave desde loom.memory_versions. memory.provenance indica quién la escribió, desde qué fuente, sesión y ejecución.
  • Lo que descartó la extracción. memory.extraction_status lista los lotes diferidos de set_from_messages (pending, failed). loom drops --namespace <ns> imprime lo que el pipeline descartó, truncó o abandonó, por etapa y motivo (descartes de ingesta de memoria). Una respuesta de set_from_messages incluye pipeline_errors y stage_ms por paso (pipeline de extracción).
  • El registro de auditoría. audit.list(event_type=, since=) lee loom.audit_log: quién cambió qué, con un hash del contenido por fila. Toda escritura que crea o modifica memoria deja una fila con solo el hash (auditoría).
  • La vista de una ejecución. run.get(run_id) devuelve lo que una ejecución recuperó (recalled_keys), lo que escribió, sus turnos y su costo (traza y reanudación).

Relacionado