Table of Contents

Como acessar e usar arquivos de registro OpenAPS para solução de problemas e otimização

OpenAPS (Open Artificial Pancreas System) é um sistema de pâncreas artificial de código aberto, dirigido pela comunidade, que automatiza a entrega de insulina para pessoas com diabetes. O sistema é executado em pequenos computadores como Raspberry Pi ou Intel Edison, processando dados de monitor de glicose contínua (CGM) e controla uma bomba de insulina em tempo real. Embora o OpenAPS seja projetado para operar de forma confiável, nenhum sistema é perfeito. Arquivos de registro são a ferramenta de diagnóstico primária para entender o que o sistema está fazendo, por que ele tomou uma decisão particular, e onde as coisas podem ter dado errado. Dominar arquivos de registro é essencial para operação segura, solução de problemas eficazes e otimização de longo prazo de sua configuração.

Este guia fornece uma análise profunda e prática dos logs do OpenAPS: como acessá-los, o que cada seção significa, como usá-los para depurar problemas comuns e como aproveitar dados de log para ajustar seu sistema para melhores resultados de glicose. Se você é um novo usuário configurando seu primeiro equipamento ou um construtor experiente procurando melhorar o desempenho, entender logs é uma habilidade que lhe servirá bem.

A aceder aos Ficheiros de Registo OpenAPS

Antes de poder analisar os logs, você precisa chegar a eles. OpenAPS armazena arquivos de log no dispositivo que executa o sistema, tipicamente um Raspberry Pi executando Raspbian ou um sistema operacional Linux semelhante. O acesso requer conexão com esse dispositivo, tanto localmente quanto através da rede.

SSH: O Método de Acesso Remoto Primário

O Secure Shell (SSH) é a maneira mais comum e prática de acessar os logs do OpenAPS. Com o SSH ativado em seu equipamento, você pode conectar-se de qualquer computador na mesma rede usando um cliente terminal. No Windows, os clientes populares incluem o PuTTY e o Terminal do Windows; no macOS e Linux, o comando integrado funciona diretamente. Uma vez conectado com o endereço IP e credenciais do seu equipamento, você tem acesso completo à linha de comando para navegar, visualizar e transferir arquivos de log.

Acesso direto à consola

Se o seu equipamento estiver fisicamente acessível e o SSH não estiver disponível ou não estiver a funcionar, poderá ligar um monitor e um teclado directamente ao dispositivo. Este método é útil para a configuração inicial ou quando os problemas de rede impedirem o acesso remoto. Os mesmos ficheiros de registo estão disponíveis na consola e pode usar comandos Linux normais para navegar e lê- los.

Transferência de logs com SCP e SFTP

Para análise detalhada num computador de secretária, você poderá copiar ficheiros de registo usando SCP (Secure Copy) ou SFTP (SSH File Transfer Protocol). Estas ferramentas permitem- lhe transferir pastas de registo inteiras ou ficheiros específicos para a sua máquina local. Por exemplo, o comando copia o ficheiro de registo principal para a sua pasta actual. Os clientes SFTP, como o FileZilla, fornecem uma interface gráfica para as transferências de arrastar e largar, que pode ser mais conveniente para os utilizadores que preferem não usar a linha de comandos.

Localidades do arquivo de registro e estrutura de diretório

Por padrão, o OpenAPS armazena arquivos de log no diretório . O arquivo de log primário é , que registra os principais eventos do sistema, leituras de sensores, decisões de dosagem de insulina e erros. Além disso, você pode encontrar subdiretórios ou arquivos de log adicionais para componentes específicos:

  • – O log principal do sistema, contendo todos os eventos principais.
  • – Logs do algoritmo oref0, que lida com a lógica de tomada de decisão.
  • – Registros de comunicação específicos da bomba, incluindo comandos enviados e respostas recebidas.
  • – Dados brutos da CGM e eventos de calibração.
  • – Logs from the autossensibilidade detection module, que ajusta as taxas basais com base em padrões observados.

