module ara::log — Log and Trace

Het functionele cluster Log and Trace stelt de centrale infrastructuur voor logging en tracering op het AUTOSAR Adaptive Platform beschikbaar AUTOSAR AP SWS LogAndTrace p. 13. Applicaties en platform-daemons maken logberichten flexibel aan via typeveilige datastromen of via uiterst efficiënte gemodelleerde functieaanroepen met minimale controle-overhead [SWS_LOG_00204]. De berichtfiltering vindt plaats via configureerbare detailniveaus per context, terwijl de doorgifte naar de DLT-backend, ARTI-tools of de lokale console plaatsvindt [SWS_LOG_00021].

meer ›

Het functionele cluster Log and Trace (ara::log) vormt de universele basisinfrastructuur voor gestructureerde logging, diagnose-uitvoer en hardwarenabije tracering in het AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. Elke Logger-instantie vertegenwoordigt een eigen context binnen een proces en registreert zich bij haar ontstaan automatisch bij de centrale logging-backend EXP SWArchitecture p. 57. Naast applicaties binden ook fundamentele platformdiensten zoals Execution Management, Platform Health Management en Persistency de Logger-interface bindend in voor de operationele documentatie AUTOSAR AP EXP SWArchitecture p. 58.

Contextdiagram: inbedding van het cluster Log and Trace als centrale logging- en tracing-infrastructuur voor adaptieve applicaties en functionele platformclusters. Bronnen: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

De module differentieert tussen twee fundamentele interactievormen:

• Ongemodelleerde logging: een fluent-builder-patroon genereert via ernstgraadgerelateerde methoden (zoals LogInfo() of LogError()) een tijdelijk LogStream-object, dat scalaire typen, tekenreeksen, foutcodes en format-modificatoren typeveilig aaneenschakelt en de buffer uiterlijk in de destructor of via Flush() verzendt [SWS_LOG_00067], [SWS_LOG_00039], [SWS_LOG_00262].
• Gemodelleerde logging: via de single-call-interface Logger::Log(id, args...) worden vooraf in het manifest gedeclareerde berichten verzonden, wat bij inactieve drempelwaarde een uiterst efficiënte uitfiltering zonder objectinstantiëring mogelijk maakt [SWS_LOG_00204], PlatformDesign p. 74.

Sequentiediagram: verloop van de ongemodelleerde stream-logging via LogStream tot aan de bufferoverdracht naar de logging-backend. Bronnen: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

Om onnodige rekentijd te vermijden kan het actieve meldingsniveau vooraf via IsEnabled(logLevel) worden geverifieerd of tijdens runtime via SetThreshold(threshold) worden aangepast [SWS_LOG_00070], [SWS_LOG_00255]. Naast de doorgifte naar DLT-kanalen via Ethernet of naar ARTI-tools fungeert bij ontbrekende modelconfiguratie de console als uitwijkvoorziening [SWS_LOG_00021], terwijl de externe diagnose-verbindingsstatus via RegisterConnectionStateHandler asynchroon kan worden bewaakt [SWS_LOG_00098], [SWS_LOG_00205].

meer ›

Systeemarchitectuur en functionele rol van Log and Trace

Het functionele cluster Log and Trace (ara::log) vormt het centrale, transversale subsysteem voor de gestandaardiseerde registratie, doorgifte en filtering van diagnose-, tracing- en logmeldingen op het AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. De programmeerinterface Logger stelt de uniforme C++-platform-API beschikbaar, die zowel door applicatiespecifieke processen (Adaptive Applications) als door de fundamentele functionele platformclusters als basisinfrastructuur wordt geconsumeerd AUTOSAR AP EXP SWArchitecture p. 58. Tot deze consumerende systeem-daemons behoren onder meer Execution Management voor de documentatie van de proceslevenscyclus AUTOSAR AP EXP SWArchitecture p. 50, Platform Health Management voor toezicht op de toestand AUTOSAR AP SWS PlatformHealthManagement p. 16, Time Synchronization voor uiterst precieze tijdsreferenties AUTOSAR AP SWS TimeSynchronization p. 17 en Update and Configuration Management tijdens software-updates AUTOSAR AP EXP SWArchitecture p. 141.

