:PROPERTIES:
:ID:       2883a21a-6b95-4f8c-a785-3c1472a994b6
:CREATED:  [2026-04-04 Sat 20:27]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Log Aggregator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :logging:observability:system:psf:

* Overview
The *Log Aggregator* monitors and summarizes system logs to provide insights into agent behavior and system health.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Collect and summarize agent logs.

** 2. User Needs
- *Scan:* Retrieve logs from the system.
- *Summarize:* Provide a high-level summary of recent activities.


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:

** 1. Architectural Intent
The Log Aggregator will employ a modular architecture, consisting of a Log Source Connector, a Summarization Engine, and a Presenter.  This allows for flexibility in adapting to different log formats and presentation styles.  The system will prioritize low overhead impact on the monitored system.

** 2. Semantic Interfaces (Lisp Signatures)

*** a. Log Source Connector

    #+BEGIN_SRC lisp
    ;;; Function: fetch-logs
    ;;; Description: Retrieves logs based on specified criteria.
    ;;; Parameters:
    ;;;   :source (keyword) - Specifies the log source (e.g., :systemd, :file, :journald).
    ;;;   :start-time (timestamp) -  Optional.  The starting timestamp for the logs.
    ;;;   :end-time (timestamp) - Optional. The ending timestamp for the logs.
    ;;;   :filters (list) - Optional. A list of filters to apply to the logs (e.g., '((:level . :error) (:component . "foo"))).
    ;;; Returns: A list of log entries (each entry being a plist).
    (defun fetch-logs (&key source start-time end-time filters)
      ...)
    #+END_SRC

*** b. Summarization Engine

    #+BEGIN_SRC lisp
    ;;; Function: summarize-logs
    ;;; Description: Summarizes a list of log entries.
    ;;; Parameters:
    ;;;   :log-entries (list) - A list of log entries (plists).
    ;;;   :summary-type (keyword) - Specifies the type of summary (e.g., :count-by-level, :count-by-component, :recent-errors).
    ;;; Returns: A summary of the logs (a plist).
    (defun summarize-logs (&key log-entries summary-type)
      ...)
    #+END_SRC

*** c. Presenter

    #+BEGIN_SRC lisp
    ;;; Function: present-summary
    ;;; Description: Presents a log summary in a human-readable format.
    ;;; Parameters:
    ;;;   :summary (plist) - A log summary as returned by `summarize-logs`.
    ;;;   :format (keyword) - Specifies the output format (e.g., :text, :html).
    ;;; Returns: A string containing the formatted summary.
    (defun present-summary (&key summary format)
      ...)
    #+END_SRC