módulo ara::log — Log and Trace

O cluster funcional Log and Trace disponibiliza a infraestrutura central para o registro em log e o rastreamento na AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. Aplicações e daemons de plataforma criam mensagens de log de forma flexível através de fluxos de dados com segurança de tipos ou através de chamadas de função modeladas altamente eficientes com mínimo overhead de verificação [SWS_LOG_00204]. A filtragem de mensagens ocorre por meio de níveis de detalhamento configuráveis por contexto, enquanto o encaminhamento é feito para o backend de DLT, ferramentas ARTI ou para o console local [SWS_LOG_00021].

mais ›

O cluster funcional Log and Trace (ara::log) constitui a infraestrutura básica universal para registro em log estruturado, saídas de diagnóstico e rastreamento de baixo nível na AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. Cada instância de Logger representa um contexto próprio dentro de um processo e se registra automaticamente no backend central de registro em log no momento de sua criação EXP SWArchitecture p. 57. Além das aplicações, serviços básicos da plataforma como Execution Management, Platform Health Management e Persistency também integram obrigatoriamente a interface Logger para documentação de operação AUTOSAR AP EXP SWArchitecture p. 58.

Diagrama de contexto: incorporação do cluster Log and Trace como infraestrutura central de registro em log e tracing para aplicações adaptativas e clusters funcionais de plataforma. Fontes: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

O módulo diferencia duas formas fundamentais de interação:

• Registro em log não modelado: Um padrão Fluent Builder gera, através de métodos relacionados ao nível de severidade (como LogInfo() ou LogError()), um objeto temporário LogStream que encadeia com segurança de tipos escalares, cadeias de caracteres, códigos de erro e modificadores de formato, transmitindo o buffer o mais tardar no destrutor ou através de Flush() [SWS_LOG_00067], [SWS_LOG_00039], [SWS_LOG_00262].
• Registro em log modelado: Através da interface de chamada única Logger::Log(id, args...), são emitidas mensagens declaradas previamente no manifesto, o que permite uma filtragem altamente eficiente sem instanciação de objetos quando o limite está inativo [SWS_LOG_00204], PlatformDesign p. 74.

Diagrama de sequência: fluxo do registro em log por stream não modelado através de LogStream até a transmissão do buffer para o backend de registro em log. Fontes: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

Para evitar tempo de processamento desnecessário, o nível de notificação ativo pode ser previamente verificado mediante IsEnabled(logLevel) ou ajustado em tempo de execução via SetThreshold(threshold) [SWS_LOG_00070], [SWS_LOG_00255]. Além do encaminhamento para canais DLT através de Ethernet ou para ferramentas ARTI, o console atua como contingência no caso de ausência de configuração de modelo [SWS_LOG_00021], enquanto o status da conexão de diagnóstico externa pode ser monitorado de forma assíncrona através de RegisterConnectionStateHandler [SWS_LOG_00098], [SWS_LOG_00205].

mais ›

Arquitetura de sistema e papel funcional do Log and Trace

O cluster funcional Log and Trace (ara::log) forma o subsistema transversal central para a captura, o encaminhamento e a filtragem padronizados de mensagens de diagnóstico, tracing e registro em log na AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. A interface de programação Logger disponibiliza a API C++ unificada da plataforma, a qual é consumida como infraestrutura básica tanto por processos específicos da aplicação (Adaptive Applications) quanto pelos clusters funcionais básicos da plataforma AUTOSAR AP EXP SWArchitecture p. 58. Entre esses daemons de sistema consumidores encontram-se o Execution Management para a documentação do ciclo de vida dos processos AUTOSAR AP EXP SWArchitecture p. 50, o Platform Health Management para o monitoramento de estado AUTOSAR AP SWS PlatformHealthManagement p. 16, o Time Synchronization para referências temporais de alta precisão AUTOSAR AP SWS TimeSynchronization p. 17, bem como o Update and Configuration Management durante atualizações de software AUTOSAR AP EXP SWArchitecture p. 141.

