본문으로 건너뛰기
ClickHouse Loom
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

요청 디버그

요청 디버그

이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.

Loom은 하나의 요청이 수행하는 모든 작업에 동일한 id를 태깅하므로, 요청을 추적하는 일은 조인(join) 한 번으로 끝납니다. 이 페이지는 응답 헤더에서 시작해 답변을 결정한 컴포넌트까지 하나의 요청을 따라갑니다. 배포 자체가 정상이 아닌 경우에는 문제 해결에서 시작하세요. 워커가 실행되지 않았다면 워커 상태를 참고하세요.

1. 요청의 id 수집하기

모든 HTTP 응답에는 다음 헤더가 포함됩니다.

헤더 의미
X-Request-Id 요청의 id입니다. 직접 id(영문자, 숫자, ., _, - 1~64자)를 보내면 Loom이 그대로 반환하므로, 사용자의 로그와 Loom의 행이 하나의 키를 공유합니다. 그 밖의 값은 생성된 id로 대체됩니다.
X-Trace-Id 요청의 스팬 트리에 대한 OpenTelemetry 트레이스 id입니다.
Server-Timing 성공 시 app(핸들러 시간)과 ch(ClickHouse 시간, 구문 수, 읽은 바이트 수)를 제공합니다.
X-Loom-Hint, X-Loom-Hint-Code 이 호출에 대해 멘토가 제공하는 힌트입니다(있는 경우). SDK가 이를 로그로 남깁니다.
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은 “왜 느렸는가”에 대한 답을 주는 경우가 많습니다. ch의 시간이나 바이트 수가 크면 쿼리가 원인입니다. ch는 작은데 app이 크면 제공자 호출(임베딩, 리랭크, LLM)이 원인입니다.

2. 시스템 간 요청 연결

동일한 id가 loom.agent_events.request_id, Langfuse 트레이스 메타데이터, 그리고 default.otel_traces의 스팬 속성 loom.request_id에 들어 있습니다.

-- 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;

log_comment 태그는 쿼리 귀속에 나와 있습니다. LOOM_OTEL_EXPORTER가 ch로 결정되면 스팬은 default.otel_traces(LOOM_CLICKSTACK_DATABASE가 설정된 경우 해당 데이터베이스)로 전송되며, 그렇지 않으면 OTLP 엔드포인트로 전송됩니다. Langfuse가 구성되어 있으면 스팬은 Langfuse로도 전송됩니다.

참고: 원장은 쿼리 텍스트를 저장하지 않습니다. loom.agent_events는 모든 자유 텍스트 인수를 sha256:<16 hex>/<length> 형태로 대체합니다. 어떤 질문이 있었는지 확인하려면 아래의 검색 트레이스 로그나 사용 중인 클라이언트 로그를 사용하세요.

3. 검색 응답 설명하기

이 결과가 왜 이 순위에 있는가? explain=true로 memory.search를 호출하면 반환된 각 히트에 score_components가 붙습니다. 여기에는 순위 신호가 담기고, 리랭커를 거친 경우 리랭커가 만든 이동(rerank_from, rerank_pos, rerank_delta)이, 리랭커가 순서를 바꾼 경우에는 리랭커 이전의 자체 통합 점수(rank_score_pre_rerank)가 함께 담깁니다. 연결된 코드가 바뀌어 순위가 내려간 행에는 내려간 자리 수(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는 memory.search와 같은 인자를 받아 벡터 단계만 점수를 계산하며(통합, 조립, 리랭커 없음), 히트마다 similarity, distance, entity_boost, rank_score, rank, source를 반환합니다.

왜 답변을 보류했는가? memory.search 응답 자체를 읽어 보세요.

필드 알려 주는 내용
abstain, abstain_code 어떤 게이트가 작동했는지: no_match, below_threshold, entity_absent, low_calibrated_confidence, page_expired.
retrieval_risk, retrieval_confidence 가장 좋은 히트가 게이트에서 얼마나 떨어져 있는지.
calibration_explanation 적용된 유사도 게이트(임베더로 보정한 값 또는 스칼라 대체값).
degraded 이번 읽기에서 대체 동작으로 전환된 프로바이더와, 응답이 대신 수행한 동작.
pending_extraction 아직 추출되지 않은 지연된 set_from_messages 배치. 0보다 크면 빈 응답이 부재의 증거는 아닙니다.
namespaces_searched, candidates_total 검색이 예상한 네임스페이스와 행에 도달했는지.

calibration.get은 네임스페이스에 적용 중인 임계값과, 그 값을 만든 티어(네임스페이스, 클러스터, 스칼라)를 보여 줍니다. 검색과 순위 지정에서 각 용어를 설명합니다.

에이전트가 시간에 따라 무엇을 검색했는가? LOOM_SEARCH_TRACE_LOG_ENABLED=true가 필요합니다(기본값은 꺼짐). memory.search_trace_log(since_hours=, agent=, run_id=)는 검색마다 한 행을 반환합니다: returned_keys, returned_scores, abstain, retrieval_risk, latency_ms, 그리고 LOOM_LANGFUSE_CAPTURE_IO_LEVEL이 off가 아닐 때의 query. 이 값의 기본값은 off이므로 기본 상태에서는 행에 질문 없이 키와 점수만 담깁니다.

4. 쓰기 설명하기

  • 쓰기 자체의 응답. memory.set은 status, conflict_verdict, peers, duplicate_of, merged_into_key, noop, advisories를 반환합니다. “사라진” 쓰기는 대부분 정식(canonical) 일치 항목에 병합되었거나 중복으로 표시된 경우입니다. advisories는 이중 인코딩되었거나 크기가 지나치게 큰 값을 알려 줍니다.
  • 이력. memory.history는 loom.memory_versions에서 키의 버전 목록을 보여 줍니다. memory.provenance는 누가, 어떤 소스, 세션, 실행에서 썼는지 알려 줍니다.
  • 추출 과정에서 누락된 항목. memory.extraction_status는 보류된 set_from_messages 배치(pending, failed)를 나열합니다. loom drops --namespace <ns>는 파이프라인이 버렸거나, 잘라 냈거나, 처리를 포기한 항목을 단계와 사유별로 출력합니다 (메모리 수집 누락 항목). set_from_messages 응답에는 pipeline_errors와 단계별 stage_ms가 포함됩니다 (추출 파이프라인).
  • 감사 추적. audit.list(event_type=, since=)는 loom.audit_log를 읽습니다. 누가 무엇을 변경했는지를 행별 콘텐츠 해시와 함께 보여 줍니다. 메모리를 생성하거나 변경하는 모든 쓰기는 해시만 담은 행을 남깁니다 (감사).
  • 실행 단위 보기. run.get(run_id)는 한 실행이 불러온 항목(recalled_keys), 쓴 항목, 턴, 비용을 반환합니다 (추적 및 재개).

관련 문서

이 페이지가 도움이 되었나요?