Diagnósticos do sistema e análise de uso

O Libre WebUI oferece aos administradores duas visualizações ao vivo da instância: uma página Sistema, com diagnósticos do host e do ambiente de execução, e uma página Uso, com análises de utilização de modelos e provedores. Ambas são exclusivas para administradores no backend e na interface. A leitura de qualquer uma das páginas permanece dentro da implantação; a telemetria externa opcional usa um caminho separado de Observabilidade, configurado pelo operador.

Acesse-as pelas entradas administrativas na barra lateral, pelos atalhos de administrador no menu de abas ou diretamente em /system e /usage. Usuários que não são administradores não podem abrir nenhuma das páginas, e as abas administrativas são fechadas quando uma conta conectada perde a função admin.

Diagnósticos do sistema

A página Sistema (/system) informa:

Host: nome do host, plataforma, versão do kernel, arquitetura, tempo de atividade, quantidade de CPUs lógicas, modelo da CPU, média de carga e se o processo parece estar em um contêiner. Não há percentual de uso da CPU; a carga da CPU é somente a média de carga.
Ambiente de execução: versão do aplicativo, versão do Node.js, ID do processo, tempo de atividade do processo e diretório de trabalho.
Memória: memória total, livre e usada do host, além dos valores de RSS e heap do processo.
Sistemas de arquivos: capacidade e uso do sistema de arquivos do ambiente de execução (/) e do diretório de dados (DATA_DIR).
Rede: nomes e endereços das interfaces, com contadores de bytes recebidos/transmitidos no Linux.
Docker: versão do mecanismo, sistema operacional do host, kernel, CPU e memória conforme informados pelo mecanismo, além das contagens de contêineres e de uma lista reduzida deles, quando o socket do Docker estiver disponível.

A página é atualizada a cada 30 segundos enquanto sua aba está em foco e tem um botão de atualização manual. O endpoint do backend é GET /api/system, protegido por autenticação, por uma função ativa de administrador e por um limite por usuário de 120 solicitações a cada 15 minutos. As respostas nunca são armazenadas em cache (Cache-Control: no-store), e cada solicitação coleta valores novos.

Dependência do socket do Docker

A seção do Docker resolve seu endpoint da mesma forma que o ambiente de execução do Work e o terminal interativo: WORK_DOCKER_SOCKET, quando definido (sempre um caminho de socket Unix local); caso contrário, DOCKER_HOST — uma URL unix:// ou um endpoint tcp:// em HTTP simples, como um proxy filtrado da API do Docker —; caso contrário, /var/run/docker.sock. Endpoints ssh:// e npipe://, assim como tcp:// com verificação TLS habilitada, deliberadamente não são consultados. As solicitações são estritamente operações GET de leitura do mecanismo (versão, informações e lista de contêineres), com tempo limite de 4 segundos e tamanho de resposta limitado; a lista de contêineres é limitada a 100 entradas.

Sem um socket utilizável, o restante da página continua funcionando: o painel do Docker informa por que ele está indisponível — socket não montado, montado mas sem permissão de leitura, daemon inacessível ou endpoint remoto — em vez de fazer a solicitação inteira falhar.

O que a página revela e para quem

A lista de contêineres é reduzida de propósito: ID curto, nome, imagem, estado e horário de criação. Variáveis de ambiente, rótulos, montagens, comandos dos contêineres e cargas de inspeção nunca são incluídos, e nenhuma credencial aparece na resposta.

Mesmo assim, a página mostra detalhes reais da infraestrutura — nome do host, diretório de trabalho, endereços IP internos e nomes e imagens de todos os contêineres no host Docker, não somente os do Libre WebUI. Isso é coerente com o modelo de confiança: em uma implantação com Docker, todo administrador do Libre WebUI já é, na prática, um administrador do host (consulte Docker). Conceda a função admin de acordo com essa responsabilidade.

Análise de uso

A página Uso (/usage) apresenta gráficos do trabalho de modelos e provedores atribuído a usuários. A medição ocorre em cada limite de execução compatível e, no momento, abrange:

chamadas locais do Ollama, incluindo Chat nativo e Work baseado em Ollama;
chamadas de chat de CLIs de agentes instaladas e chamadas do motor Strands;
chat por plugins, com e sem streaming;
embeddings, imagens, transcrição, síntese de voz, som e vídeo por plugins;
chamadas Work por plugins.

