시스템 진단 및 사용량 분석

Libre WebUI는 관리자에게 인스턴스의 두 가지 실시간 보기를 제공합니다. 호스트 및 런타임 진단을 보여 주는 시스템 페이지와 모델 및 공급자 사용량 분석을 보여 주는 사용량 페이지입니다. 두 페이지 모두 백엔드와 인터페이스에서 관리자만 이용할 수 있습니다. 어느 페이지를 읽어도 데이터는 배포 내부에 머뭅니다. 선택적 외부 원격 측정은 운영자가 별도로 구성하는 관측 가능성 경로입니다.

사이드바의 관리자 항목, 탭 메뉴의 관리자 바로 가기 또는 /system과 /usage에서 직접 접근할 수 있습니다. 관리자가 아닌 사용자는 어느 페이지도 열 수 없으며 로그인한 계정에서 admin 역할이 사라지면 관리자 탭도 닫힙니다.

시스템 진단

시스템 페이지(/system)는 다음 내용을 보고합니다.

호스트: 호스트 이름, 플랫폼, 커널 릴리스, 아키텍처, 가동 시간, 논리 CPU 수, CPU 모델, 평균 부하와 프로세스의 컨테이너 실행 여부. CPU 사용률 백분율은 없으며 CPU 부하는 평균 부하로만 표시됩니다.
런타임: 애플리케이션 버전, Node.js 버전, 프로세스 ID, 프로세스 가동 시간과 작업 디렉터리
메모리: 전체, 여유, 사용 중인 호스트 메모리와 프로세스 RSS 및 힙 수치
파일 시스템: 런타임 파일 시스템(/)과 데이터 디렉터리(DATA_DIR)의 용량 및 사용량
네트워크: 인터페이스 이름과 주소, Linux에서는 수신/송신 바이트 카운터
Docker: Docker 소켓을 사용할 수 있을 때 엔진 버전, 호스트 OS, 커널, 엔진에서 보고하는 CPU 및 메모리, 컨테이너 수와 축약된 컨테이너 목록

탭에 포커스가 있는 동안 페이지는 30초마다 새로 고쳐지며 수동 새로 고침 버튼도 있습니다. 백엔드 엔드포인트는 GET /api/system이며 인증, 활성 관리자 역할, 사용자별 15분당 요청 120회의 속도 제한으로 보호됩니다. 응답은 캐시되지 않고(Cache-Control: no-store) 각 요청에서 최신 값을 수집합니다.

Docker 소켓 의존성

Docker 섹션은 Work 런타임 및 대화형 터미널과 같은 방식으로 엔드포인트를 결정합니다. WORK_DOCKER_SOCKET이 설정되어 있으면 사용하며 이는 항상 로컬 Unix 소켓 경로입니다. 그렇지 않으면 DOCKER_HOST를 사용합니다. 이는 unix:// URL 또는 필터링된 Docker API 프록시 같은 일반 HTTP tcp:// 엔드포인트일 수 있습니다. 둘 다 없으면 /var/run/docker.sock을 사용합니다. ssh://, npipe:// 엔드포인트와 TLS 검증이 활성화된 tcp://는 의도적으로 조회하지 않습니다. 요청은 엄격하게 읽기 전용 엔진 GET(버전, 정보, 컨테이너 목록)으로 제한되고 제한 시간은 4초이며 응답 크기가 제한되고 컨테이너 목록은 최대 100개입니다.

사용 가능한 소켓이 없어도 페이지의 나머지 부분은 계속 작동합니다. Docker 패널에는 전체 요청을 실패시키는 대신 사용할 수 없는 이유(소켓이 마운트되지 않음, 마운트되었지만 읽을 수 없음, 데몬에 연결할 수 없음 또는 원격 엔드포인트)가 표시됩니다.

페이지에 표시되는 정보와 공개 대상