Algumas configurações também podem girar logs automaticamente, criando arquivos compactados como . Estes contêm entradas antigas e podem ser descompactados com para revisão. Compreender o layout do diretório ajuda você a ir diretamente para a fonte de um problema específico em vez de pesquisar através de um único arquivo monolítico.

Compreender a Estrutura dos Registos OpenAPS

Os ficheiros de registo do OpenAPS são ficheiros de texto simples com entradas com data- limite. Cada linha começa normalmente com uma data e hora no formato ISO 8601, seguida de um nível de gravidade (INFO, WARN, ERROR, DEBUG), e depois uma mensagem detalhada que descreve o evento. O nível de detalhe depende da verbosidade de registo configurada, que pode ser ajustada na configuração do sistema.

Datas e fusos horários

Cada entrada de log inclui uma data exata. É fundamental que o relógio do seu equipamento esteja correto e esteja configurado para o fuso horário correto. Os selos de tempo inconsistentes podem dificultar a correlação dos eventos de registro com as tendências reais de glicose ou ações do usuário. O Protocolo de Tempo da Rede (NTP) deve ser ativado para manter o relógio sincronizado automaticamente. Ao revisar os registros, observe sempre o fuso horário usado, especialmente se você estiver comparando dados de log com dados de CGM de um telefone ou outro dispositivo que possa usar um fuso horário diferente.

Níveis de gravidade e o que significam

  • INFO: Mensagens operacionais normais. Estas leituras de sensores de registro, doses de insulina e decisões de algoritmo de rotina. As mensagens INFO são as mais comuns e ajudam você a entender o que o sistema está fazendo em qualquer momento.
  • WARN: Os avisos indicam potenciais problemas que não causaram uma falha, mas podem precisar de atenção. Exemplos incluem uma leitura de sensores que está ligeiramente fora do intervalo esperado, uma comunicação com bombas que requereu uma repetição ou uma calibração que foi ignorada devido a dados insuficientes.
  • ERROR: Os erros representam falhas que impediram o sistema de completar uma ação. Os erros comuns incluem falhas de comunicação da bomba, desconexão do sensor ou tempo limite do algoritmo. Erros devem ser investigados prontamente, pois podem levar a doses de insulina perdidas ou decisões de dosagem incorretas.
  • DEBUG: As mensagens de depuração são altamente detalhadas e normalmente só são habilitadas quando resolvem problemas específicos. Elas podem produzir um grande volume de dados e podem conter detalhes de baixo nível que não são necessários para revisão de rotina.

Rotação e retenção do log

Para evitar que os arquivos de log consumam todo o espaço disponível em disco, o OpenAPS implementa normalmente a rotação de log. Os arquivos de log mais antigos são compactados e eventualmente excluídos após um número configurável de rotações. Por padrão, os registros podem ser mantidos por 7 a 30 dias, dependendo da configuração. Se você precisar reter logs por períodos mais longos para análise de tendência ou auditoria, você pode ajustar as configurações de rotação no arquivo de configuração ou implementar um script de backup personalizado para arquivar logs para armazenamento externo.

Interpretando eventos de registro de chaves

Saber o que procurar em logs transforma dados brutos em insights acionáveis. Aqui estão os tipos de eventos mais importantes e como interpretá-los.

Dados e Calibrações do Sensor

As leituras CGM são a base da tomada de decisão do OpenAPS. As entradas de log para os dados do sensor incluem o valor de glicose, o tempo em que foi gravado e qualquer informação de calibração. Uma entrada típica é como: . Os eventos de calibração também são registrados, mostrando quando um valor de dedo foi digitado e como o sistema ajustou suas leituras de sensores de acordo. Procure padrões de calibrações frequentes ou entradas onde o sistema rejeita uma calibração porque os valores estão muito distantes. Estes podem indicar erros de deriva ou calibração do sensor.

Acontecimentos no parto de insulina

Cada dose de insulina é registrada, incluindo bolus, taxas basais temporárias e entrega basal programada. As entradas incluem o tipo de entrega, a quantidade em unidades e a duração para taxas temporárias. Por exemplo: ou . Ao cruzar estas entradas com tendências de glicose, você pode avaliar se o sistema está respondendo adequadamente a altas e baixas. Inesperadamente grandes doses ou entregas perdidas são facilmente detectadas na sequência de log.

