模块 ara::log — Log and Trace

功能集群 Log and Trace 为 AUTOSAR Adaptive Platform 上的日志记录和跟踪提供核心基础设施 AUTOSAR AP SWS LogAndTrace 第13页。应用程序和平台守护进程可以通过类型安全的数据流灵活创建日志消息，或者通过具有极低检查开销的高效建模函数调用来创建日志消息 [SWS_LOG_00204]。消息过滤通过每个上下文可配置的详细级别进行，同时转发至 DLT 后端、ARTI 工具或本地控制台 [SWS_LOG_00021]。

更多 ›

功能集群 Log and Trace（ara::log）构成了 AUTOSAR Adaptive Platform 中用于结构化日志记录、诊断输出和底层硬件跟踪的通用基础基础设施 AUTOSAR AP SWS LogAndTrace 第13页。每个 Logger 实例代表进程内的一个独立上下文，并在创建时自动向中央日志记录后端注册 EXP SWArchitecture 第57页。除应用程序外，Execution Management、Platform Health Management 和 Persistency 等基本平台服务也必须绑定 Logger 接口以用于运行文档记录 AUTOSAR AP EXP SWArchitecture 第58页。

上下文图：集群 Log and Trace 作为自适应应用程序和平台功能集群的核心日志记录与跟踪基础设施的嵌入情况。来源：AUTOSAR AP SWS LogAndTrace 第13页、AUTOSAR AP EXP SWArchitecture 第58页、SWS LogAndTrace 第21页、AUTOSAR AP SWS OperatingSystemInterface 第21页

该模块区分了两种基本的交互形式：

• 非建模日志记录： Fluent-Builder 模式通过与严重级别相关的方法（例如 LogInfo() 或 LogError()）生成一个临时的 LogStream 对象，该对象以类型安全的方式级联标量类型、字符串、错误代码和格式修饰符，并最迟在析构函数中或通过 Flush() 发送缓冲区 [SWS_LOG_00067]、[SWS_LOG_00039]、[SWS_LOG_00262]。
• 建模日志记录： 通过单次调用接口 Logger::Log(id, args...) 发送预先在清单中声明的消息，这使得在阈值未激活时能够实现高效过滤而无需进行对象实例化 [SWS_LOG_00204]、PlatformDesign 第74页。

时序图：通过 LogStream 进行非建模流日志记录直至将缓冲区传输至日志记录后端的过程。来源：[SWS_LOG_00067]、[SWS_LOG_00040]、[SWS_LOG_00039]、[SWS_LOG_00262]、PlatformDesign 第74页

为避免不必要的计算时间，可以预先通过 IsEnabled(logLevel) 验证活动报告级别，或在运行时通过 SetThreshold(threshold) 进行调整 [SWS_LOG_00070]、[SWS_LOG_00255]。除了通过 Ethernet 转发至 DLT 通道或转发至 ARTI 工具之外，在缺少模型配置时控制台还充当故障安全回退 [SWS_LOG_00021]，同时外部诊断连接状态可以通过 RegisterConnectionStateHandler 进行异步监控 [SWS_LOG_00098]、[SWS_LOG_00205]。

更多 ›

系统架构与 Log and Trace 的功能角色

功能集群 Log and Trace（ara::log）构成了用于在 AUTOSAR Adaptive Platform 上标准化采集、转发和过滤诊断、跟踪与日志消息的核心横向子系统 AUTOSAR AP SWS LogAndTrace 第13页。编程接口 Logger 提供了统一的 C++ 平台 API，该 API 既作为基础基础设施被特定于应用的进程（Adaptive Applications）使用，也被基本平台功能集群使用 AUTOSAR AP EXP SWArchitecture 第58页。这些使用该 API 的系统守护进程除其他外包括：用于进程生命周期文档记录的 Execution Management AUTOSAR AP EXP SWArchitecture 第50页、用于状态监控的 Platform Health Management AUTOSAR AP SWS PlatformHealthManagement 第16页、用于高精度时间基准的 Time Synchronization AUTOSAR AP SWS TimeSynchronization 第17页，以及用于软件更新期间的 Update and Configuration Management AUTOSAR AP EXP SWArchitecture 第141页。

