콘텐츠로 이동

프롬프트 및 요청 로깅: 설계 기록

이 문서는 Continuum Router가 요청 및 응답 내용에 대해 기록하는 것과, 옵트인 방식 프롬프트 로깅 기능(에픽 #2294, 이슈 #2301, #2309, #2324, #2328, #2333)의 설계를 기록합니다. 설계 기록으로 남겨 두며 실제로 출시된 내용을 설명합니다. 기능을 켜고 운영하는 방법은 운영 가이드 프롬프트 로깅을 참고하십시오.

기본값인 꺼짐 상태에서는 로그 줄, tracing 스팬, 사용량 레코드 어디에도 프롬프트나 응답 텍스트가 담기지 않습니다.

현재 라우터가 기록하는 것

  • 프로세스 로그와 tracing 스팬: 메타데이터만 기록합니다. 로그 줄에는 엔드포인트, 백엔드, 모델, 상태, 지연 시간이 담깁니다. 로깅 미들웨어는 credential 헤더(authorization, x-api-key, x-goog-api-key, proxy-authorization, 쿠키, WebSocket 서브프로토콜 토큰) denylist를 trace 레벨에서 마스킹하며, 프롬프트나 응답 텍스트는 로그 줄에 기록되지 않습니다.
  • 사용량 원장: 요청별 토큰 수, 모델, 백엔드, 결과, 지연 시간입니다. 충돌 복구를 위한 선행 기록 시도 로그도 동일한 귀속 정보를 기록합니다. 프롬프트나 응답 텍스트는 기록되지 않습니다.
  • 거부 로그: 로그 지점, 거부 사유, 모델별로 속도 제한된 줄 하나입니다. 내용은 담기지 않습니다.
  • 허브(컨트롤 플레인): 원장이 푸시하는 사용량 레코드(계수와 귀속 정보)를 받으며, 텍스트는 받지 않습니다. 레코드 스키마에는 내용을 담을 필드가 없습니다.

일부 기능은 요청 처리에 필요하기 때문에 내용을 저장하거나 전송합니다. 이 기능들은 옵트인이며 요청 로그가 아닙니다.

  • 응답 캐시: 캐시된 응답을 메모리에 저장하며, response_cache.backend가 redis 또는 tiered이면 Redis나 Valkey에 저장합니다.
  • 시맨틱 캐시: 마지막 사용자 메시지를 설정된 임베딩 모델로 전송합니다.
  • Files 및 Batch API: 업로드된 파일과 배치 입력·출력을 삭제되거나 만료될 때까지 저장합니다.

남은 작업

캡처, 동의, 마스킹, 보존, 내보내기는 출시되었습니다. 다음 항목은 아직 출시되지 않았으며, 이를 대신하는 라우터 설정도 없습니다.

설계와 출시 내용

  • 설정 표면 (#2301, 출시): 옵트인 방식의 prompt_logging 섹션입니다. 기본값은 없음 또는 비활성화이며, 이때의 동작은 위에서 설명한 메타데이터 전용 기록과 정확히 같습니다. 모든 retention 한도는 1 이상이어야 하므로 보존은 항상 유한합니다.
  • 캡처 (#2320, 출시): 요청 경로는 기록하기 전에 각 캡처 레코드를 마스킹 처리(#2309)에 통과시키며, fail-open으로 동작해 캡처 오류가 요청을 실패시키지 않습니다. 대상은 POST /v1/chat/completions(A2A 브리지 포함), POST /v1/responses, POST /anthropic/v1/messages입니다. /v1/completions, 임베딩, ACP는 캡처하지 않으며, 응답 캐시 적중은 레코드를 쓰지 않습니다. 설계에서는 API 키 또는 팀 단위 동의를 허용했지만 실제로는 키 단위 동의만 있습니다. 라우터는 KeyEntry.prompt_logging_consent를 읽고 prompt_logging_consent_v1을 광고하며 이 값을 영속 키 테이블에 저장하고, 팀의 동의를 지정하는 prompt_logging 필드는 없습니다.
  • 동의 게이트 (#2324, 출시): 캡처는 요청마다 게이트를 호출합니다. enabled: false이면 키의 allowed까지 포함해 아무것도 캡처하지 않습니다. 그 밖의 경우 denied는 캡처하지 않고, allowed는 default_consent: denied에서도 캡처하며, 값이 없는 키와 키 없는 요청은 default_consent를 따릅니다. 허브 정책 저장소가 있지만 정책이 없는 동안(첫 동기화 전, 또는 복원한 키 테이블이 만료된 뒤)에는 키의 동의를 알 수 없으므로, 키로 인증한 요청은 default_consent와 상관없이 캡처하지 않습니다. 키 없는 요청은 그대로 default_consent를 따릅니다. 허브 정책 저장소가 없는 배포는 이 구간에 해당하지 않으며, 그런 배포에서는 로컬 검증에 실패한 제시 토큰을 default_consent와 관계없이 캡처하지 않으므로(#2879) 알 수 없는 토큰과 삭제·교체·비활성·만료된 키의 토큰은 이 값을 따르지 않습니다. 로컬에 설정한 키는 api_keys[].prompt_logging_consent로 동의를 나타내고(#2819), 값이 없는 키는 default_consent를 따릅니다.
  • 레코드 스키마와 기록기 (#2309, #2320, 출시): directory 아래의 크기 순환 JSONL 파일이며, 레코드 256개 크기의 큐 뒤에서 전용 스레드 하나가 씁니다. 스키마는 사용량 원장이 기록하는 귀속 정보에 마스킹 후의 캡처된 프롬프트와 응답 텍스트를 더해 담습니다. 스키마 버전 2에서는 선택 필드 consent(key_allowed 또는 deployment_default)를 추가했고, 하위 호환 방식으로 truncated 목록도 추가했습니다. 동의 게이트가 거부한 요청은 레코드를 쓰지 않고, 입력 가드레일이 거부한 요청은 프롬프트만 있고 응답이 없는 refused 레코드를 씁니다.
  • 보존 (#2301, 출시): prompt_logging 섹션이 로컬 파일을 크기, 파일 수, 기간으로 제한합니다. 기간은 활성 파일을 max_age_days의 8분의 1 시점에 새로 시작하고 파일을 일찍 삭제하는 방식으로 지켜지므로, 기간이 적용되려면 max_files가 9 이상이어야 합니다.
  • 내보내기 (#2328, 출시): 캡처된 레코드는 설정된 싱크(webhook, OTLP 엔드포인트를 쓰는 Langfuse, S3)를 통해서만 라우터 밖으로 나갑니다. 기본 싱크는 없으며, 설정되지 않으면 보존 정책이 정리할 때까지 로컬 순환 파일에 머뭅니다. 싱크마다 저장된 자체 커서로 파일을 읽고, 설정된 패턴으로 모든 레코드를 다시 마스킹하며, 메모리에는 크기가 제한된 배치 하나만 둡니다. 실패한 배치는 디스크에 남겨 백오프로 재시도합니다. 세 싱크 모두 운영자가 내부 수집기를 허용하지 않는 한 사설·루프백·링크 로컬·메타데이터 주소의 엔드포인트를 거부하며, 어느 싱크도 리다이렉트를 따라가지 않습니다. 새 싱크는 backfill: true를 지정하지 않으면 시작 후에 기록된 레코드만 내보냅니다. 전달은 최소 한 번 보장입니다. webhook이나 S3가 거부하면 재시도하며 원인을 고칠 때까지 그 싱크가 멈추고, Langfuse가 거부했다고 보고한 스팬은 건너뜁니다. 자세한 내용은 내보내기 싱크를 참고하세요.
  • 허브 푸시 (#2764, 출시): export.hub_push는 control-plane 빌드에서 control_plane.policy.enabled가 켜져 있을 때, 등록 자격 증명으로 POST /api/agent/v1/prompt-logs에 보내는 내보내기 루프의 작업 하나를 더 실행합니다. 설계는 레코드의 동의 필드로 푸시를 제어하려 했지만, 출시된 규칙은 더 엄격합니다. 레코드는 키가 허브의 키 테이블에 allowed로 있고, default_consent가 아니라 그 allowed를 근거로 캡처되었으며, 로컬 denied가 이를 덮지 않을 때만 나갑니다. 허브는 테이블이 허용하지 않는 키가 하나라도 있으면 배치 전체를 거부하고, 로컬 운영자의 allowed는 테넌트의 동의가 아니기 때문입니다. 새 커서는 백필 없이 파일 끝에서 시작하고, 각 본문은 64 KiB로 자르며, 요청 하나는 등록 설정의 prompt_log_batch_max_records와 16 MiB의 인코딩된 JSON을 넘지 않습니다. 404는 밀린 레코드를 버리고 끝으로 이동하며, 413은 요청을 버리고, 400, 403, 409는 레코드별로 다시 보내며, 나머지는 백오프로 재시도합니다. 설계의 로컬 보존 규칙(파일을 배달 버퍼로만 쓰고 푸시 후 삭제)은 구현하지 않았습니다. 파일은 모든 싱크의 커서가 공유하며 retention이 제한합니다. 자세한 내용은 허브 푸시를 참고하십시오.
  • 허브 열람 (계획): 허브는 푸시된 레코드를 사용량 레코드와 분리해 저장하며(continuum-hub#1622, 출시), 기본적으로 마스킹되고 감사 기록이 남는 원문 보기를 갖춘 요청별 화면에 표시할 예정입니다(continuum-hub#1623). 사용량 레코드는 계속 메타데이터 전용입니다.