initial version of logging feature request

docs/features/analysis-infra/index.rst

@@ -16,4 +16,8 @@ Analysis Infrastructure
 #######################
 
 .. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
    logging/index.rst
+   tracing/index.rst

docs/features/analysis-infra/logging/index.rst

@@ -12,9 +12,11 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
-Logging
-#######
+.. Logging
+.. #######
 
 .. toctree::
-   console-output/index.rst
-   mw-log-api/index.rst
+   :titlesonly:
+   :maxdepth: 1
+
+   ./mw-fr_logging.rst

docs/features/analysis-infra/logging/mw-fr_logging.rst

@@ -0,0 +1,202 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Logging
+#######
+
+.. document:: Logging
+   :id: DOC_Logging
+   :status: draft
+   :safety: ASIL_B
+   :tags: feature_request
+
+
+Feature flag
+============
+
+To activate this feature, use the following feature flag:
+
+``experimental_logging``
+
+Abstract
+========
+
+This feature request proposes the development of a safe, efficient and robust logging framework for embedded systems.
+
+
+Motivation
+==========
+
+- currently no solution available in the score platform
+
+Rationale
+=========
+
+Logging provides the possibility to understand the running system by capturing detailed information about system
+events and application-level activities.
+
+Specification
+=============
+
+[Describe the requirements, architecture of any new feature.] [or]
+[Describe the change to requirements, architecture, implementation, process, documentation, infrastructure of any change request.]
+
+   .. note::
+      A Feature Request shall specify the stakeholder requirements as part of our platform/project.
+      Thereby the :need:`RL_technical_lead` will approve these requirements as part of accepting the Feature Request (e.g. merging the PR with the Feature Request).
+
+Functionality
+-------------
+
+Logging has to support the following features:
+
+- Timestamping
+
+  - local timestamp for each log entry
+  - original timestamp for routed log entries
+  - timestamp synchronization for log entries coming from different logging nodes-
+
+- Log severity levels
+- Log prioritization in case of resource conflicts
+- logging of early startup events
+- Log filtering
+
+  - Support application and context identifier like in DLT
+  - Filtering by log levels for components and application level
+  - Out of scope "time" (tooling topic)
+  - logs filtering by logging entity ID (e.g., ECU ID, Application ID, Context ID such as in DLT)
+  - logs filtering by log level (e.g., FATAL, ERROR, WARN, INFO, DEBUG, VERBOSE such as in DLT)
+  - Filtering options: it should have filter on app id and more fine-tuned filters on context ids.
+
+- message loss detection
+
+  - optional functionality for logging. Important for tracing.
+  - would become mandatory in case verification is done via logging feature (not recommended)
+
+- Context specific log level activation at runtime
+
+Log Sources
+-----------
+
+- user application
+- component features & platform
+
+Log Sinks
+---------
+- log sinks shall be transparent to the application (e.g. by a facade )
+- console
+- File system
+
+  - local
+  - external mounted PCIe Drive
+  - Cloud native drive via network
+
+- Network (incl. second dedicated Ethernet Channel)
+- Logs shall appear on stdout when running unit tests
+
+Configuration
+-------------
+
+- Log level
+- Log Sinks
+
+  - Log storage device
+  - Log storage strategy (e.g., on system shutdown, on each message, on demand, on file size, on cache size, with circular or linear buffer)
+
+- Buffer size
+- Storage size (e.g. storage size of log files)
+- Permission settings
+- log filter
+- Logging entity ID (e.g., ECU ID, Application ID, Context ID such as in DLT)
+- On-demand functionality (e.g., enable / disable the log storage)
+- Provide fallback configs. E.g.: App, System-wide
+
+- Possibility to provide an extension for custom types
+
+Error handling
+--------------
+
+- reboot/reset
+- On logging errors, the framework should continue if recoverable; otherwise, deactivate silently and set an error state reported on shutdown.
+- The user application should not be affected by logging framework errors.
+
+Context
+-------
+
+- Supported operating system: QNX, Linux (encapsulation via OSAL)
+- Supported programming languages: C++, Rust, Python (e.g. for tests)
+
+Resource consumption
+--------------------
+
+- Storage
+- Communication Channel
+- Runtime resources
+- Low impact on overall performance ---> QoS for handling overflows/dropping log messages
+
+Norms/Standards
+---------------
+
+
+Backwards Compatibility
+=======================
+\-
+
+Security Impact
+===============
+
+- only authorized users should be able to access the log files
+
+Safety Impact
+=============
+
+- The interface should support the ASIL level of the user function.
+- Dependent on the Safety concept of the over all system, the logging should be classified accordingly.
+  That could be the case if the logging information are part of the verification strategy..
+
+License Impact
+==============
+
+- not known
+
+How to Teach This
+=================
+
+How to Use: Logging Guideline
+
+
+Definitions
+===========
+
+Logging
+-------
+
+Write out some message
+General progress description (incl. Context)
+- state changes
+- Infos
+- errors
+
+When logging from a library, it shall be possible to easily associate the logs to the library. A solution could be to provide contexts.
+
+Tracing
+-------
+
+Example - User need to correlate kernel traces to user traces for debugging , analyzing etc
+Follow the control flow (on function call basis)of the application.
+
+Recompute
+---------
+
+All data to recompute a module (Input, Output, States)

docs/features/analysis-infra/logging/mw-fr_logging_DD_Input.rst

@@ -0,0 +1,44 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+This document includes the detailed design findings from the feature request review.
+
+Logging
+#######
+
+Specification
+=============
+Context
+-------
+.. related feature from feature request
+- Supported programming languages: C++, Rust, Python (e.g. for tests)
+
+.. detailed design finding
+For Rust, we would like to be able to use the log crate. It provides an (allocation-free) facade without forcing a specific logger implementation. Advantages of using this facade:
+
+We stay with language best-practices.
+New contributors directly feel at home with the logging.
+Any library dependency which we might use probably logs against this facade. So we would get logs of dependencies for free by using it as well and implementing a logger for the facade.
+There might be comparable defacto standards for C++ and Python.
+
+
+Resource consumption
+--------------------
+.. related feature from feature request
+- Runtime ressources
+- Low impact on overall performance ---> QoS for handling overflows/dropping log messages
+
+.. detailed design finding
+Ideally, in a language like Rust, logging messages should be possible without allocations for individual logs.
+Using the defacto standard log crate as facade, implementors of this facade should not allocate to write / forward log messages.

docs/features/analysis-infra/logging/console-output/index.rst → docs/features/analysis-infra/tracing/index.rst

@@ -12,5 +12,11 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
-Console Output
-##############
+.. Tracing
+.. #######
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   ./mw-fr_tracing.rst