在架构上，每个 Logger 实例封装了应用程序或进程作用域内的唯一上下文（Context ID），该上下文在创建时自动向日志记录后端注册，并在应用程序关闭时自动注销 EXP SWArchitecture 第57页。日志记录后端将格式化后的消息转发至规划的输出通道（例如根据机器清单通过 Ethernet 转发至 DLT 协议接收端）或本地缓冲区，在缺少部署模型时默认回退到操作系统控制台 [SWS_LOG_00021]、SWS LogAndTrace 第21页。此外，解耦的适配器架构允许操作系统（POSIX/OS）通过 AUTOSAR 运行时接口（ARTI）提供与 ara::log 的消息同步的内部内核与调度度量指标 AUTOSAR AP SWS OperatingSystemInterface 第21页。

上下文图：集群 Log and Trace 作为自适应应用程序和平台功能集群的核心日志记录与跟踪基础设施的嵌入情况。来源：AUTOSAR AP SWS LogAndTrace 第13页、AUTOSAR AP EXP SWArchitecture 第58页、SWS LogAndTrace 第21页、AUTOSAR AP SWS OperatingSystemInterface 第21页

实例化、上下文管理与阈值控制

Logger 上下文的提供通过工厂函数 ara::log::CreateLogger 进行，因为类 Logger 的默认构造函数已被删除 [SWS_LOG_00259]。应用程序既可以通过指定上下文 ID（ctxId）、描述（ctxDescription）和可选的默认日志级别以编程方式实例化 Logger [SWS_LOG_00021]、[SWS_LOG_00263]，也可以通过 ara::core::InstanceSpecifier 基于实例从模型元素派生 [SWS_LOG_00256]。Logger 的析构函数以线程安全的方式处理注销 [SWS_LOG_00260]。

消息的粒度和优先级通过枚举 LogLevel 分层映射：kFatal（不可恢复的系统错误）、kError（具有功能损害的错误）、kWarn（目标行为受危及时的警告）、kInfo（常规运行信息）、kDebug（详细诊断）以及 kVerbose（详尽跟踪）[SWS_LOG_00018]、ManifestSpecification 第416页。为了进行运行时优化，可以通过预先经由查询 IsEnabled(logLevel) 检查相关日志级别当前是否在上下文处于活动状态，从而避免对日志数据进行计算密集型准备 [SWS_LOG_00070]。Logger 实例的活动报告阈值在需要时可以在运行时通过 SetThreshold(threshold) 进行动态调整 [SWS_LOG_00255]。

非建模日志记录与基于流的消息组合

对于非建模消息，ara::log 提供了一个借鉴自 Builder 设计模式的 Fluent 接口 PlatformDesign 第74页。入口通过 Logger 实例的特定于严重级别的成员函数进行，即 LogFatal()、LogError()、LogWarn()、LogInfo()、LogDebug() 和 LogVerbose()，或通过 WithLevel(logLevel)，它们返回一个临时的轻量级 LogStream 对象 [SWS_LOG_00064]、[SWS_LOG_00065]、[SWS_LOG_00066]、[SWS_LOG_00067]、[SWS_LOG_00068]、[SWS_LOG_00069]、[SWS_LOG_00131]。随后，数据通过类型安全的流插入运算符（operator<<）以链式方式追加到内部消息缓冲区中 [SWS_LOG_00040]。

流接口支持广泛的原生 C++ 和 AUTOSAR 类型，而不会出现手动格式化错误：

• 整数类型（8 到 64 位的有符号和无符号类型）以及布尔值 [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]。
• 单精度和双精度浮点类型（float、double）[SWS_LOG_00049]、[SWS_LOG_00050]。
• 以 null 结尾的 UTF-8 字符串以及 ara::core::StringView [SWS_LOG_00051]、[SWS_LOG_00062]。
• 特定平台类型，例如文本形式的 LogLevel [SWS_LOG_00063]、错误对象 ara::core::ErrorCode [SWS_LOG_00124]、时间跨度 std::chrono::duration [SWS_LOG_00125]、模型引用 ara::core::InstanceSpecifier [SWS_LOG_00126]、原始指针 [SWS_LOG_00127] 以及通过 ara::core::Span<const ara::core::Byte> 的字节序列 [SWS_LOG_00128]。