Arquiteturalmente, cada instância de logger encapsula um contexto unívoco (Context ID) dentro de um domínio de aplicação ou de processo, sendo que esse contexto se registra de forma autônoma no backend de registro em log no momento da criação e é desregistrado automaticamente no desligamento da aplicação EXP SWArchitecture p. 57. O backend de registro em log encaminha mensagens formatadas para canais de saída projetados (p. ex., destinos de protocolo DLT via Ethernet de acordo com o Machine Manifest) ou para buffers locais, recorrendo-se por padrão ao console do sistema operacional na ausência de um modelo de implantação [SWS_LOG_00021], SWS LogAndTrace p. 21. Além disso, uma arquitetura de adaptador desacoplada permite ao sistema operacional (POSIX/OS) disponibilizar métricas internas do kernel e de escalonamento através da AUTOSAR Run-Time Interface (ARTI) sincronizadas com as mensagens de ara::log AUTOSAR AP SWS OperatingSystemInterface p. 21.

Diagrama de contexto: incorporação do cluster Log and Trace como infraestrutura central de registro em log e tracing para aplicações adaptativas e clusters funcionais de plataforma. Fontes: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

Instanciação, gestão de contexto e controle de limite

A disponibilização de um contexto de logger ocorre através das funções de fábrica ara::log::CreateLogger, uma vez que o construtor padrão da classe Logger está excluído [SWS_LOG_00259]. As aplicações podem instanciar loggers programaticamente, indicando um ID de contexto (ctxId), uma descrição (ctxDescription) e opcionalmente um nível de log padrão [SWS_LOG_00021], [SWS_LOG_00263], ou derivá-los com base em instâncias através de um elemento de modelo mediante ara::core::InstanceSpecifier [SWS_LOG_00256]. O destrutor de Logger realiza o desregistro de forma thread-safe [SWS_LOG_00260].

A granularidade e a prioridade das mensagens são mapeadas hierarquicamente pela enumeração LogLevel: kFatal (erro de sistema irrecuperável), kError (erro com degradação funcional), kWarn (aviso com comportamento nominal em risco), kInfo (informação operacional geral), kDebug (diagnóstico detalhado) e kVerbose (rastreamento minucioso) [SWS_LOG_00018], ManifestSpecification p. 416. Para otimização do tempo de execução, preparações de dados de log computacionalmente intensivas podem ser evitadas verificando previamente, através da consulta IsEnabled(logLevel), se o respectivo nível de log está atualmente ativo no contexto [SWS_LOG_00070]. O limite de notificação ativo de uma instância de logger pode, se necessário, ser ajustado dinamicamente em tempo de execução através de SetThreshold(threshold) [SWS_LOG_00255].

Registro em log não modelado e composição de mensagens baseada em streams

Para mensagens não modeladas, o ara::log disponibiliza uma interface fluente baseada no padrão de projeto Builder PlatformDesign p. 74. O ponto de entrada ocorre através de funções de membro específicas de severidade da instância Logger, nomeadamente LogFatal(), LogError(), LogWarn(), LogInfo(), LogDebug() e LogVerbose(), ou através de WithLevel(logLevel), as quais retornam um objeto LogStream temporário e leve [SWS_LOG_00064], [SWS_LOG_00065], [SWS_LOG_00066], [SWS_LOG_00067], [SWS_LOG_00068], [SWS_LOG_00069], [SWS_LOG_00131]. Em seguida, os dados são anexados ao buffer interno de mensagens de forma encadeada através do operador de inserção de fluxo com segurança de tipos (operator<<) [SWS_LOG_00040].

A interface de stream suporta uma ampla gama de tipos nativos de C++ e AUTOSAR sem erros manuais de formatação:

• Tipos inteiros (com e sem sinal, de 8 a 64 bits), bem como valores booleanos [SWS_LOG_00040], [SWS_LOG_00041], [SWS_LOG_00042], [SWS_LOG_00043], [SWS_LOG_00044], [SWS_LOG_00045], [SWS_LOG_00046], [SWS_LOG_00047], [SWS_LOG_00048].
• Tipos de ponto flutuante de precisão simples e dupla (float, double) [SWS_LOG_00049], [SWS_LOG_00050].
• Cadeias de caracteres UTF-8 terminadas em nulo e ara::core::StringView [SWS_LOG_00051], [SWS_LOG_00062].
• Tipos de plataforma específicos, como LogLevel em formato textual [SWS_LOG_00063], objetos de erro ara::core::ErrorCode [SWS_LOG_00124], intervalos de tempo std::chrono::duration [SWS_LOG_00125], referências de modelo ara::core::InstanceSpecifier [SWS_LOG_00126], ponteiros brutos [SWS_LOG_00127] e sequências de bytes via ara::core::Span<const ara::core::Byte> [SWS_LOG_00128].

