PEL: Document PEL retention and pruning rules
The amount of disk space that PELs can take up on the BMC as well as the
total number of PELs will be capped. Document what happens when this
cap is reached.
At a high level, this includes removing old PELs from several
categories until those categories take up only a certain percentage of
the allocated space.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: Ib68a4b90751b5207a19bcbf381108b11d1c0c134
diff --git a/extensions/openpower-pels/README.md b/extensions/openpower-pels/README.md
index fac2373..e2c927f 100644
--- a/extensions/openpower-pels/README.md
+++ b/extensions/openpower-pels/README.md
@@ -11,6 +11,7 @@
* [Callouts](#callouts)
* [Action Flags and Event Type Rules](#action-flags-and-event-type-rules)
* [D-Bus Interfaces](#d-bus-interfaces)
+* [PEL Retention](#pel-retention)
## Passing PEL related data within an OpenBMC event log
@@ -289,3 +290,52 @@
See the org.open_power.Logging.PEL interface definition for the most up to date
information.
+
+## PEL Retention
+
+The PEL repository is allocated a set amount of space on the BMC. When that
+space gets close to being full, the code will remove a percentage of PELs to
+make room for new ones. In addition, the code will keep a cap on the total
+number of PELs allowed. Note that removing a PEL will also remove the
+corresponding OpenBMC event log.
+
+The disk capacity limit is set to 20MB, and the number limit is 3000.
+
+The rules used to remove logs are listed below. The checks will be run after a
+PEL has been added and the method to create the PEL has returned to the caller,
+i.e. run when control gets back to the event loop.
+
+### Removal Algorithm
+
+If the size used is 95% or under of the allocated space and under the limit on
+the number of PELs, nothing further needs to be done, otherwise continue and
+run all 5 of the following steps. Each step itself only deletes PELs until it
+meets its requirement and then it stops.
+
+The steps are:
+
+1. Remove BMC created informational PELs until they take up 15% or less of the
+ allocated space.
+
+2. Remove BMC created non-informational PELs until they take up 30% or less of
+ the allocated space.
+
+3. Remove non-BMC created informational PELs until they take up 15% or less of
+ the allocated space.
+
+4. Remove non-BMC created non-informational PELs until they take up 30% or less
+ of the allocated space.
+
+5. After the previous 4 steps are complete, if there are still more than the
+ maximum number of PELs, remove PELs down to 80% of the maximum.
+
+PELs with associated guard records will never be deleted. Each step above
+makes the following 4 passes, stopping as soon as its limit is reached:
+
+Pass 1. Remove HMC acknowledged PELs.<br>
+Pass 2. Remove OS acknowledged PELs.<br>
+Pass 3. Remove PHYP acknowledged PELs.<br>
+Pass 4. Remove all PELs.
+
+After all these steps, disk capacity will be at most 90% (15% + 30% + 15% +
+30%).