Architectonisch kapselt elke logger-instantie een unieke context (Context ID) binnen een applicatie- of procesbereik in, waarbij deze context zich bij het aanmaken automatisch bij de logging-backend registreert en bij het afsluiten van de applicatie automatisch wordt afgemeld EXP SWArchitecture p. 57. De logging-backend geeft geformatteerde meldingen door aan geprojecteerde uitvoerkanalen (bijv. DLT-protocolputten via Ethernet conform het Machine-manifest) of aan lokale buffers, waarbij bij een ontbrekend deploymentmodel standaard wordt teruggevallen op de besturingssysteemconsole [SWS_LOG_00021], SWS LogAndTrace p. 21. Bovendien stelt een ontkoppelde adapterarchitectuur het besturingssysteem (POSIX/OS) in staat om interne kernel- en scheduling-statistieken via de AUTOSAR Run-Time Interface (ARTI) gesynchroniseerd met de meldingen van ara::log beschikbaar te stellen AUTOSAR AP SWS OperatingSystemInterface p. 21.

Contextdiagram: inbedding van het cluster Log and Trace als centrale logging- en tracing-infrastructuur voor adaptieve applicaties en functionele platformclusters. Bronnen: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

Instantiëring, contextbeheer en drempelwaardebesturing

Het beschikbaar stellen van een logger-context vindt plaats via de factoryfuncties ara::log::CreateLogger, aangezien de standaardconstructor van de klasse Logger is verwijderd [SWS_LOG_00259]. Applicaties kunnen loggers ofwel programmatisch onder opgave van een context-ID (ctxId), een beschrijving (ctxDescription) en optioneel een standaard-loglevel instantiëren [SWS_LOG_00021], [SWS_LOG_00263], ofwel instantiegebaseerd via een modelelement door middel van ara::core::InstanceSpecifier afleiden [SWS_LOG_00256]. De destructor van Logger handelt het afmelden thread-veilig af [SWS_LOG_00260].

De granulariteit en prioriteit van meldingen wordt door de enumeratie LogLevel hiërarchisch weergegeven: kFatal (onherstelbare systeemfout), kError (fout met functionele belemmering), kWarn (waarschuwing bij gevaar voor beoogd gedrag), kInfo (algemene bedrijfsinformatie), kDebug (gedetailleerde diagnose) en kVerbose (uitvoerige tracering) [SWS_LOG_00018], ManifestSpecification p. 416. Voor runtime-optimalisatie kunnen rekenintensieve voorbereidingen van loggegevens worden vermeden door vooraf via de bevraging IsEnabled(logLevel) te controleren of het desbetreffende loglevel op de context momenteel actief is geschakeld [SWS_LOG_00070]. De actieve meldingsdrempel van een logger-instantie kan desgewenst tijdens runtime via SetThreshold(threshold) dynamisch worden aangepast [SWS_LOG_00255].

Ongemodelleerde logging en streamgebaseerde berichtcompositie

Voor ongemodelleerde meldingen stelt ara::log een op het builder-ontwerppatroon geïnspireerde fluent-interface beschikbaar PlatformDesign p. 74. De instap vindt plaats via ernstgraadspecifieke lidfuncties van de Logger-instantie, te weten LogFatal(), LogError(), LogWarn(), LogInfo(), LogDebug() en LogVerbose(), of via WithLevel(logLevel), die een tijdelijk, lichtgewicht LogStream-object retourneren [SWS_LOG_00064], [SWS_LOG_00065], [SWS_LOG_00066], [SWS_LOG_00067], [SWS_LOG_00068], [SWS_LOG_00069], [SWS_LOG_00131]. Gegevens worden vervolgens via de typeveilige stream-invoegoperator (operator<<) aaneengeschakeld aan de interne berichtbuffer toegevoegd [SWS_LOG_00040].

De stream-interface ondersteunt een breed scala aan native C++- en AUTOSAR-typen zonder handmatige opmaakfouten:

• Geheeltallige typen (met en zonder teken van 8 tot 64 bit) evenals booleaanse waarden [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].
• Drijvendekommatypen met enkele en dubbele precisie (float, double) [SWS_LOG_00049], [SWS_LOG_00050].
• Nul-getermineerde UTF-8-tekenreeksen en ara::core::StringView [SWS_LOG_00051], [SWS_LOG_00062].
• Specifieke platformtypen zoals LogLevel in tekstvorm [SWS_LOG_00063], foutobjecten ara::core::ErrorCode [SWS_LOG_00124], tijdsduren std::chrono::duration [SWS_LOG_00125], modelreferenties ara::core::InstanceSpecifier [SWS_LOG_00126], ruwe pointers [SWS_LOG_00127] en bytesequenties via ara::core::Span<const ara::core::Byte> [SWS_LOG_00128].