元数据和格式化可以精确控制：通过 WithLocation(file, line) 捕获源代码来源 [SWS_LOG_00129]，WithTag(tag) 补充功能关键字 [SWS_LOG_00132]，而 WithPrivacy(value) 则通过最低 8 位指定机密性级别 [SWS_LOG_00258]。带有名称和物理单位的格式化参数通过辅助模板 Arg 进行封装 [SWS_LOG_00201]、[SWS_LOG_00203]，并由枚举 Fmt 中的格式化辅助工具 Dflt、Hex、Dec、Oct、Bin、DecFloat、EngFloat、HexFloat 和 AutoFloat 提供支持 [SWS_LOG_00206]、[SWS_LOG_00208]、[SWS_LOG_00209]、[SWS_LOG_00211]、[SWS_LOG_00217]、[SWS_LOG_00225]、[SWS_LOG_00226]。

在生命周期方面，LogStream 是一个仅移动（Move-only）对象：拷贝构造函数和拷贝赋值运算符已被删除 [SWS_LOG_00174]、[SWS_LOG_00175]，而移动构造函数被声明用于支持返回值优化（RVO）[SWS_LOG_00176]；移动赋值运算符已被删除 [SWS_LOG_00177]。离开作用域时，缓冲区内容会自动通过析构函数 ~LogStream() 发送到日志记录框架 [SWS_LOG_00262]。如果要在同一作用域内将一个 LogStream 对象依次用于多条消息，则必须通过 Flush() 显式触发缓冲区传输，从而初始化一个新的消息流 [SWS_LOG_00039]。Interpretation：LogStream 的内部缓冲区管理在调用 Flush() 之后可能会清空并重新初始化缓冲区，以供同一作用域中的后续流运算符使用，而无需销毁对象标识。

时序图：通过 LogStream 进行非建模流日志记录直至将缓冲区传输至日志记录后端的过程。来源：[SWS_LOG_00067]、[SWS_LOG_00040]、[SWS_LOG_00039]、[SWS_LOG_00262]、PlatformDesign 第74页

建模日志记录与向 ARTI 跟踪的分支

与非建模消息的分步构建相比，ara::log 针对清单中建模的消息通过 Logger::Log(id, args...) 以及 Logger::LogWith(attrs, msgId, params...) 定义了高效的单次调用接口 [SWS_LOG_00204]、[SWS_LOG_00133]。所有参数都在单个函数调用中传递，从而在消息被抑制的情况下将运行时开销降至最低：在参数传递后，单个条件会立即检查阈值，如果未达到配置的日志级别则立即返回 PlatformDesign 第74页。

在 Log 的调用内部，处理路径发生分流：除了 DLT 序列化的经典路径（buildDltMessage()、通过日志掩码过滤并传递给接收端）之外，还存在一条通过 TraceArti(msg_id, params...) 进行基于 AUTOSAR 运行时接口（ARTI）的底层硬件跟踪的专用路径 [SWS_LOG_20000]、AUTOSAR AP SWS LogAndTrace 第42页。Annahme：向 TraceArti 的转接是在编译时通过静态模板特化解析的，以确保所要求的极低运行时开销。ARTI 后端根据其基于 MsgId 的自有准则进行过滤，并完全绕过 DLT 缓冲，从而允许进行实时关键型跟踪而不会干扰常规日志记录子系统 AUTOSAR AP SWS LogAndTrace 第42页。

活动图：在 DLT 后端与 ARTI 跟踪之间发送建模消息时的控制与过滤流程。来源：[SWS_LOG_00204]、[SWS_LOG_20000]、AUTOSAR AP SWS LogAndTrace 第42页、PlatformDesign 第74页

客户端连接监控与诊断连接

Log and Trace 不仅提供本地输出通道，还监视外部诊断客户端（例如通过 Ethernet 的 DLT 查看器）的状态，该状态由枚举 ClientState 表示：kUnknown（-1，DLT 后端尚未就绪）、kNotConnected（未检测到远程客户端）以及 kConnected（与外部客户端的连接处于活动状态）[SWS_LOG_00098]。这允许应用程序将繁重的跟踪与分析工具的物理存在相绑定。

