req/req.yml

name: journal-uploader
version: 1.0.0
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:
  TOPIC-1:
    name: Journal Watcher
    subtopics:
      SUB-1.1:
        name: File Monitoring
        requirements:
          REQ-1.1.1:
            name: Continuous Monitoring
            description: The tool must continuously monitor a designated directory.
      SUB-1.2:
        name: File Detection
        requirements:
          REQ-1.2.1:
            name: Detection of New Files
            description: The tool must detect the addition of new files in the monitored directory.
          REQ-1.2.2:
            name: Avoid Re-processing
            description: The tool must not process files that have already been processed.

  TOPIC-2:
    name: Traced Logging
    subtopics:
      SUB-2.1:
        name: File Processing
        requirements:
          REQ-2.1.1:
            name: Reading Log Messages
            description: When a new file is processed, each log message should be put into a buffer.
          REQ-2.1.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-2.1.3:
            name: No Duplicate Log Messages
            description: The tool shall make sure that no log entry will be written to the file twice.
      SUB-2.2:
        name: Traced Log Rotation
        requirements:
          REQ-2.2.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.2.2:
            name: Compression of Rotated Files
            description: Each traced log file must get compressed after it got rotated.
          REQ-2.2.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.

  TOPIC-3:
    name: Remote Journal Logging
    subtopics:
      SUB-3.1:
        name: Service Activation
        requirements:
          REQ-3.1.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-3.1.2:
            name: Duration
            description: The remote journal logging should stay active, until it reaches the specified duration.
          REQ-3.1.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-3.1.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-3.2:
        name: File Processing
        requirements:
          REQ-3.2.1:
            name: File Upload
            description: When a file gets detected, it should get uploaded to the cloud.
          REQ-3.2.2:
            name: No Duplicate Files
            description: Already processed files must not get uploaded again.
          REQ-3.2.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-3.2.4:
            name: Duration Expired
            description: After the specified duration is expired, the service should stop uploading files.

  TOPIC-4:
    name: Configuration
    requirements:
      CONF-4.1:
        name: Journal Directory
        description: Users should be able to specify the directory to be monitored for journal files.
      CONF-4.2:
        name: Output Directory
        description: Users should be able to specify the directory into which the final files will be written.
      CONF-4.3:
        name: Trigger Priority
        description: Users should be able to specify which priority triggers the filtering.
      CONF-4.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.
      CONF-4.5:
        name: Max File Size
        description: Users should be able to specify the max file size, at which a file gets rotated.
      CONF-4.6:
        name: Max Directory Size
        description: Users should be able to specify the max directory size, at which a directory gets rotated.
      CONF-4.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.

  TOPIC-5:
    name: Performance Requirements
    requirements:
      PERF-5.1:
        name: Efficiency
        description: The tool should efficiently monitor and process files without excessive resource consumption.
      PERF-5.2:
        name: Interval Delay
        description: The tool should do its work with no more than 10 seconds delay after its interval.

  TOPIC-6:
    name: Security & Data Protection
    requirements:
      SEC-6.1:
        name: No Insecure Connection
        description: The tool must send data only through a secure connection.
      SEC-6.2:
        name: GDPR compliance
        description: The tool must not upload data if the user has not agreed to share this information.

  TOPIC-7:
    name: Testing
    requirements:
      TST-7.1:
        name: Unit Tests
        description: Comprehensive unit tests should be written to cover major functionalities.
      TST-7.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'