Operações em segundo plano sem um usuário proprietário deliberadamente não são atribuídas a uma conta sintética e, portanto, não são medidas. Uma chamada ainda é registrada quando falha ou é cancelada.

Cada evento registra:

ID do provedor/plugin e snapshot do nome (ollama e agent-cli:* usam o mesmo registro dos plugins)
capacidade (chat, embedding, image, stt, tts, audio, video)
modelo
estado: success, error ou cancelled (stream interrompido conta como cancelado)
tokens, apenas quando o provedor retorna metadados de uso
unidades da capacidade: caracteres de TTS, imagens, entradas de embeddings, tarefas de vídeo, bytes de áudio
duração de ponta a ponta e horário
ID do usuário solicitante

Nada mais é armazenado. Prompts, respostas, endpoints de provedores, credenciais e corpos de erro dos provedores nunca são gravados na tabela de uso — uma chamada com falha é registrada somente como status = 'error'. Os eventos ficam no banco de dados selecionado do aplicativo (SQLite no modo individual, PostgreSQL no modo de equipe) e são mantidos por 400 dias; linhas mais antigas são removidas de forma oportunista durante a gravação, no máximo uma vez por dia. A medição funciona por melhor esforço e nunca pode fazer uma solicitação a um modelo ou provedor falhar.

A página oferece intervalos de 7, 30 e 90 dias por meio de um único endpoint exclusivo para administradores, GET /api/plugins/usage?days=<1..365> (padrão 30). Ela mostra o total de chamadas, os tokens informados, a taxa de sucesso, a latência média e a proporção de chamadas que informaram uso de tokens. A leitura da página é somente leitura e usa o registro de uso que a instalação já mantém.

Uso dos agentes

A seção Agentes próxima ao topo (Chamadas a agentes CLI e ao motor Strands) separa Claude Code, Codex, OpenCode, Pi e Strands. Mostra chamadas, tokens informados, falhas e cancelamentos, duração média e até 20 modelos mais usados de cada agente. Os totais cobrem todas as chamadas correspondentes do período, independentemente dos limites das tabelas maiores de provedores e modelos. São partes do total da página, não eventos adicionais de cobrança.

Sem registros, o agente mostra Nenhuma chamada registrada neste período. Isso não indica instalação ou login da CLI. Sem metadados de tokens, aparece Tokens não reportados, sem estimar valores. A página atualiza a cada 20 segundos enquanto visível e oferece atualização manual.

O uso CLI registra uma execução e os contadores informados pela CLI. Snapshots cumulativos substituem os anteriores; relatórios repetidos por etapa são deduplicados. Cache e raciocínio são combinados conforme cada protocolo, sem contar subconjuntos duas vezes. Cancelamentos e respostas parciais que terminam com falha preservam seu resultado real.

As chamadas do Strands são atribuídas ao agente Strands. O motor não tem um provedor de modelos próprio; toda chamada de modelo que ele faz passa pelos provedores do Ollama ou de plugins do Libre WebUI. Chamadas fora do LWUI não são importadas, e registros antigos sem contadores permanecem não medidos.

O endpoint expõe esse detalhamento limitado em agents, incluindo os cinco nomes suportados mesmo com contadores zerados. A leitura não descobre modelos CLI, inicia agentes ou contata provedores. Servidores antigos sem o campo podem mostrar registros de agentes disponíveis no detalhamento de provedores, mas entradas ausentes não são apresentadas como uso zero confirmado.

Explore modelos e provedores

As cores dos modelos conectam o gráfico diário, o calendário anual de atividade, a tabela de modelos e as barras por provedor. Além das cores, os nomes dos modelos, os valores e os indicadores de seleção também aparecem. O calendário de atividade sempre cobre os últimos 365 dias, independentemente do intervalo escolhido; a cor de cada dia identifica o modelo mais usado naquele dia.

O gráfico diário alterna entre Chamadas e Tokens. Passe o ponteiro sobre um modelo na legenda ou leve o foco do teclado até ele para acompanhar a linha desse modelo. Selecione o modelo para mantê-lo destacado, selecione de novo para liberar ou escolha Mostrar todos os modelos para reiniciar. A tabela de modelos também oferece a ação de destaque. Destacar muda a ênfase, mas preserva os totais diários, os valores da tabela e os totais por provedor.