컨테이너 목록은 의도적으로 축약되어 짧은 ID, 이름, 이미지, 상태와 생성 시간만 표시합니다. 환경 변수, 레이블, 마운트, 컨테이너 명령과 inspect 페이로드는 절대 포함되지 않으며 응답 어디에도 자격 증명이 나타나지 않습니다.

그렇더라도 페이지에는 호스트 이름, 작업 디렉터리, 내부 IP 주소와 Libre WebUI 컨테이너뿐 아니라 Docker 호스트의 모든 컨테이너 이름 및 이미지 같은 실제 인프라 세부 정보가 표시됩니다. 이는 신뢰 모델과 일치합니다. Docker 배포에서는 모든 Libre WebUI 관리자가 이미 사실상 호스트 관리자입니다(Docker 참조). 이에 맞춰 admin 역할을 부여하세요.

사용량 분석

사용량 페이지(/usage)는 사용자에게 귀속된 모델 및 공급자 작업을 차트로 보여 줍니다. 계측은 지원되는 각 실행 경계에서 수행되며 현재 다음을 포함합니다.

기본 Chat 및 Ollama 기반 Work를 포함한 로컬 Ollama 채팅 호출
설치된 에이전트 CLI 채팅 호출과 Strands 엔진 호출
플러그인 기반 스트리밍 및 비스트리밍 채팅
플러그인 임베딩, 이미지 생성, 음성 인식, 음성 합성, 사운드, 동영상
플러그인 기반 Work 호출

소유 사용자가 없는 백그라운드 작업은 의도적으로 가상 계정에 할당하지 않으므로 계측되지 않습니다. 호출이 실패하거나 취소되더라도 기록됩니다.

각 이벤트는 다음 항목을 기록합니다.

제공자/플러그인 ID와 표시 이름 스냅샷(ollama와 agent-cli:*는 플러그인과 같은 원장 사용)
기능(chat, embedding, image, stt, tts, audio, video)
모델
상태: success, error, cancelled(중단된 스트림은 취소로 계산)
제공자가 메타데이터를 반환한 경우에만 토큰 수
기능별 단위 수(TTS 문자, 이미지, 임베딩 입력, 동영상 작업, 오디오 바이트)
전체 소요 시간과 타임스탬프
요청 사용자 ID

그 외의 항목은 저장하지 않습니다. 프롬프트, 응답, 공급자 엔드포인트, 자격 증명과 공급자 오류 본문은 사용량 테이블에 절대 기록되지 않으며, 실패한 호출은 status = 'error'로만 기록됩니다. 이벤트는 선택한 애플리케이션 데이터베이스(solo 모드의 SQLite, team 모드의 PostgreSQL)에 저장되고 400일 동안 유지됩니다. 더 오래된 행은 쓰기 시 하루 최대 한 번 기회적으로 정리됩니다. 계측은 의도적으로 최선형이며 모델 또는 공급자 요청을 실패하게 만들 수 없습니다.

이 페이지는 관리자 전용 단일 엔드포인트인 GET /api/plugins/usage?days=<1..365>(기본값 30)를 통해 7일, 30일, 90일 범위를 제공합니다. 총 호출 수, 보고된 토큰, 성공률, 평균 지연 시간, 그리고 토큰 사용량을 보고한 호출의 비율을 표시합니다. 이 페이지를 보는 동작은 읽기 전용이며 배포에 이미 있는 사용량 원장을 사용합니다.

에이전트 사용량

상단 근처 에이전트 영역(CLI 에이전트 및 Strands 엔진 호출)은 Claude Code, Codex, OpenCode, Pi, Strands를 각각 표시합니다. 호출, 보고된 토큰, 실패·취소 호출, 평균 시간, 상위 20개 모델을 포함합니다. 에이전트 합계는 제공자·모델 표의 표시 제한과 무관하게 선택 기간의 모든 해당 호출을 포함합니다. 페이지 총계의 부분집합이며 추가 과금 이벤트가 아닙니다.