Decisões sobre algoritmos

O algoritmo oref0 toma decisões sobre ajustes basais, recomendações de bolus e alertas altos/baixos com base nos níveis de glicose atuais e previstos. Essas decisões são registradas com texto explicativo que revela o raciocínio por trás de cada ação. Por exemplo: . Ler estas entradas ajuda você a entender se as previsões do sistema se alinham com os resultados reais. As discrepâncias persistentes podem indicar que os parâmetros do modelo precisam de ajuste.

Mensagens de Aviso e Erro

Erros e avisos são as entradas mais acionáveis para a resolução de problemas. Erros de comunicação da bomba estão entre os mais comuns, aparecendo frequentemente como: ou . Estes podem ser causados por interferência de rádio, bateria de bomba baixa, ou distância física entre a plataforma e a bomba. Erros de sensor, tais como , indicam uma perda de conexão CGM que pode levar a dados perdidos e dose potencialmente incorreta. Todos os erros devem ser investigados e resolvidos antes de confiar no sistema para entrega automática de insulina.

Resolução de problemas com os Ficheiros de Registo

Os arquivos de log são a ferramenta primária para diagnosticar problemas em um sistema OpenAPS. Uma abordagem sistemática para análise de log pode identificar rapidamente a causa raiz dos problemas mais comuns.

Processo de Resolução de Problemas Passo a Passo

  1. Identifique o período de tempo do problema. Se você notou um problema em um momento específico, comece puxando entradas de log de todo esse período. Use com um padrão de timestamp para estreitar a pesquisa.
  2. Procurar por ERRO e entradas de aviso. Use para extrair todos os avisos e erros. Estes são os indicadores mais prováveis de um problema.
  3. Verifique se faltam dados. Procure lacunas nas leituras dos sensores ou nas entregas de insulina. Uma lacuna de mais de 5-10 minutos em dados dos sensores, ou uma entrada de logs horárias em falta para o estado da bomba, pode sinalizar uma falha de comunicação.
  4. Correlacionar com o histórico da CGM e da bomba. Comparar entradas de log com o histórico de registro da CGM e bomba da sua bomba de insulina. Discrepâncias entre o que o log relata e o que a bomba mostra podem indicar um log que está fora de sincronia, ou um comando que foi enviado mas não executado.
  5. Reveja as decisões do algoritmo. Para questões com controle de glicose, examine as previsões do algoritmo e os ajustes de insulina resultantes. Procure padrões onde o sistema corre sempre sobrecorreções ou erros.
  6. Verifique se há erros de configuração. Erros que ocorrem imediatamente após uma alteração de configuração são muitas vezes causados por configurações incorretas nas preferências ou perfil da bomba. Revise o registro em torno do tempo da mudança para ver se um parâmetro específico acionou o problema.

Questões comuns e suas assinaturas de log

Doses de insulina perdidas:] Procure sequências onde um bolus ou um basal temporário foi solicitado mas nunca confirmado. O log pode mostrar seguido de sem uma confirmação posterior. Nesses casos, a dose não foi administrada, e o sistema pode não tentar automaticamente. Você deve verificar o histórico da bomba e entregar manualmente a dose esquecida, se necessário.

Gaps de dados do sensor: Se o CGM parar de transmitir, o log irá mostrar seguido de uma gravidade crescente à medida que o gap se alonga. Isto pode ser causado por um sensor morto, um transmissor desconectado ou interferência de rádio. Verifique o estado do sensor e transmissor e substitua o sensor se necessário.

Falhas de comunicação de bomba: As entradas repetidas sugerem um problema físico ou de rádio. Mova o equipamento para mais perto da bomba, substitua as baterias da bomba ou verifique se há fontes de interferência como outros dispositivos sem fio. O log mostrará o número de tentativas de repetição, e se todas as tentativas falharem, o sistema poderá entrar em um modo de segurança.

