module ara::log — Log and Trace

The functional cluster Log and Trace provides the central infrastructure for logging and tracing on the AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. Applications and platform daemons create log messages flexibly via type-safe data streams or via highly efficient modeled function calls with minimal checking overhead [SWS_LOG_00204]. Message filtering is performed via configurable detail levels per context, while forwarding takes place to the DLT backend, ARTI tools, or the local console [SWS_LOG_00021].

more ›

The functional cluster Log and Trace (ara::log) represents the universal base infrastructure for structured logging, diagnostic output, and hardware-oriented tracing in the AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. Each Logger instance represents its own context within a process and automatically registers with the central logging backend upon creation EXP SWArchitecture p. 57. In addition to applications, foundational platform services such as Execution Management, Platform Health Management, and Persistency also mandatory integrate the Logger interface for operational documentation AUTOSAR AP EXP SWArchitecture p. 58.

Context diagram: Embedding of the Log and Trace cluster as the central logging and tracing infrastructure for adaptive applications and functional platform clusters. Sources: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

The module differentiates between two fundamental forms of interaction:

• Unmodeled logging: A fluent builder pattern creates a temporary LogStream object via severity-specific methods (such as LogInfo() or LogError()), which type-safely chains scalar types, strings, error codes, and format modifiers, and transmits the buffer at the latest in the destructor or via Flush() [SWS_LOG_00067], [SWS_LOG_00039], [SWS_LOG_00262].
• Modeled logging: Via the single-call interface Logger::Log(id, args...), messages previously declared in the manifest are emitted, which enables highly efficient filtering out without object instantiation when the threshold is inactive [SWS_LOG_00204], PlatformDesign p. 74.

Sequence diagram: Sequence of unmodeled stream logging via LogStream up to buffer transmission to the logging backend. Sources: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

To avoid unnecessary computation time, the active reporting level can be verified in advance using IsEnabled(logLevel) or adjusted at runtime via SetThreshold(threshold) [SWS_LOG_00070], [SWS_LOG_00255]. Besides forwarding to DLT channels via Ethernet or to ARTI tools, the console acts as a fallback if model configuration is missing [SWS_LOG_00021], while the external diagnostic connection state can be monitored asynchronously via RegisterConnectionStateHandler [SWS_LOG_00098], [SWS_LOG_00205].

more ›

System Architecture and Functional Role of Log and Trace

The functional cluster Log and Trace (ara::log) forms the central, cross-cutting subsystem for the standardized collection, forwarding, and filtering of diagnostic, tracing, and log messages on the AUTOSAR Adaptive Platform AUTOSAR AP SWS LogAndTrace p. 13. The programming interface Logger provides the unified C++ platform API, which is consumed as base infrastructure both by application-specific processes (Adaptive Applications) and by the foundational functional platform clusters AUTOSAR AP EXP SWArchitecture p. 58. These consuming system daemons include Execution Management for process lifecycle documentation AUTOSAR AP EXP SWArchitecture p. 50, Platform Health Management for state monitoring AUTOSAR AP SWS PlatformHealthManagement p. 16, Time Synchronization for high-precision time references AUTOSAR AP SWS TimeSynchronization p. 17, and Update and Configuration Management during software updates AUTOSAR AP EXP SWArchitecture p. 141.

Architecturally, each logger instance encapsulates a unique context (Context ID) within an application or process scope, whereby this context registers itself automatically with the logging backend upon creation and is automatically deregistered when the application shuts down EXP SWArchitecture p. 57. The logging backend forwards formatted messages to configured output channels (e.g., DLT protocol sinks via Ethernet according to the machine manifest) or to local buffers, falling back to the operating system console by default if a deployment model is missing [SWS_LOG_00021], SWS LogAndTrace p. 21. In addition, a decoupled adapter architecture allows the operating system (POSIX/OS) to provide internal kernel and scheduling metrics via the AUTOSAR Run-Time Interface (ARTI) synchronized with the messages of ara::log AUTOSAR AP SWS OperatingSystemInterface p. 21.

Context diagram: Embedding of the Log and Trace cluster as the central logging and tracing infrastructure for adaptive applications and functional platform clusters. Sources: AUTOSAR AP SWS LogAndTrace p. 13, AUTOSAR AP EXP SWArchitecture p. 58, SWS LogAndTrace p. 21, AUTOSAR AP SWS OperatingSystemInterface p. 21

Instantiation, Context Management, and Threshold Control

The provisioning of a logger context is performed via the factory functions ara::log::CreateLogger, since the default constructor of class Logger is deleted [SWS_LOG_00259]. Applications can instantiate loggers either programmatically by specifying a context ID (ctxId), a description (ctxDescription), and optionally a default log level [SWS_LOG_00021], [SWS_LOG_00263], or derive them instance-based via a model element using ara::core::InstanceSpecifier [SWS_LOG_00256]. The destructor of Logger handles deregistration in a thread-safe manner [SWS_LOG_00260].

