req/req.yml

name: journal-uploader
description: |-
  The journal-uploader has two main functionalities.
  - Take a stream of log messages and filter them depending on their severity
  - Upload journal logs for a specified time when activated through cloud call
topics:
  FEAT-1:
    name: Traced Logging
    subtopics:
      SUB-1:
        name: File Monitoring
        requirements:
          REQ-1:
            name: Continuous Monitoring
            description: The tool must continuously monitor a designated directory.
      SUB-2:
        name: File Detection
        requirements:
          REQ-1:
            name: Detection of New Files
            description: The tool must detect the addition of new files in the monitored directory.
          REQ-2:
            name: Avoid Re-processing
            description: The tool must not process files that have already been processed.
      SUB-3:
        name: File Processing
        requirements:
          REQ-1:
            name: Reading Log Messages
            description: When a new file is processed, each log message should be put into a buffer.
          REQ-2:
            name: Filtering Log Messages
            description: |-
              The tool will search for messages of a defined priority (Trigger Priority).
              Each message of this priority, as well as all messages before and after, which are inside a defined timespan, must
              get written into a file. Every other message should gets dropped.
          REQ-3:
            name: No Duplicate Log Messages
            description: The tool shall make sure that no log entry will be written to the file twice.
      SUB-4:
        name: Traced Log Rotation
        requirements:
          REQ-1:
            name: Rotating Files
            description: |-
              When the size of the current traced log file exceeds a certain threshold,
              it must be closed and a new file must be opened for writing.
          REQ-2:
            name: Compression of Rotated Files
            description: Each traced log file must get compressed after it got rotated.
          REQ-3:
            name: Rotating Directory
            description: |-
              When the directory size exceeds a certain threshold, the tool must delete the oldest
              files in the directory, until the size is below the threshold again.
  FEAT-2:
    name: Remote Journal Logging
    subtopics:
      SUB-1:
        name: Service Activation
        requirements:
          REQ-1:
            name: Cloud Activation
            description: |-
              The remote journal logging **_SHALL_** be startable through a function call from the cloud.
              The api call has the duration and max interval as arguments.
          REQ-2:
            name: Duration
            description: The remote journal logging **_SHOULD_** stay active, until it reaches the specified duration.
          REQ-3:
            name: Max Interval
            description: |-
              If no upload was done after the amount of time specified in max interval,
              a log rotation **_SHALL_** be triggered, which will in turn get picked up by the file monitoring.
          REQ-4:
            name: Analytics Not Accepted
            description: |-
              If the user has not accepted the usage of their data, the cloud call **_MUST_**
              result in an error.
      SUB-2:
        name: File Monitoring
        requirements:
          REQ-1:
            name: Continuous Monitoring
            description: The tool **_SHOULD_** continuously monitor a designated directory.
      SUB-3:
        name: File Detection
        requirements:
          REQ-1:
            name: Detection of New Files
            description: The tool **_MUST_** detect the addition of new files in the monitored directory.
          REQ-2:
            name: Avoid Re-processing
            description: The tool must not process files that have already been processed.
      SUB-4:
        name: File Processing
        requirements:
          REQ-1:
            name: File Upload
            description: When a file gets detected, it **_SHOULD_** get uploaded to the cloud.
          REQ-2:
            name: No Duplicate Files
            description: Already processed files **_MUST NOT_** get uploaded again.
          REQ-3:
            name: Revoking Analytics
            description: |-
              If the user revokes the usage of their data, the service **_MAY_** continue running
              but **_MUST NOT_** upload any data until the user allows the usage of their data again.
          REQ-4:
            name: Duration Expired
            description: After the specified duration is expired, the service **_SHOULD_** stop uploading files.
  FEAT-3:
    name: Configuration
    requirements:
      REQ-1:
        name: Journal Directory
        description: Users **_SHOULD_** be able to specify the directory to be monitored for journal files.
      REQ-2:
        name: Output Directory
        description: Users **_SHOULD_** be able to specify the directory into which the final files will be written.
      REQ-3:
        name: Trigger Priority
        description: Users **_SHOULD_** be able to specify which priority triggers the filtering.
      REQ-4:
        name: Journal Context
        description: Users **_SHOULD_** be able to specify how many seconds of context will be added
          to traced logs when encountering a trigger priority.
      REQ-5:
        name: Max File Size
        description: Users **_SHOULD_** be able to specify the max file size, at which a file gets rotated.
      REQ-6:
        name: Max Directory Size
        description: Users **_SHOULD_** be able to specify the max directory size, at which a directory gets rotated.
      REQ-7:
        name: File Monitoring Interval
        description: |-
          Users **_SHOULD_** be able to specify an interval, which **_SHOULD_** change
          how long the tool waits before checking if new files are available.
  FEAT-4:
    name: Performance Requirements
    requirements:
      REQ-1:
        name: Efficiency
        description: The tool **_SHOULD_** efficiently monitor and process files without excessive resource consumption.
      REQ-2:
        name: Interval Delay
        description: The tool **_SHOULD_** do its work with no more than 10 seconds delay after its interval.
  FEAT-5:
    name: Data Protection
    requirements:
      REQ-1:
        name: No Insecure Connection
        description: The tool **_MUST_** send data only through a secure connection.
      REQ-2:
        name: GDPR compliance
        description: The tool **_MUST NOT_** upload data if the user has not agreed to share this information.
  FEAT-6:
    name: Testing
    requirements:
      REQ-1:
        name: Unit Tests
        description: Comprehensive unit tests **_SHOULD_** be written to cover major functionalities.
      REQ-2:
        name: Integration Tests
        description: Integration tests **_SHOULD_** be conducted to ensure all parts of the tool work together seamlessly.

definitions:
- name: Default Journal Directory
  value: /run/log/journal/<machine_id>
  additional_info:
  - Machine ID can be found at /etc/machine-id
- name: Default Output Directory
  value: /run/log/filtered-journal
config_defaults:
- name: Journal Directory
  type: Path
- name: Output Directory
  type: Path
- name: Trigger Priority
  type: Enum
  valid_values:
  - Emergency
  - Alert
  - Critical
  - Error
  - Warning
  - Notice
  - Info
  - Debug
  default_value: Warning
- name: Journal Context
  type: Integer
  unit: Seconds
  default_value: '15'
- name: Max File Size
  type: Integer
  unit: Bytes
  default_value: '8388608'
  hint: (8 MB)
- name: Max Directory Size
  type: Integer
  unit: Bytes
  default_value: '75497472'
  hint: (72 MB)
- name: File Monitoring Interval
  type: Integer
  unit: Seconds
  default_value: '10'