Autosens sobrepõe: Se você notar que o sistema entrega mais ou menos insulina do que o esperado, verifique os registros de autossensibilidade. Um indica que o sistema detectou um padrão de maior sensibilidade e está ajustando as taxas basais de acordo. Se a proporção parecer extrema ou não corresponder às suas observações, você pode precisar ajustar as configurações de autosens ou fornecer dados mais consistentes.

Otimizando seu sistema OpenAPS usando dados de log

Além de solucionar problemas, os arquivos de log fornecem os dados históricos necessários para ajustar o seu sistema para um melhor controle de glicose. Ao revisar os registros regularmente, você pode identificar padrões e fazer ajustes informados.

Taxas de ajuste fino e perfis de bolo

Comparando resultados esperados com os resultados reais da glicose após as refeições e durante a noite pode revelar se as suas taxas basais e perfis de bolos precisam de ser ajustados. Se vir um padrão de altos após as refeições, verifique o log para ver se as recomendações do bolo do sistema correspondem ao que foi realmente entregue. Procure entradas como e depois verifique se a bomba entregou essa quantidade. Se o sistema recomenda consistentemente mais insulina do que o que é fornecido, as configurações da bomba podem necessitar de atualização. Da mesma forma, as taxas basais durante a noite podem ser refinadas examinando o log para períodos de glicose estável e anotando a taxa basal em vigor. Com o tempo, você pode construir um perfil mais preciso que reduza a necessidade de correções automatizadas.

Otimização de Calibração

As calibrações frequentes ou erráticas podem degradar o desempenho do sistema. Analise os registros para eventos de calibração e observe os valores e horários. Se você vir calibrações que são rejeitadas ou que causam ajustes de sensores grandes, considere calibrar em momentos mais estáveis, como quando a glicose não está subindo ou caindo rapidamente. O registro pode ajudá- lo a identificar os melhores momentos para calibrar para o seu sensor específico e química corporal. Além disso, procure padrões de deriva nas leituras dos sensores. Se o sensor ler consistentemente baixo ou alto em comparação com os dedos, você pode precisar ajustar a curva de calibração ou substituir o sensor.

Ajuste dos Limiares de Alerta

O OpenAPS permite- lhe configurar alertas para os erros de glucose elevada e baixa, dados não detectados e sistema. Ao rever os registos, poderá ver com que frequência estes alertas teriam sido activados e se os limiares são definidos de forma adequada. Se estiver a receber demasiados alarmes falsos, o registo poderá ajudá- lo a identificar as condições que os activam, permitindo- lhe ajustar os limiares para reduzir o ruído sem comprometer a segurança. Por exemplo, se o registo mostrar alertas frequentes [[FLT: 27]] que não se materializem, poderá querer ajustar o horizonte de previsão ou o valor do limiar.

Análise de Desempenho a Longo Prazo

O arquivo de registros ao longo de semanas ou meses permite uma análise de tendência de longo prazo. Você pode rastrear métricas como tempo- em- intervalo, glicose média, alterações na sensibilidade à insulina e confiabilidade do sistema. Ferramentas como ] ou scripts Python personalizados podem analisar arquivos de registro e gerar relatórios sumários. Ao comparar registros entre estações ou mudanças no estilo de vida, você pode ver como seu sistema se adapta e faz ajustes proativos antes que surjam problemas. Isto é especialmente valioso para identificar mudanças graduais na sensibilidade à insulina que de outra forma passariam despercebidas até que causem um problema.

Automatizando análise de log e monitoramento

A leitura manual de arquivos de log todos os dias não é prática. Felizmente, existem várias maneiras de automatizar o monitoramento e alerta de log.

Configurar o Logwatch ou Ferramentas Semelhantes

O Logwatch é uma ferramenta de análise de logs que pode ser configurada para executar diariamente e enviar um resumo de eventos importantes. Ao criar um filtro de Logwatch personalizado para logs do OpenAPS, você poderá receber um relatório diário de avisos, erros e eventos notáveis. Isto permite- lhe ficar informado, sem deslocar manualmente centenas de linhas de entradas de logs. O relatório poderá realçar problemas que necessitam de atenção, como erros de comunicação repetidos ou lacunas de sensores, e fornecer tranquilidade ao sistema que está a correr normalmente.

