관측 가능성
Libre WebUI는 운영자를 위한 두 가지 관측 가능성 경로를 제공합니다.
- 표준 출력과 오류에 로컬로 기록되는 구조화된 애플리케이션 로그
- HTTP 요청, 영구 작업, 카운터와 경고/오류 로그 레코드를 위한 선택적 OpenTelemetry 내보내기
어느 경로도 Libre WebUI 프로젝트로 원격 측정 데이터를 보내지 않습니다. 운영자가 수집기 엔드포인트를 구성할 때까지 OpenTelemetry는 꺼져 있습니다. 관리자의 시스템 및 사용량 페이지는 별개입니다. OpenTelemetry 수집기가 아니라 배포 자체에서 진단 정보와 모델/공급자 사용량을 읽습니다.
구조화된 로그
기본값인 LOG_FORMAT=text는 익숙한 범위 지정 콘솔 출력을 유지합니다. 한 줄에 JSON 객체 하나를 출력하려면 LOG_FORMAT=json을 설정합니다.
LOG_LEVEL=info
LOG_FORMAT=json
구조화된 각 줄에는 다음이 포함됩니다.
- ISO 타임스탬프
- 수준과 로거 범위
- 메시지
- 현재 요청 또는 영구 작업의 상관관계 ID(있는 경우)
- 호출자가 제공한 크기 제한 구조화 세부 정보
모든 HTTP 요청은 X-Request-Id를 받습니다. Libre는 수신 ID가 문자, 숫자, ., _, -로 구성된 8~64자인 경우에만 허용하며 그렇지 않으면 UUID를 생성합니다. ID는 응답으로 반환되고 로깅 컨텍스트를 통해 비동기 작업에도 이어집니다. 접근 로그는 HTTP 메서드, 경로, 상태, 지속 시간을 기록합니다. 쿼리 매개변수에는 사용자 콘텐츠나 수명이 짧은 자격 증명이 포함될 수 있으므로 쿼리 문자열은 제거합니다.
LOG_LEVEL에는 silent, error, warn, info, debug를 사용할 수 있습니다. 디버그 로깅은 더 많은 운영 정보를 노출할 수 있으므로 문제를 진단할 때만 활성화하고 생성된 로그를 다른 배포 데이터처럼 보호하세요.
민감 정보 제거 경계
구조화 세부 정보와 내보낸 원격 측정 데이터는 같은 크기 제한 민감 정보 제거 도우미를 통과합니다.
- 이름이 비밀번호, 비밀 값, 토큰, 키, 권한 부여, 쿠키, 자격 증명, Bearer 값 또는 JWT와 유사한 필드는 생략됩니다.
- 문자열은 512자로 제한됩니다.
- 배열, 중첩 깊이와 내보낸 속성 수가 제한됩니다.
- 오류 객체는 임의 객체 그래프가 아니라 이름과 크기가 제한된 메시지만 유지합니다.
이는 심층 방어이며 프롬프트나 비밀 값을 로깅해도 된다는 허가가 아닙니다. 비밀 값처럼 보이는 필드 이름이 없는 짧은 사용자 제공 문자열은 일반 로그 텍스트가 될 수 있습니다. 애플리케이션 확장은 요청 본문, 프롬프트, 문서 텍스트, 도구 결과 또는 공급자 페이로드 대신 식별자와 결과를 기록해야 합니다. 로그 접근을 제한하고 운영자가 관리하는 보존 정책을 적용하세요.
OpenTelemetry 활성화하기
Libre는 OpenTelemetry SDK 의존성을 추가하지 않고 OTLP/HTTP JSON을 직접 내보냅니다. 표준 신호 경로를 허용하는 수집기의 HTTP Base URL을 지정합니다.
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
내보내기는 Base URL에 /v1/traces, /v1/metrics, /v1/logs를 추가합니다. OTEL_EXPORTER_OTLP_HEADERS는 쉼표로 구분된 key=value 쌍 목록입니다. 수집기 자격 증명은 배포 비밀 값으로 저장하고 커밋하지 마세요. OTEL_SERVICE_NAME의 기본값은 libre-webui입니다.
엔드포인트 변수가 없으면 span, 메트릭, 로그 기록은 아무 작업도 하지 않으며 어떤 데이터도 프로세스 밖으로 나가지 않습니다. 팀 배포에서는 애플리케이션과 외부 워커 프로세스가 독립적으로 내보내므로 각 프로세스에 사용할 수집기 구성을 제공하세요. 역할별로 서비스 이름을 구분하면 대시보드를 더 쉽게 읽을 수 있습니다.
내보내는 신호
| 신호 | Libre가 기록하는 항목 |
|---|---|
| HTTP 서버 span | 쿼리 문자열 없는 메서드와 경로, 응답 상태, 지속 시간, 성공/실패 상태와 요청 ID |
| HTTP 카운터 | 메서드 및 응답 상태 클래스별 단조 증가 요청 수 |
| 영구 작업 span | 작업 유형, 시도 횟수, 지속 시간과 성공/실패 상태 |
| 영구 작업 카운터 | 작업 유형 및 결과별 단조 증가 실행 수 |
| 로그 레코드 | 민감 정보가 제거된 경고 및 오류 메시지, 로거 범위와 요청/작업 상관관계 ID |
span은 로컬에서 완료된 span입니다. 현재 Libre는 들어오는 OpenTelemetry 추적 부모를 전파하거나, 서비스 간 부모/자식 span 트리를 만들거나, 브라우저 렌더링과 모든 공급자 호출을 계측하지 않습니다. 모델 토큰 및 미디어 사용량은 대신 로컬 사용량 분석 및 비용 관리 원장에 속합니다.
전달 동작
원격 측정은 의도적으로 최선형입니다.
- 버퍼는 span 2,048개와 로그 레코드 2,048개를 최대한 보관하며 압력이 높으면 가장 오래된 항목을 버립니다.
- 카운터 시리즈는 최대 512개 유지됩니다.
- 내보내기는 약 5초마다 플러시합니다.
- 각 HTTP 내보내기의 제한 시간은 3초입니다.
- 수집기 오류가 발생하면 해당 배치를 버리며 애플리케이션 요청이나 영구 작업을 차단하거나 실패시키지 않습니다.
따라서 내보내기는 감사 로그나 영구 회계 시스템이 아닙니다. 보안 이벤트에는 추가 전용 보안 감사 로그를, 비용에는 SQL 사용량 원장을, 원격 측정에는 수집기 자체의 보존과 알림 기능을 사용하세요.
문제 해결
원격 측정 데이터가 도착하지 않음. 정확한 애플리케이션 또는 워커 프로세스의 환경에 OTEL_EXPORTER_OTLP_ENDPOINT가 있고, 수집기 Base URL만 포함하며, 수집기가 세 표준 경로에서 OTLP/HTTP JSON을 허용하는지 확인합니다.
수집기에서 승인되지 않음 오류를 반환함. 쉼표로 구분된 헤더 구문과 수집기에서 authorization=Bearer ... 또는 다른 헤더를 기대하는지 확인합니다. 환경 변수를 변경한 뒤 프로세스를 다시 시작하세요.
수집기가 중단되어도 요청이 계속 성공함. 예상된 동작입니다. 애플리케이션 가용성을 위해 내보내기 경로는 실패를 허용하며 실패한 배치를 재시도하도록 저장하지 않습니다.
로그 필드가 없거나 잘림. 비밀 값처럼 보이는 키는 제거되고 길거나 깊게 중첩된 값은 의도적으로 제한됩니다. 민감 정보 제거 경계를 약화하는 대신 안전한 식별자 또는 요약을 기록하세요.