adaptived: README: Update flow chart and examples

Add a few real-world examples.  Update the flow chart to fix rendering
issues.

Signed-off-by: Tom Hromatka <[email protected]>

Author: drakenclimber

adaptived/README.md

@@ -1,5 +1,8 @@
-Adaptived is a simple cause-and-effect daemon for the Linux operating system.  It
-is designed to allow a user to construct a series of rules to automate tasks.
+adaptived is a simple yet extremely powerful and flexible cause-and-effect
+daemon.  Users can use adaptived to construct a series of custom rules to
+automate tasks, manage resources, kill processes, etc.  When used in
+conjunction with cgroups, adaptived can adjust system performance and settings
+in realtime to adapt to a changing workload.
 
 Adaptived has several built-in causes and effects.  When using only the built-in
 causes and effects, adaptived can be invoked directly by calling the adaptived
@@ -24,16 +27,16 @@ Adaptived uses the following terminology:
   Baring an error, each effect will run when the associated causes are
   triggered.
 * Rule - A rule is one or more causes combined with one or more effects. When
-  all of the causes in the rule are triggered, then the effects will be
-  executed.  A adaptived configuration file can contain multiple rules.
+  all of the causes in the rule are triggered, then the effect(s) will be
+  executed.  An adaptived configuration file can contain multiple rules.
 
 ## Architecture
 
 Adaptived's main processing loop operates as shown in the flow chart below:
 
 ![Adaptived flow chart](./doc/examples/flow-chart.png)
 
-## Simple Use Case - Built-In Causes and Effects
+## Getting Started
 
 If a user only wants to utilize the built-in causes and effects in adaptived,
 then they can invoke the daemon directly.
@@ -48,13 +51,34 @@ The above command will start the adaptived daemon.  It will employ the rules
 outlined in the provided configuration file, and the main adaptived loop will run
 every 3 seconds.
 
-Given the rule in this example, adaptived will print "It's 5 o'clock here :)" when
+Given the rule in this example, adaptived will print `It's 5 o'clock here :)` when
 the time is after 5 pm and it's a weekday.  It will print that message until
-midnight, and then the time_of_day cause will fail.  Since no maximum number of
-loops was provided in this example, adaptived will continue running until it is
-killed.  Once it's after 5 pm and a weekday, then the print effect will again
+midnight, and then the `time_of_day` cause will no longer trigger.  Since no maximum
+number of loops was provided in this example, adaptived will continue running until
+it is killed.  Once it's after 5 pm and a weekday, then the print effect will again
 run and output the aforementioned message.
 
+## Real-World Use Cases
+
+* Given two cgroups, high-priority and low-priority, kill processes in the
+  low-priority cgroup when there is PSI pressure on the high-priority cgroup
+  [[1]](https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/examples/kill-lowpriority.json)
+* Given two cgroups, high-priority and low-priority, reduce the cpu.weight
+  of the low-priority cgroup when there is PSI pressure on the high-priority
+  cgroup.  Conversely, when there is very little pressure on the high-priority
+  cgroup, increase the cpu.weight of the low-priority cgroup
+  [[2]](https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/examples/adjust-weight.json)
+* Adjust a cgroup's soft memory limit (memory.high) to determine the minimum
+  memory requirements of an application.  This value could be used to
+  populate that application's memory.low cgroup setting
+  [[3]](https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/examples/determine-memorylow.json)
+* When an anomalous event occurs, save critical logs off for later offline
+  evaluation and troubleshooting
+  [[4]](https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/examples/topmem-savelogs.json)
+* When the system's MemFree field falls below a threshold, send a signal to a
+  monitoring process
+  [[5]](https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/examples/lowmemfree-sendsignal.json)
+
 ## Advanced Use Case - Custom Causes and/or Effects
 
 Adaptived allows for users to create their own custom causes and effects.  (Note
@@ -68,6 +92,94 @@ library and its C APIs.  The automated test,
 [003-register_plugin_cause.c](./tests/ftests/003-register_plugin_cause.c),
 is a good starting point.
 
+## Schema
+
+An example adaptived JSON configuration file is attached below.  Note that the
+`comment` fields are for illustrative purposes and are not required.  (In fact,
+adaptived will ignore fields that aren't part of its schema.  As outlined
+below, these ignored fields could be a way to document the configuration
+file.)
+
+```
+{
+    "comment1": "adaptived configuration files consist of one or more rules.",
+    "comment2": "The rules are processed independent of each other,",
+    "comment3": "therefore ensure that one rule doesn't adversely affect another rule.",
+    "rules": [
+        {
+            "name": "We recommend a short but descriptive rule name",
+            "comment1": "The rule name must be unique as the name is used as the built-in identifier",
+            "comment2": "Also, the rule name is displayed in debug logs, so a short-but-descriptive name is very helpful in debugging",
+            "description": "Optional but helpful for further describing the rule.",
+
+            "causes comment1": "A rule consists of one of more causes.",
+            "causes comment2": "Every cause is run every time the main adaptived processing loop runs.",
+            "causes comment3": "Every cause must trigger for the effect(s) to be run.",
+            "currently-supported causes": "https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/internal/list-of-built-in-causes.md",
+            "causes": [
+                {
+                    "name": "cause 1 name",
+                    "args": {
+                        "comment1": "Each cause has its own set of args applicable to that cause.",
+                        "comment2": "See the list of built-in causes for the args supported by each cause"
+                    }
+                },
+                {
+                    "name": "cause 2 name",
+                    "comment1": "Even if cause 1 does not trigger, this cause will be evaluated every time the adaptived processing loop runs.",
+                    "comment2": "This is critical so that averages, trends, etc. can be properly computed.",
+                    "args": {}
+                }
+            ],
+
+            "effects comment1": "A rule consists of one or more effects.",
+            "effects comment2": "The effect(s) will only be run if every cause in this rule triggers.",
+            "currently-supported effects": "https://github.com/oracle/adaptivemm/blob/master/adaptived/doc/internal/list-of-built-in-effects.md",
+            "effects": [
+                {
+                    "name": "effect 1 name",
+                    "args": {
+                        "comment1": "Just like with the causes, each effect has its own set of args applicable to that effect.",
+                        "comment2": "See the list of built-in effects for the args supported by each effect."
+                    }
+                },
+                {
+                    "name": "effect 2 name",
+                    "args": {}
+                }
+            ]
+        },
+
+        {
+            "name": "When MemFree falls below 2 GB, send SIGALRM (signal 14) to the monitoring program",
+            "causes": [
+                {
+                    "name": "meminfo",
+                    "args": {
+                        "field": "MemFree",
+                        "threshold": "2G",
+                        "operator": "lessthan"
+                    }
+                }
+            ],
+            "effects": [
+                {
+                    "name": "signal",
+                    "args": {
+                        "proc_names": [
+                            {
+                                "name": "monitor_program"
+                            }
+                        ],
+                        "signal": 14
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
 ## Additional Resources
 
 * [List of Built-In Causes](./doc/internal/list-of-built-in-causes.md)
@@ -111,7 +223,7 @@ applications:
 
 However, if you are building the library from sources retrieved from the source
 repository you may need to run the autogen.sh script before running configure.
-In both cases, running "./configure -h" will display a list of build-time
+In both cases, running `./configure -h` will display a list of build-time
 configuration options.
 
 ## Testing the Library