Criando scripts personalizados Bash ou Python

Para análise mais detalhada, você pode escrever scripts que analisam arquivos de log e geram gráficos ou estatísticas. Por exemplo, um script Python usando pode plotar a entrega de insulina ao longo do tempo, juntamente com as leituras do CGM, tornando fácil correlacionar visualmente eventos. Os scripts também podem calcular métricas como porcentagem de tempo gasto em um intervalo de glicose- alvo, número médio de erros por dia ou a frequência de ajustes de autossens. Ao executar esses scripts periodicamente e armazenar o resultado, você constrói um registro histórico que ajuda a acompanhar o desempenho do sistema e mudanças ao longo do tempo.

Configurar Alertas em Tempo Real

Para eventos críticos, os alertas em tempo real podem ser enviados por e- mail, SMS ou plataformas de mensagens como o Telegram ou o Slack. Um script simples que monitora o arquivo de registro para novos itens de ERROR ou WARN pode desencadear uma notificação quando ocorre um problema. Por exemplo, você pode usar para canalizar novos erros em um script de notificação. Isto garante que você está ciente de problemas assim que eles acontecerem, em vez de descobri- los mais tarde durante uma revisão de registro. Alertas em tempo real são especialmente valiosos para problemas que requerem ação imediata, como uma falha na comunicação com bombas que pode levar à falta de entrega de insulina.

Considerações sobre Segurança e Privacidade

Os ficheiros de registo contêm informações de saúde pessoais altamente sensíveis, incluindo leituras de glucose, doses de insulina, datas e, por vezes, dados de localização se o equipamento tiver o registo GPS activado. A protecção destes dados é essencial por razões legais e pessoais.

Criptografar os Registos em Descanso e em Trânsito

Quando os arquivos de log são armazenados no equipamento, eles devem ser protegidos pela segurança geral do dispositivo, incluindo senhas fortes e sistemas de arquivos criptografados. Ao transferir logs via SCP ou SFTP, os dados são criptografados em trânsito, o que é uma boa prática. Evite transferir logs por protocolos não criptografados como FTP ou HTTP. Se você arquivar logs para um serviço de nuvem ou unidade externa, considere criptografar o arquivo com uma ferramenta como ou usar um arquivo zip criptografado.

Limitando o acesso aos arquivos de registro

Apenas conceda acesso aos arquivos de log a pessoas que precisem, como o usuário do sistema e qualquer cuidador confiável. Evite compartilhar arquivos de log brutos com outros, inclusive em fóruns públicos, a menos que você tenha removido ou anonimizado todas as informações de identificação pessoal. Se você precisar compartilhar trechos de log para ajuda de solução de problemas, revise cuidadosamente o conteúdo e remova quaisquer dados que possam identificá-lo, como seu nome, localização exata ou números de série de bomba.

Políticas de retenção e eliminação

Estabelecer uma política clara para o tempo que você mantém os arquivos de registro e como eles são eliminados quando não mais necessário. Embora os registros de longo prazo sejam valiosos para análise de tendências, eles também representam um risco de privacidade se o dispositivo for perdido ou roubado. Regularmente, purgue os registros antigos que não são mais necessários e assegure que quando você desativar um equipamento, os arquivos de registro sejam apagados com segurança. Usando criptografia de disco completo no equipamento, pode proteger dados em caso de roubo.

Conclusão

Os ficheiros de registo OpenAPS são mais do que apenas um registo de eventos; são uma janela para o funcionamento interno do seu sistema de administração de insulina automatizado. Ao aprender a aceder, ler e analisar estes registos, ganha a capacidade de diagnosticar problemas, otimizar o desempenho e, em última análise, obter um melhor controlo da glucose. As habilidades e técnicas descritas neste guia irão ajudá-lo a passar da resolução de problemas reactiva para a gestão do sistema proactiva, garantindo que o seu equipamento OpenAPS funcione com segurança, fiabilidade e eficácia. Faça uma revisão do registo de uma parte regular da sua rotina e, com o tempo, irá desenvolver uma compreensão intuitiva de como o seu sistema se comporta e como o manter a funcionar no seu melhor.