Observabilidade
O Libre WebUI oferece dois caminhos de observabilidade para operadores:
- logs estruturados do aplicativo, gravados localmente na saída e no erro padrão;
- um exportador OpenTelemetry opcional para solicitações HTTP, tarefas persistentes, contadores e registros de log de aviso/erro.
Nenhum desses caminhos envia telemetria ao projeto Libre WebUI. O OpenTelemetry permanece desativado até que um operador configure o endpoint de um coletor. As páginas administrativas de Sistema e Uso são separadas: elas leem os diagnósticos e o uso de modelos/provedores da própria implantação, não de um coletor OpenTelemetry.
Logs estruturados
O padrão LOG_FORMAT=text mantém a saída conhecida do console, separada por escopo. Defina LOG_FORMAT=json para gerar um objeto JSON por linha:
LOG_LEVEL=info
LOG_FORMAT=json
Cada linha estruturada contém:
- um carimbo de data e hora ISO;
- o nível e o escopo do logger;
- uma mensagem;
- o ID de correlação da solicitação ou da tarefa persistente atual, quando houver; e
- detalhes estruturados e limitados fornecidos por quem fez a chamada.
Toda solicitação HTTP recebe um X-Request-Id. O Libre aceita um ID recebido somente quando ele tem entre 8 e 64 caracteres formados por letras, dígitos, ., _ ou -; caso contrário, cria um UUID. O ID é devolvido na resposta e acompanha o trabalho assíncrono pelo contexto de logging. Os logs de acesso registram método HTTP, caminho, status e duração, com a string de consulta removida porque os parâmetros de consulta podem conter conteúdo do usuário ou credenciais de curta duração.
LOG_LEVEL aceita silent, error, warn, info ou debug. O logging de depuração pode expor mais detalhes operacionais; habilite-o somente durante o diagnóstico de um problema e proteja os logs resultantes como quaisquer outros dados da implantação.
Limite de supressão de dados
Os detalhes estruturados e a telemetria exportada passam pelo mesmo auxiliar limitado de supressão:
- campos cujos nomes lembram senhas, segredos, tokens, chaves, autorização, cookies, credenciais, valores bearer ou JWTs são omitidos;
- strings são limitadas a 512 caracteres;
- arrays, profundidade de aninhamento e contagens de atributos exportados têm limites; e
- objetos de erro preservam o nome e uma mensagem limitada, não um grafo arbitrário de objetos.
Essa é uma defesa em profundidade, não uma permissão para registrar prompts ou segredos. Uma string curta fornecida pelo usuário em um campo cujo nome não pareça conter um segredo ainda pode virar texto comum de log. Extensões do aplicativo devem registrar identificadores e resultados, não corpos de solicitações, prompts, texto de documentos, resultados de ferramentas nem cargas de provedores. Restrinja o acesso aos logs e aplique uma política de retenção gerenciada pelo operador.
Habilitar o OpenTelemetry
O Libre exporta OTLP/HTTP JSON diretamente, sem adicionar uma dependência do SDK OpenTelemetry. Aponte-o para a URL HTTP base de um coletor que aceite os caminhos de sinal padrão:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
O exportador acrescenta /v1/traces, /v1/metrics e /v1/logs à URL base. OTEL_EXPORTER_OTLP_HEADERS é uma lista separada por vírgulas de pares key=value. Armazene as credenciais do coletor como segredos da implantação; não as inclua em commits. O valor padrão de OTEL_SERVICE_NAME é libre-webui.
Quando a variável do endpoint não está presente, o registro de spans, métricas e logs não faz nada, e nenhum dado sai do processo. Em uma implantação de equipe, os processos do aplicativo e de workers externos exportam de forma independente; portanto, forneça a cada processo a configuração de coletor que ele deve usar. Um nome de serviço diferente para cada função pode facilitar a leitura dos painéis.
Sinais exportados
| Sinal | O que o Libre registra |
|---|---|
| Spans do servidor HTTP | Método e caminho sem string de consulta, status da resposta, duração, status de sucesso/falha e ID da solicitação |
| Contadores HTTP | Contagem monotônica de solicitações por método e classe de status da resposta |
| Spans de tarefas persistentes | Tipo da tarefa, número da tentativa, duração e status de sucesso/falha |
| Contadores de tarefas persistentes | Contagem monotônica de execuções por tipo de tarefa e resultado |
| Registros de log | Mensagens de aviso e erro com dados suprimidos, escopo do logger e IDs de correlação da solicitação/tarefa |
Os spans são spans locais concluídos. Atualmente, o Libre não propaga um trace parent OpenTelemetry recebido, não cria árvores de spans pai/filho entre serviços e não instrumenta a renderização no navegador nem todas as chamadas de provedores. O uso de tokens de modelos e de mídia pertence aos registros locais de Análise de uso e Governança de custos.
Comportamento de entrega
A telemetria é deliberadamente baseada em melhor esforço:
- os buffers armazenam no máximo 2.048 spans e 2.048 registros de log e descartam a entrada mais antiga sob pressão;
- no máximo 512 séries de contadores são mantidas;
- o exportador envia os dados a cada cinco segundos, aproximadamente;
- cada exportação HTTP tem um tempo limite de três segundos; e
- um erro no coletor descarta esse lote e nunca bloqueia nem faz falhar uma solicitação do aplicativo ou uma tarefa persistente.
Portanto, o exportador não é um log de auditoria nem um sistema persistente de contabilização. Use o log de auditoria de segurança somente de acréscimo para eventos de segurança, o registro de uso SQL para custos e a retenção e os alertas do próprio coletor para a telemetria.
Solução de problemas
Nenhuma telemetria chega. Confirme se OTEL_EXPORTER_OTLP_ENDPOINT está presente no ambiente do processo exato do aplicativo ou do worker, contém somente a URL base do coletor e se o coletor aceita OTLP/HTTP JSON nos três caminhos padrão.
O coletor retorna “não autorizado”. Verifique a sintaxe dos cabeçalhos separados por vírgula e se o coletor espera authorization=Bearer ... ou outro cabeçalho. Reinicie o processo depois de alterar as variáveis de ambiente.
As solicitações continuam funcionando enquanto o coletor está indisponível. Esse é o comportamento esperado. O caminho de exportação falha de forma aberta para preservar a disponibilidade do aplicativo e não persiste lotes com falha para tentar novamente.
Um campo de log está ausente ou abreviado. Chaves que parecem conter segredos são removidas, e valores longos ou profundamente aninhados são limitados por projeto. Registre um identificador ou resumo seguro em vez de enfraquecer o limite de supressão.