Metadata en formattering kunnen nauwkeurig worden gestuurd: via WithLocation(file, line) wordt de broncode-oorsprong vastgelegd [SWS_LOG_00129], WithTag(tag) voegt functionele trefwoorden toe [SWS_LOG_00132], en WithPrivacy(value) legt een vertrouwelijkheidsniveau vast via de onderste 8 bits [SWS_LOG_00258]. Geformatteerde argumenten met naam en fysische eenheid worden via de hulp-template Arg ingekapseld [SWS_LOG_00201], [SWS_LOG_00203], ondersteund door de formatteringshulpmiddelen Dflt, Hex, Dec, Oct, Bin, DecFloat, EngFloat, HexFloat en AutoFloat uit de enumeratie Fmt [SWS_LOG_00206], [SWS_LOG_00208], [SWS_LOG_00209], [SWS_LOG_00211], [SWS_LOG_00217], [SWS_LOG_00225], [SWS_LOG_00226].

Wat betreft de levenscyclus is LogStream een move-only-object: copy-constructor en copy-toekenningsoperator zijn verwijderd [SWS_LOG_00174], [SWS_LOG_00175], terwijl de move-constructor ter ondersteuning van Return Value Optimization (RVO) is gedeclareerd [SWS_LOG_00176]; de move-toekenningsoperator is verwijderd [SWS_LOG_00177]. De bufferinhoud wordt bij het verlaten van het geldigheidsbereik via de destructor ~LogStream() automatisch naar het logging-framework verzonden [SWS_LOG_00262]. Indien een LogStream-object binnen hetzelfde geldigheidsbereik achtereenvolgens voor meerdere meldingen moet worden gebruikt, moet de bufferoverdracht expliciet via Flush() worden geactiveerd, waardoor een nieuwe meldingsstroom wordt geïnitialiseerd [SWS_LOG_00039]. Interpretatie: het interne bufferbeheer van LogStream zal vermoedelijk na aanroep van Flush() de buffer voor opeenvolgende streaming-operatoren binnen hetzelfde bereik legen en opnieuw initialiseren, zonder dat vernietiging van de objectidentiteit vereist is. Vraag (open)

Sequentiediagram: verloop van de ongemodelleerde stream-logging via LogStream tot aan de bufferoverdracht naar de logging-backend. Bronnen: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

Gemodelleerde logging en vertakking naar ARTI-tracing

In tegenstelling tot de stapsgewijze opbouw van ongemodelleerde berichten definieert ara::log voor in het manifest gemodelleerde berichten een uiterst efficiënte single-call-interface via Logger::Log(id, args...) en Logger::LogWith(attrs, msgId, params...) [SWS_LOG_00204], [SWS_LOG_00133]. Alle argumenten worden in een enkele functieaanroep doorgegeven, waardoor de runtime-overhead in het geval van onderdrukte meldingen tot een minimum wordt beperkt: direct na de parameteroverdracht controleert een enkele voorwaarde de drempelwaarde en keert onmiddellijk terug indien het geconfigureerde loglevel niet is bereikt PlatformDesign p. 74.