对于异步状态跟踪，应用程序使用函数别名 ConnectionStateHandler = std::function<void(ClientState)> 通过 ara::log::RegisterConnectionStateHandler 注册回调函数 [SWS_LOG_00205]、[SWS_LOG_00265]。此时日志记录框架恰好支持一个活动处理程序注册：再次调用 RegisterConnectionStateHandler 会无限制地覆盖先前安装的回调 [SWS_LOG_00205]。

状态图：根据 ClientState 的外部客户端状态转换。来源：[SWS_LOG_00098]、[SWS_LOG_00205]、[SWS_LOG_00265]

发生错误时的行为

该模块主要通过编译时的静态类型检查和严格的异常保证来强制实现功能安全与稳健性：

• 编译时错误（ill-formed）：如果传递的参数与清单中声明的消息签名不完全匹配，则对 Logger::Log(id, args...) 的调用是非法的（ill-formed）[SWS_LOG_00204]。同样，将 Arg() 用于既非算术类型、非布尔类型，也无法转换为 StringView 或 Span<const Byte> 的类型，会导致编译中止 [SWS_LOG_00201]。函数 WithPrivacy(value) 还强制要求参数类型必须是整数类型或枚举 [SWS_LOG_00258]。
• 构造与赋值限制：为排除意外的缓冲区重复或资源冲突，LogStream 的拷贝构造函数和拷贝赋值运算符以及移动赋值运算符均被显式删除 [SWS_LOG_00174]、[SWS_LOG_00175]、[SWS_LOG_00177]。
• 实例化时的运行时完整性：如果在 CreateLogger(is) 处机器或应用模型中 ara::core::InstanceSpecifier 的解析失败，或者其未指向允许的模型元素，系统将报告 InstanceSpecifierMappingIntegrityViolation [SWS_LOG_00256]。
• 故障安全回退接收端：如果在运行时没有可用的部署模型或到 DLT 服务的网络连接，框架会自动切换到本地控制台作为默认输出接收端，从而不会无声无息地丢失诊断信息 [SWS_LOG_00021]、[SWS_LOG_00263]。在控制台上输出 core::ErrorCode 时，通过域名和数字错误值进行呈现 [SWS_LOG_00124]。
• 异常安全性：所有流运算符、阈值查询以及析构函数 ~LogStream() 均声明为 noexcept，以确保日志记录在任何时候都不会向调用功能块传播未处理的异常 [SWS_LOG_00040]、[SWS_LOG_00070]、[SWS_LOG_00262]；相反，析构函数 ~Logger() 在形式上未被指定为 noexcept [SWS_LOG_00260]。

进一步详细证据

模块 Log and Trace 的架构和行为植根于 AUTOSAR 规范的以下参考部分：

• 集群接口规范：Logger 和 LogStream 的规范性 C++ 签名、流运算符和上下文方法在 Log and Trace 规范中定义 [SWS_LOG_00021]、[SWS_LOG_00039]、[SWS_LOG_00064]、[SWS_LOG_00204]、AUTOSAR AP SWS LogAndTrace 第13页。
• 平台设计与性能：针对建模消息的 Builder 模式与高效单次调用之间的架构比较在 Platform Design 中阐述 PlatformDesign 第74页。
• 全平台依赖关系：功能性平台集群对 Logger 接口的强制性使用在各自的架构文档中进行规定 AUTOSAR AP EXP SWArchitecture 第58页、AUTOSAR AP EXP SWArchitecture 第50页、AUTOSAR AP SWS PlatformHealthManagement 第16页。
• 清单与部署模型：DLT 日志通道、进程分配以及机器端点的配置在清单规范中进行了规定 SWS LogAndTrace 第21页、ManifestSpecification 第416页。
• 操作系统适配器与 ARTI：原生操作系统跟踪缓冲区与 ara::log 的连接以及通过 TraceArti 进行的接近硬件的采集均在 OSI 和跟踪架构中进行了规范 [SWS_LOG_20000]、AUTOSAR AP SWS OperatingSystemInterface 第21页、AUTOSAR AP SWS LogAndTrace 第42页。