The granularity and priority of messages is represented hierarchically by the enumeration LogLevel: kFatal (unrecoverable system error), kError (error with functional impairment), kWarn (warning in case of compromised nominal behavior), kInfo (general operational information), kDebug (detailed diagnostics), and kVerbose (verbose tracing) [SWS_LOG_00018], ManifestSpecification p. 416. For runtime optimization, computationally intensive preparation of log data can be avoided by checking in advance via the query IsEnabled(logLevel) whether the respective log level is currently activated on the context [SWS_LOG_00070]. If required, the active reporting threshold of a logger instance can be dynamically adjusted at runtime via SetThreshold(threshold) [SWS_LOG_00255].

Unmodeled Logging and Stream-Based Message Composition

For unmodeled messages, ara::log provides a fluent interface based on the builder design pattern PlatformDesign p. 74. Entry occurs via severity-specific member functions of the Logger instance, namely LogFatal(), LogError(), LogWarn(), LogInfo(), LogDebug(), and LogVerbose(), or via WithLevel(logLevel), which return a temporary, lightweight LogStream object [SWS_LOG_00064], [SWS_LOG_00065], [SWS_LOG_00066], [SWS_LOG_00067], [SWS_LOG_00068], [SWS_LOG_00069], [SWS_LOG_00131]. Data is then appended to the internal message buffer in a chained manner via the type-safe stream insertion operator (operator<<) [SWS_LOG_00040].

The stream interface supports a wide range of native C++ and AUTOSAR types without manual formatting errors:

• Integer types (signed and unsigned from 8 to 64 bits) as well as boolean values [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].
• Floating-point types of single and double precision (float, double) [SWS_LOG_00049], [SWS_LOG_00050].
• Null-terminated UTF-8 strings and ara::core::StringView [SWS_LOG_00051], [SWS_LOG_00062].
• Specific platform types such as LogLevel in text form [SWS_LOG_00063], error objects ara::core::ErrorCode [SWS_LOG_00124], time durations std::chrono::duration [SWS_LOG_00125], model references ara::core::InstanceSpecifier [SWS_LOG_00126], raw pointers [SWS_LOG_00127], and byte sequences via ara::core::Span<const ara::core::Byte> [SWS_LOG_00128].

Metadata and formatting can be controlled precisely: Source code origin is captured via WithLocation(file, line) [SWS_LOG_00129], WithTag(tag) adds functional tags [SWS_LOG_00132], and WithPrivacy(value) defines a confidentiality level via the lowest 8 bits [SWS_LOG_00258]. Formatted arguments with name and physical unit are encapsulated via the helper template Arg [SWS_LOG_00201], [SWS_LOG_00203], supported by the formatting helpers Dflt, Hex, Dec, Oct, Bin, DecFloat, EngFloat, HexFloat, and AutoFloat from the enumeration Fmt [SWS_LOG_00206], [SWS_LOG_00208], [SWS_LOG_00209], [SWS_LOG_00211], [SWS_LOG_00217], [SWS_LOG_00225], [SWS_LOG_00226].

With respect to lifecycle, LogStream is a move-only object: copy constructor and copy assignment operator are deleted [SWS_LOG_00174], [SWS_LOG_00175], while the move constructor is declared to support Return Value Optimization (RVO) [SWS_LOG_00176]; the move assignment operator is deleted [SWS_LOG_00177]. When leaving scope, the buffer content is automatically sent to the logging framework via the destructor ~LogStream() [SWS_LOG_00262]. If a LogStream object is to be used for multiple messages in succession within the same scope, the buffer transmission must be triggered explicitly via Flush(), thereby initializing a fresh message stream [SWS_LOG_00039]. Interpretation: After Flush() is called, the internal buffer management of LogStream is likely to flush and reinitialize the buffer for subsequent streaming operators within the same scope without requiring destruction of the object identity. Question (open)

Sequence diagram: Sequence of unmodeled stream logging via LogStream up to buffer transmission to the logging backend. Sources: [SWS_LOG_00067], [SWS_LOG_00040], [SWS_LOG_00039], [SWS_LOG_00262], PlatformDesign p. 74

Modeled Logging and Branching to ARTI Tracing

In contrast to the incremental construction of unmodeled messages, ara::log defines a highly efficient single-call interface via Logger::Log(id, args...) as well as Logger::LogWith(attrs, msgId, params...) for messages modeled in the manifest [SWS_LOG_00204], [SWS_LOG_00133]. All arguments are passed in a single function call, which reduces runtime overhead to a minimum in the case of suppressed messages: Immediately after parameter passing, a single condition checks the threshold and returns immediately if the configured log level is not reached PlatformDesign p. 74.