Binnen de aanroep van Log splitst het verwerkingspad zich: naast het klassieke pad van DLT-serialisatie (buildDltMessage(), filtering via logmasker en overdracht aan de put) bestaat er een specifiek pad voor hardwarenabije tracering via de AUTOSAR Run-Time Interface (ARTI) door middel van TraceArti(msg_id, params...) [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42. Vermoedelijk wordt het doorschakelen naar TraceArti via statische templatespecialisaties tijdens compileertijd opgelost om de vereiste minimale runtime-overhead te garanderen. Vraag (open) De ARTI-backend filtert volgens eigen criteria op basis van de MsgId en omzeilt de DLT-buffering volledig, wat realtime-kritische tracering mogelijk maakt zonder verstoring van het reguliere logging-subsysteem AUTOSAR AP SWS LogAndTrace p. 42.

Activiteitendiagram: controle- en filterstroom bij het verzenden van gemodelleerde berichten tussen DLT-backend en ARTI-tracing. Bronnen: [SWS_LOG_00204], [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42, PlatformDesign p. 74

Client-verbindingsbewaking en diagnoseaansluiting

Log and Trace biedt niet alleen lokale uitvoerkanalen, maar bewaakt ook de toestand van externe diagnose-clients (bijv. DLT-viewer via Ethernet), gerepresenteerd door de enumeratie ClientState: kUnknown (-1, DLT-backend nog niet gereed), kNotConnected (geen externe client gedetecteerd) en kConnected (verbinding met externe client actief) [SWS_LOG_00098]. Hierdoor kunnen applicaties bewerkelijke tracering koppelen aan de fysieke aanwezigheid van een analysetool.

Voor asynchrone toestandsbewaking registreren applicaties een callbackfunctie via ara::log::RegisterConnectionStateHandler met behulp van de functie-aliasing ConnectionStateHandler = std::function<void(ClientState)> [SWS_LOG_00205], [SWS_LOG_00265]. Het logging-framework ondersteunt hierbij exact één actieve handler-registratie: een hernieuwde aanroep van RegisterConnectionStateHandler overschrijft een eerder geïnstalleerde callback zonder beperking [SWS_LOG_00205].

Toestandsdiagram: toestandsovergangen van de externe client conform ClientState. Bronnen: [SWS_LOG_00098], [SWS_LOG_00205], [SWS_LOG_00265]

Gedrag in het foutgeval

De module dwingt functionele veiligheid en robuustheid primair af door statische typecontroles tijdens compileertijd en strikte exceptiegaranties:

• Compileertijdfouten (ill-formed): de aanroep van Logger::Log(id, args...) is ongeldig (ill-formed) wanneer de doorgegeven argumenten niet exact overeenkomen met de in het manifest gedeclareerde berichtsignatuur [SWS_LOG_00204]. Evenzo leidt het gebruik van Arg() met typen die noch rekenkundig noch booleaans zijn, noch converteerbaar naar StringView resp. Span<const Byte>, tot een compileerafbreek [SWS_LOG_00201]. De functie WithPrivacy(value) dwingt bovendien af dat het parametertype een geheel getal of een enumeratie is [SWS_LOG_00258].
• Constructie- en toekenningsverboden: om onbedoelde bufferduplicaties of resourceconflicten uit te sluiten, zijn de copy-constructor en de copy-toekenningsoperator van LogStream evenals de move-toekenningsoperator expliciet verwijderd [SWS_LOG_00174], [SWS_LOG_00175], [SWS_LOG_00177].
• Runtime-integriteit bij instantiëring: faalt de resolutie van de ara::core::InstanceSpecifier in het machine- of applicatiemodel bij CreateLogger(is) of verwijst deze niet naar een toelaatbaar modelelement, dan meldt het systeem een InstanceSpecifierMappingIntegrityViolation [SWS_LOG_00256].
• Uitwijkveilige fallback-putten: is er tijdens runtime geen deploymentmodel of geen netwerkverbinding met de DLT-dienst beschikbaar, dan schakelt het framework automatisch over naar de lokale console als standaard uitvoerput, zodat er geen diagnose-informatie geruisloos verloren gaat [SWS_LOG_00021], [SWS_LOG_00263]. Bij uitvoer van een core::ErrorCode op de console vindt de weergave plaats via de domeinnaam en de numerieke foutwaarde [SWS_LOG_00124].
• Exceptieveiligheid: alle streaming-operatoren, drempelwaardebevragingen en de destructor ~LogStream() zijn gedeclareerd als noexcept, om te waarborgen dat de logging op geen enkel moment onafgehandelde excepties naar aanroepende functieblokken propageert [SWS_LOG_00040], [SWS_LOG_00070], [SWS_LOG_00262]; de destructor ~Logger() is daarentegen formeel niet als noexcept gespecificeerd [SWS_LOG_00260].

Verdere gedetailleerde bewijzen

De architectuur en het gedrag van de module Log and Trace zijn verankerd in de volgende referentiepunten van de AUTOSAR-specificatie:

• Cluster-interfacespecificatie: de normatieve C++-signaturen, stream-operatoren en contextmethoden van Logger en LogStream zijn gedefinieerd in de specificatie van Log and Trace [SWS_LOG_00021], [SWS_LOG_00039], [SWS_LOG_00064], [SWS_LOG_00204], AUTOSAR AP SWS LogAndTrace p. 13.
• Platformdesign en performance: de architectonische vergelijking tussen het builder-patroon en de uiterst efficiënte single-call-aanroep voor gemodelleerde berichten wordt uiteengezet in het Platform Design PlatformDesign p. 74.
• Platformbrede afhankelijkheden: het bindende gebruik van de Logger-interface door functionele platformclusters wordt bijgehouden in de respectieve architectuurdocumenten AUTOSAR AP EXP SWArchitecture p. 58, AUTOSAR AP EXP SWArchitecture p. 50, AUTOSAR AP SWS PlatformHealthManagement p. 16.
• Manifest- en deploymentmodel: de configuratie van DLT-logkanalen, procestoewijzingen en machine-eindpunten is geregeld in de manifestspecificatie SWS LogAndTrace p. 21, ManifestSpecification p. 416.
• Besturingssysteemadapters en ARTI: de koppeling van native besturingssysteem-tracebuffers aan ara::log en de hardwarenabije registratie via TraceArti zijn gespecificeerd in de OSI- en trace-architectuur [SWS_LOG_20000], AUTOSAR AP SWS OperatingSystemInterface p. 21, AUTOSAR AP SWS LogAndTrace p. 42.