기록이 없으면 이 기간에 기록된 호출이 없습니다라고 표시합니다. CLI가 설치되었거나 로그인되었는지를 뜻하지는 않습니다. 토큰 메타데이터가 없는 호출은 토큰이 보고되지 않음으로 표시하며 값을 추정하지 않습니다. 페이지가 보이는 동안 20초마다 갱신하고 수동 갱신도 제공합니다.

CLI 사용량은 호출 한 번과 CLI가 보고한 토큰 카운터를 기록합니다. 누적 스냅샷은 이전 것을 대체하고 중복 단계 보고를 제거합니다. 캐시·추론 카운터는 각 CLI 규약에 맞게 합치며 부분집합을 중복 집계하지 않습니다. 취소된 실행이나 부분 응답 후 비정상 종료한 호출도 실제 결과를 유지합니다.

Strands 호출은 Strands 에이전트에 귀속됩니다. 엔진에는 자체 모델 제공자가 없으며, 엔진이 수행하는 모든 모델 호출은 Libre WebUI의 Ollama 또는 플러그인 제공자를 거칩니다. LWUI 외부 호출은 가져오지 않으며 토큰 없는 과거 기록은 미계측 상태를 유지합니다.

엔드포인트는 agents에 제한된 내역을 제공하며 카운터가 0이어도 지원하는 다섯 이름을 모두 포함합니다. 조회는 CLI 모델 검색, 에이전트 실행, 제공자 접촉을 하지 않습니다. 이 필드가 없는 이전 서버에서는 제공자 내역에 있는 에이전트 기록을 표시할 수 있지만, 없는 항목을 확실한 0 사용량으로 표시하지 않습니다.

모델과 제공자 살펴보기

모델 색상은 일별 차트, 연간 활동 달력, 모델 표, 제공자 막대를 하나로 연결합니다. 색상과 함께 모델 이름, 값, 선택 표시가 함께 제공됩니다. 활동 달력은 선택한 범위와 무관하게 항상 최근 365일을 다루며, 각 날짜의 색은 그날 가장 많이 사용한 모델을 나타냅니다.

일별 차트는 호출과 토큰 사이를 전환합니다. 범례에서 모델에 포인터를 올리거나 키보드 포커스를 옮기면 해당 모델의 선을 따라갈 수 있습니다. 모델을 선택하면 강조가 유지되고, 다시 선택하면 해제되며, 모든 모델 표시를 선택하면 초기화됩니다. 모델 표에서도 강조 동작을 사용할 수 있습니다. 강조는 표현만 바꿀 뿐 일별 합계, 표의 값, 제공자 합계는 그대로 유지됩니다.

차트 위로 포인터를 움직이거나 일별 사용량 살펴보기를 사용하면 특정 날짜의 합계와 모델 구성을 확인할 수 있습니다. 일별 슬라이더는 키보드 이동을 지원해 화살표 키로 날짜를 옮기고 Home/End로 첫날과 마지막 날로 이동합니다. 일별 버킷과 레이블은 UTC를 사용합니다.

기본적으로 차트는 선택한 기간에서 호출 수가 가장 많은 모델 이름 12개를 표시하며, 토큰을 볼 때도 마찬가지입니다. 모든 모델은 여전히 개별로 확인할 수 있습니다. 표나 제공자 세부 정보에서 모델에 포커스하거나 모델을 선택하면 그 12개 밖에 있는 모델이라도 정확한 일별 선을 불러옵니다. 로딩 메시지에는 요청한 모델 이름이 표시됩니다.

추가로 불러온 모델의 선은 기타 모델에서 분리되며, 남은 그룹에서는 그 모델의 호출, 보고된 토큰, 실패가 제외됩니다. 차트에는 이름이 지정된 모델 선이 최대 13개와 남은 그룹이 포함되고, 일별 값은 계속 같은 합계와 맞아떨어집니다. 모든 모델 표시를 선택하면 기본 화면으로 돌아갑니다.