Mova o ponteiro pelo gráfico ou use Explorar a utilização diária para inspecionar o total de um dia e sua composição por modelo. O controle deslizante diário aceita o teclado: as setas percorrem os dias e Home/End chegam ao primeiro e ao último. Os agrupamentos diários e seus rótulos usam UTC.

Por padrão, o gráfico mostra os 12 modelos com mais chamadas no período selecionado, inclusive na visualização de tokens. Todos os modelos continuam inspecionáveis individualmente: foque ou selecione um modelo na tabela ou nos detalhes do provedor para carregar a linha diária exata dele, mesmo fora desses 12. Uma mensagem de carregamento nomeia o modelo solicitado enquanto o histórico é buscado.

A linha de um modelo adicional é separada de Outros modelos, e o grupo restante deixa de contar as chamadas, os tokens informados e as falhas dele. O gráfico tem no máximo 13 linhas de modelos nomeados mais o grupo restante, e os valores diários continuam batendo com os mesmos totais. Escolha Mostrar todos os modelos para voltar à visualização padrão.

As linhas diárias combinam chamadas com o mesmo nome de modelo registrado em provedores diferentes. A tabela de modelos mantém as entradas de provedor/modelo separadas, então o mesmo modelo pode aparecer sob mais de um provedor. Modelos nomeados mantêm cores próprias na tabela e nas barras por provedor, inclusive os que ficam fora do gráfico padrão.

Os detalhes do provedor mostram a participação de cada provedor nas requisições, uma barra dividida por modelo, os tokens informados, as chamadas com falha ou canceladas e o tempo médio de resposta. A distribuição de recursos continua disponível abaixo dos detalhamentos por modelo e por provedor.

Os totais de tokens incluem somente chamadas nas quais o provedor informou metadados de uso. O percentual de cobertura torna visível um relato parcial; contagens de tokens ausentes nunca são estimadas a partir das requisições nem de outro modelo. Um período sem tokens informados mostra uma explicação na visualização de tokens, e seu histórico de requisições continua disponível em chamadas.

O endpoint inclui pontos diários por modelo em modelSeries. Um parâmetro de consulta opcional model pede um nome de modelo registrado exato junto dos 12 primeiros padrão, por exemplo GET /api/plugins/usage?days=30&model=<encoded-model-name>. É o mesmo endpoint somente leitura e exclusivo para administradores: ele consulta o registro de uso local e nunca chama um provedor de modelos para obter histórico.

Um parâmetro opcional to fixa o limite final da requisição em um timestamp Unix em milissegundos. Ele exige model e aceita apenas um inteiro seguro não negativo que não seja posterior ao horário atual do servidor. Ao carregar um modelo individual, o navegador envia o range.to da visão geral, preservando os limites de dia e ano em UTC e excluindo chamadas depois desse timestamp. Sem to, o endpoint usa o horário atual.

Carregar um modelo mantém os cartões, a tabela, os totais por provedor e as cores da visão geral. A linha diária dele só é adicionada quando os limites de tempo e os totais diários da resposta coincidem com essa visão geral. O limite de tempo não congela o banco de dados: se recargas históricas ou exclusões alterarem esses totais, o navegador atualiza a visão geral antes de mostrar a linha do modelo.

Se um servidor mais antigo não enviar modelSeries, o gráfico mostra a série agregada Todos os modelos com uma explicação de que o detalhamento por modelo está indisponível. A tabela de modelos continua disponível; o navegador não deduz o histórico diário por modelo a partir dos totais do período nem do calendário anual.

Não há opção para desabilitar a medição. Como os dados são agregados entre contas, sua inspeção é restrita aos administradores.

A página Uso informa chamadas, unidades, tokens, latência e resultados. Adicione a Governança de custos quando esses eventos precisarem de tarifas com vigência definida, detalhamento de gastos, orçamentos, alertas ou exportação contábil. Eventos sem uma tarifa correspondente ou sem uso informado pelo provedor permanecem visivelmente sem preço, em vez de serem tratados como gratuitos.

Atribuição do OpenRouter

Desde a versão 0.18.0, as solicitações ao OpenRouter identificam o aplicativo por meio dos cabeçalhos de atribuição do OpenRouter (HTTP-Referer: https://librewebui.org, um título do aplicativo e indicações de categoria). Esses cabeçalhos são enviados somente quando a solicitação vai para o próprio https://openrouter.ai — nunca para uma rota personalizada ou auto-hospedada — e não acrescentam nada ao que é armazenado localmente.