Within the call to Log, the processing path branches: In addition to the classic path of DLT serialization (buildDltMessage(), filtering via log mask, and passing to the sink), a dedicated path exists for hardware-oriented tracing via the AUTOSAR Run-Time Interface (ARTI) using TraceArti(msg_id, params...) [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42. Forwarding to TraceArti is presumably resolved via static template specializations at compile time to ensure the required minimal runtime overhead. Question (open) The ARTI backend filters according to its own criteria based on the MsgId and completely bypasses DLT buffering, which permits real-time-critical tracing without interfering with the regular logging subsystem AUTOSAR AP SWS LogAndTrace p. 42.

Activity diagram: Control and filter flow when emitting modeled messages between DLT backend and ARTI tracing. Sources: [SWS_LOG_00204], [SWS_LOG_20000], AUTOSAR AP SWS LogAndTrace p. 42, PlatformDesign p. 74

Client Connection Monitoring and Diagnostic Integration

Log and Trace not only provides local output channels, but also monitors the state of external diagnostic clients (e.g., DLT viewer via Ethernet), represented by the enumeration ClientState: kUnknown (-1, DLT backend not yet ready), kNotConnected (no remote client detected), and kConnected (connection to external client active) [SWS_LOG_00098]. This allows applications to couple computationally expensive tracing to the physical presence of an analysis tool.

For asynchronous state tracking, applications register a callback function via ara::log::RegisterConnectionStateHandler using the function alias ConnectionStateHandler = std::function<void(ClientState)> [SWS_LOG_00205], [SWS_LOG_00265]. The logging framework supports exactly one active handler registration here: A renewed call to RegisterConnectionStateHandler overwrites a previously installed callback without restriction [SWS_LOG_00205].

State diagram: State transitions of the external client according to ClientState. Sources: [SWS_LOG_00098], [SWS_LOG_00205], [SWS_LOG_00265]

Behavior in the event of an error

The module enforces functional safety and robustness primarily through static type checking at compile time and strict exception guarantees:

• Compile-time errors (ill-formed): The call to Logger::Log(id, args...) is ill-formed if the passed arguments do not match the message signature declared in the manifest exactly [SWS_LOG_00204]. Likewise, using Arg() with types that are neither arithmetic nor boolean nor convertible to StringView or Span<const Byte> results in a compilation abort [SWS_LOG_00201]. The function WithPrivacy(value) additionally enforces that the parameter type is an integer type or an enumeration [SWS_LOG_00258].
• Construction and assignment prohibitions: To preclude unintentional buffer duplications or resource conflicts, the copy constructor and copy assignment operator of LogStream as well as the move assignment operator are explicitly deleted [SWS_LOG_00174], [SWS_LOG_00175], [SWS_LOG_00177].
• Runtime integrity during instantiation: If resolution of the ara::core::InstanceSpecifier in the machine or application model fails in CreateLogger(is) or does not reference a valid model element, the system reports a InstanceSpecifierMappingIntegrityViolation [SWS_LOG_00256].
• Fail-safe fallback sinks: If no deployment model or network connection to the DLT service is available at runtime, the framework automatically switches to the local console as the default output sink so that no diagnostic information is silently lost [SWS_LOG_00021], [SWS_LOG_00263]. When outputting an core::ErrorCode to the console, it is rendered using the domain name and the numeric error value [SWS_LOG_00124].
• Exception safety: All streaming operators, threshold queries, and the destructor ~LogStream() are declared as noexcept to ensure that logging at no point propagates unhandled exceptions into calling functional blocks [SWS_LOG_00040], [SWS_LOG_00070], [SWS_LOG_00262]; the destructor ~Logger(), however, is formally not specified as noexcept [SWS_LOG_00260].

Further detailed evidence

The architecture and behavior of the Log and Trace module are anchored in the following reference sections of the AUTOSAR specification:

• Cluster interface specification: The normative C++ signatures, stream operators, and context methods of Logger and LogStream are defined in the specification of Log and Trace [SWS_LOG_00021], [SWS_LOG_00039], [SWS_LOG_00064], [SWS_LOG_00204], AUTOSAR AP SWS LogAndTrace p. 13.
• Platform design and performance: The architectural comparison between builder pattern and highly efficient single-call invocation for modeled messages is set forth in the Platform Design PlatformDesign p. 74.
• Platform-wide dependencies: The mandatory use of the Logger interface by functional platform clusters is maintained in the respective architecture documents AUTOSAR AP EXP SWArchitecture p. 58, AUTOSAR AP EXP SWArchitecture p. 50, AUTOSAR AP SWS PlatformHealthManagement p. 16.
• Manifest and deployment model: The configuration of DLT log channels, process mappings, and machine endpoints is governed in the manifest specification SWS LogAndTrace p. 21, ManifestSpecification p. 416.
• Operating system adapters and ARTI: The connection of native operating system trace buffers to ara::log and hardware-oriented capture via TraceArti are specified in the OSI and trace architecture [SWS_LOG_20000], AUTOSAR AP SWS OperatingSystemInterface p. 21, AUTOSAR AP SWS LogAndTrace p. 42.