일별 선은 기록된 모델 이름이 같은 호출을 제공자에 상관없이 합칩니다. 모델 표는 제공자/모델 항목을 따로 유지하므로 같은 모델이 여러 제공자 아래에 나타날 수 있습니다. 이름이 지정된 모델은 기본 차트 밖에 있는 모델을 포함해 표와 제공자 막대에서 고유한 색을 유지합니다.

제공자 세부 정보에는 제공자별 요청 비중, 모델로 나뉜 막대, 보고된 토큰, 실패하거나 취소된 호출, 평균 응답 시간이 표시됩니다. 기능 구성은 모델과 제공자 분석 아래에 계속 표시됩니다.

토큰 합계에는 공급자가 사용량 메타데이터를 보고한 호출만 포함됩니다. 커버리지 비율은 보고가 일부만 이뤄졌다는 사실을 드러냅니다. 누락된 토큰 수를 요청 수나 다른 모델에서 추정하지 않습니다. 보고된 토큰이 전혀 없는 기간에는 토큰 화면에 설명이 표시되며, 해당 요청 이력은 호출 화면에서 계속 확인할 수 있습니다.

이 엔드포인트는 modelSeries에 일별 모델 데이터를 포함합니다. 선택적 model 쿼리 매개변수는 기본 상위 12개와 함께 기록된 정확한 모델 이름 하나를 요청합니다. 예: GET /api/plugins/usage?days=30&model=<encoded-model-name>. 이것도 동일한 관리자 전용 읽기 전용 엔드포인트로, 로컬 사용량 원장을 조회할 뿐 이력을 가져오려고 모델 공급자를 호출하지 않습니다.

선택적 to 매개변수는 요청의 종료 경계를 밀리초 단위 Unix 타임스탬프로 고정합니다. model이 함께 필요하며 서버의 현재 시각보다 늦지 않은 음수가 아닌 안전한 정수만 허용합니다. 브라우저는 개별 모델을 불러올 때 개요의 range.to를 보내 UTC 일·연 경계를 유지하고 해당 타임스탬프 이후의 호출을 제외합니다. to가 없으면 엔드포인트는 현재 시각을 사용합니다.

모델을 불러와도 개요의 카드, 표, 제공자 합계, 색상은 그대로 유지됩니다. 응답의 시간 범위와 일별 합계가 그 개요와 일치할 때만 일별 선이 추가됩니다. 시간 경계가 데이터베이스를 고정하지는 않습니다. 과거 데이터 보정이나 삭제로 합계가 바뀌면 브라우저는 모델 선을 표시하기 전에 개요를 새로 고칩니다.

오래된 서버가 modelSeries를 생략하면 차트는 집계된 모든 모델 계열을 표시하고 모델별 분석을 사용할 수 없다고 설명합니다. 모델 표는 계속 사용할 수 있으며, 브라우저는 기간 합계나 연간 달력에서 일별 모델 이력을 추론하지 않습니다.

계측을 비활성화하는 스위치는 없습니다. 데이터가 계정 전체에서 집계되므로 관리자만 확인할 수 있습니다.

사용량 페이지는 호출, 단위, 토큰, 지연 시간과 결과를 보고합니다. 이러한 이벤트에 적용일별 요금표, 지출 내역, 예산, 알림 또는 회계 내보내기가 필요하면 비용 관리를 추가하세요. 일치하는 요금표가 없거나 공급자가 사용량을 보고하지 않은 이벤트는 무료로 취급하지 않고 가격 미정으로 명확히 표시합니다.

OpenRouter 귀속 정보

0.18.0부터 OpenRouter 요청은 OpenRouter의 앱 귀속 헤더(HTTP-Referer: https://librewebui.org, 애플리케이션 제목과 카테고리 힌트)를 통해 애플리케이션을 식별합니다. 이 헤더는 요청이 https://openrouter.ai 자체로 전송될 때만 보내며 사용자 지정 또는 자체 호스팅 경로에는 절대 보내지 않습니다. 로컬에 저장되는 정보도 늘어나지 않습니다.