Diagnóstico Técnico¶
O jaylog possui um canal de diagnóstico interno para observar sua própria operação. Ele registra decisões de configuração, inicialização de handlers, coletas auxiliares, chamadas a subprocessos, transmissões HTTP, retries e encerramento.
Esse canal é diferente dos registros produzidos pela aplicação. Definir
JAYLOG_LOG_LEVEL=DEBUG permite registros logger.debug(...); definir
JAYLOG_DEBUG=true habilita os diagnósticos internos do jaylog.
Habilitação¶
Em .env.logging ou no ambiente do processo:
Ou diretamente em código:
from jaylog import JaylogSettings, configure
configure(JaylogSettings(app_name="meu-bot", debug=True))
O padrão é false. Quando desabilitado, o canal não produz saída nem altera o
comportamento dos handlers normais.
Destinos¶
JAYLOG_DEBUG_HANDLERS recebe uma lista separada por vírgulas. Os valores
aceitos são console, file e http; o padrão é somente console.
Em código, use a mesma sintaxe:
| Destino | Comportamento | Requisito |
|---|---|---|
console |
Emite imediatamente em stderr, inclusive antes da construção do logger. |
Nenhum; é independente de JAYLOG_LOG_CONSOLE_ENABLED. |
file |
Encaminha o diagnóstico ao arquivo rotativo do serviço. | JAYLOG_LOG_DIR configurado e o logger construído por get_logger(). |
http |
Envia o diagnóstico como um registro de log para o endpoint principal. | JAYLOG_LOG_HTTP_ENDPOINT e JAYLOG_LOG_HTTP_API_KEY configurados. |
Os destinos podem ser combinados:
Um nome desconhecido ou uma lista vazia invalida JaylogSettings. Diagnósticos
destinados a file ou http que ocorrerem antes da construção dos handlers são
mantidos num buffer limitado e reproduzidos quando o logger é construído.
Warning
O destino http deve ser usado temporariamente e de forma consciente: ele
aumenta o volume de registros transmitidos. O handler impede recursão — uma
transmissão diagnóstica não gera outro diagnóstico HTTP — e não anexa
screenshots aos registros internos.
Formato¶
No console, cada linha segue este formato:
Exemplo:
[jaylog] debug schedule: contexto de execução identificado; modo=task_scheduler; cadeia=python.exe < cmd.exe < svchost.exe
[jaylog] debug schedule: consulta XML iniciada; comando=`schtasks /query /xml`; timeout=10s
[jaylog] debug schedule: análise sintática do XML concluída; tasks_lidas=42; tasks_elegíveis=3
[jaylog] debug schedule: consolidação concluída; agendas_para_envio=5
Nos destinos file e http, a mensagem mantém o prefixo
[jaylog] debug <componente>: e o nível textual DEBUG. Esses registros não são
suprimidos por JAYLOG_LOG_LEVEL, pois o canal precisa diagnosticar inclusive a
configuração dos próprios handlers.
Etapas observadas¶
| Componente | Informações registradas |
|---|---|
logger |
Configuração, seleção e construção dos handlers, QueueListener, reutilização e encerramento. |
entrypoint |
Origem usada para identificar o arquivo principal: executável congelado, __main__.__file__ ou sys.argv[0]. |
git |
Comandos executados, diretório de busca, timeout, código de saída e resumo da detecção. |
host |
Elegibilidade, coleta do ambiente, cache do snapshot e entrega ao endpoint. |
metrics |
Inicialização do sampler, coleta, ocupação do buffer, lotes HTTP e amostra final. |
schedule |
Modo de execução, entrypoint, consulta XML, parsing, associação de tasks, consolidação e envio. |
http |
Início e término das requisições de logs, status HTTP, exceções e solicitação de sincronização do host. |
file |
Rotação do arquivo e aplicação da política de retenção. |
screenshot |
Elegibilidade, resultado, tamanho, qualidade, escala ou falha da captura. |
safe |
Exceções que um coletor suprimiu para proteger a aplicação. |
Segurança dos diagnósticos¶
O canal não imprime:
- chaves de API;
- conteúdo dos registros da aplicação;
- payloads completos;
- corpos integrais de respostas HTTP;
- conteúdo dos arquivos inspecionados.
Caminhos locais, nomes de serviço, endpoints, comandos sem credenciais, códigos HTTP e descrições de exceções podem aparecer porque são necessários para o diagnóstico. Antes de compartilhar a saída externamente, trate esses valores como informações operacionais do ambiente.
Diagnóstico do Task Scheduler¶
Para investigar a sincronização de agendas no Windows, habilite inicialmente somente o console:
Execute a task e acompanhe, nesta ordem:
modo=task_schedulerna identificação do contexto;- caminho do entrypoint identificado;
- execução de
schtasks /query /xml; - quantidade de tasks lidas e elegíveis;
- tasks associadas ao entrypoint e agendas extraídas;
- consolidação do payload;
- requisição e resposta de
POST /logs/host-schedules.
Se a sequência parar, a última mensagem identifica a etapa que impediu o envio. Veja as regras de associação e os limites em Agendas do Task Scheduler.
Desativação¶
Remova as variáveis ou defina:
Não use o diagnóstico permanentemente apenas por conveniência. Em produção,
habilite-o pelo período necessário para investigar o incidente e depois o
desative, principalmente quando file ou http estiver selecionado.