Metadados e formatações podem ser controlados com precisão: através de WithLocation(file, line), registra-se a origem do código-fonte [SWS_LOG_00129], WithTag(tag) adiciona palavras-chave funcionais [SWS_LOG_00132], e WithPrivacy(value) define um nível de confidencialidade através dos 8 bits inferiores [SWS_LOG_00258]. Argumentos formatados com nome e unidade física são encapsulados através do template auxiliar Arg [SWS_LOG_00201], [SWS_LOG_00203], suportado pelos recursos auxiliares de formatação Dflt, Hex, Dec, Oct, Bin, DecFloat, EngFloat, HexFloat e AutoFloat da enumeração Fmt [SWS_LOG_00206], [SWS_LOG_00208], [SWS_LOG_00209], [SWS_LOG_00211], [SWS_LOG_00217], [SWS_LOG_00225], [SWS_LOG_00226].

No que diz respeito ao ciclo de vida, o LogStream é um objeto move-only: o construtor de cópia e o operador de atribuição por cópia estão excluídos [SWS_LOG_00174], [SWS_LOG_00175], enquanto o construtor de movimento está declarado para suportar Return Value Optimization (RVO) [SWS_LOG_00176]; o operador de atribuição por movimento está excluído [SWS_LOG_00177]. O conteúdo do buffer é enviado automaticamente para o framework de log através do destrutor ~LogStream() ao sair do escopo [SWS_LOG_00262]. Se um objeto LogStream for reutilizado para várias mensagens sucessivas dentro do mesmo escopo, a transmissão do buffer deve ser disparada explicitamente via Flush(), inicializando um novo fluxo de mensagens [SWS_LOG_00039]. Interpretação: supõe-se que, após a chamada de Flush(), a gestão interna de buffer de LogStream esvazie e reinicialize o buffer para operadores de streaming subsequentes no mesmo escopo, sem que seja necessária a destruição da identidade do objeto. Pergunta (aberta)

Diagrama de sequência: fluxo do registro em log por stream não modelado através de LogStream até a transmissão do buffer para o backend de registro em log. Fontes: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

Registro em log modelado e ramificação para tracing ARTI

Ao contrário da construção progressiva de mensagens não modeladas, o ara::log define uma interface de chamada única altamente eficiente através de Logger::Log(id, args...) e Logger::LogWith(attrs, msgId, params...) para mensagens modeladas no manifesto [SWS_LOG_00204], [SWS_LOG_00133]. Todos os argumentos são passados em uma única chamada de função, o que reduz ao mínimo o overhead de tempo de execução no caso de mensagens suprimidas: diretamente após a passagem de parâmetros, uma única condição verifica o limite e retorna imediatamente se o nível de log configurado não for atingido PlatformDesign p. 74.

Dentro da chamada de Log, o fluxo de processamento se divide: além do fluxo clássico de serialização DLT (buildDltMessage(), filtragem via máscara de log e entrega ao destino), existe um fluxo dedicado para rastreamento de baixo nível através da AUTOSAR Run-Time Interface (ARTI) mediante TraceArti(msg_id, params...) [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42. Provavelmente, o encaminhamento para TraceArti é resolvido em tempo de compilação por meio de especializações estáticas de template, a fim de garantir o overhead de tempo de execução mínimo exigido. Pergunta (aberta) O backend ARTI filtra segundo critérios próprios com base no MsgId e ignora completamente o buffer DLT, permitindo um tracing crítico em tempo real sem interferir no subsistema de log regular AUTOSAR AP SWS LogAndTrace p. 42.

Diagrama de atividades: fluxo de controle e filtragem no envio de mensagens modeladas entre o backend de DLT e o tracing ARTI. Fontes: [SWS_LOG_00204], [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42, PlatformDesign p. 74

Monitoramento de conexão de clientes e integração de diagnóstico

O Log and Trace não apenas disponibiliza canais de saída locais, mas também monitora o estado de clientes de diagnóstico externos (p. ex., DLT Viewer via Ethernet), representado pela enumeração ClientState: kUnknown (-1, backend de DLT ainda não pronto), kNotConnected (nenhum cliente remoto detectado) e kConnected (conexão com cliente externo ativa) [SWS_LOG_00098]. Isso permite que as aplicações vinculem um tracing dispendioso à presença física de uma ferramenta de análise.

Para o rastreamento assíncrono de estados, as aplicações registam uma função de retorno através de ara::log::RegisterConnectionStateHandler recorrendo ao aliasing de funções ConnectionStateHandler = std::function<void(ClientState)> [SWS_LOG_00205], [SWS_LOG_00265]. O framework de logging suporta exatamente um registo de handler ativo: uma nova chamada a RegisterConnectionStateHandler sobrescreve sem restrições um callback instalado anteriormente [SWS_LOG_00205].

Diagrama de estados: transições de estado do cliente externo de acordo com o ClientState. Fontes: [SWS_LOG_00098], [SWS_LOG_00205], [SWS_LOG_00265]

Comportamento em caso de erro

O módulo impõe segurança funcional e robustez primariamente através de verificações estáticas de tipos em tempo de compilação e de garantias estritas de exceção:

• Erros em tempo de compilação (ill-formed): A chamada a Logger::Log(id, args...) é inválida (ill-formed) se os argumentos passados não coincidirem exatamente com a assinatura da mensagem declarada no manifesto [SWS_LOG_00204]. Do mesmo modo, a utilização de Arg() com tipos que não sejam aritméticos, booleanos ou convertíveis para StringView ou Span<const Byte> resulta na interrupção da compilação [SWS_LOG_00201]. A função WithPrivacy(value) impõe ainda que o tipo do parâmetro seja um tipo inteiro ou uma enumeração [SWS_LOG_00258].
• Proibições de construção e atribuição: Para excluir duplicações inadvertidas de buffers ou conflitos de recursos, o construtor de cópia e o operador de atribuição por cópia de LogStream, bem como o operador de atribuição por movimento, estão explicitamente eliminados [SWS_LOG_00174], [SWS_LOG_00175], [SWS_LOG_00177].
• Integridade em tempo de execução na instanciação: Se a resolução do ara::core::InstanceSpecifier no modelo de máquina ou de aplicação falhar em CreateLogger(is) ou se este não referenciar um elemento de modelo válido, o sistema reporta um InstanceSpecifierMappingIntegrityViolation [SWS_LOG_00256].
• Recetores de fallback tolerantes a falhas: Se em tempo de execução não estiver disponível nenhum modelo de deployment ou ligação de rede ao serviço DLT, o framework comuta automaticamente para a consola local como recetor de saída padrão, garantindo que nenhuma informação de diagnóstico seja perdida silenciosamente [SWS_LOG_00021], [SWS_LOG_00263]. Ao emitir um core::ErrorCode na consola, a representação é feita através do nome de domínio e do valor numérico de erro [SWS_LOG_00124].
• Segurança de exceções: Todos os operadores de streaming, consultas de limiar e o destrutor ~LogStream() estão declarados como noexcept, para assegurar que o registo de log nunca propague exceções não tratadas para blocos funcionais chamadores [SWS_LOG_00040], [SWS_LOG_00070], [SWS_LOG_00262]; em contrapartida, o destrutor ~Logger() formalmente não está especificado como noexcept [SWS_LOG_00260].

Evidências mais detalhadas

A arquitetura e o comportamento do módulo Log and Trace estão fundamentados nas seguintes referências da especificação AUTOSAR:

• Especificação de interface do cluster: As assinaturas C++ normativas, os operadores de stream e os métodos de contexto de Logger e LogStream estão definidos na especificação de Log and Trace [SWS_LOG_00021], [SWS_LOG_00039], [SWS_LOG_00064], [SWS_LOG_00204], AUTOSAR AP SWS LogAndTrace p. 13.
• Design da plataforma e desempenho: A comparação arquitetural entre o padrão Builder e a chamada de invocação única (single-call) de alta eficiência para mensagens modeladas é apresentada no Platform Design PlatformDesign p. 74.
• Dependências em toda a plataforma: A utilização obrigatória da interface Logger por clusters funcionais da plataforma é documentada nos respetivos documentos de arquitetura AUTOSAR AP EXP SWArchitecture p. 58, AUTOSAR AP EXP SWArchitecture p. 50, AUTOSAR AP SWS PlatformHealthManagement p. 16.
• Modelo de manifesto e de deployment: A configuração de canais de log DLT, mapeamentos de processos e endpoints de máquinas está regulamentada na especificação do manifesto SWS LogAndTrace p. 21, ManifestSpecification p. 416.
• Adaptadores de sistema operativo e ARTI: A ligação de buffers de trace nativos do sistema operativo a ara::log e a aquisição de baixo nível via TraceArti estão especificadas na arquitetura de OSI e trace [SWS_LOG_20000], AUTOSAR AP SWS OperatingSystemInterface p. 21, AUTOSAR AP SWS LogAndTrace p. 42.