-----Original Message-----
From: Liu, Xinwu
Sent: Monday, August 13, 2018 4:37 AM
To: acrn-dev@...
Cc: Chen, Gang C <gang.c.chen@...>; Zhang, Di <di.zhang@...>;
Liu, Xinwu <xinwu.liu@...>; Jin, Zhi <zhi.jin@...>; Liu, Xiaojing
<xiaojing.liu@...>; VanCutsem, Geoffroy
<geoffroy.vancutsem@...>
Subject: [PATCH v3] tools:acrn-crashlog: Document of configuration file

This document explains all fields in acrnprobe.xml.
User could use it to control acrnprobe's behavior and configure their own
events.

Signed-off-by: Liu, Xinwu <xinwu.liu@...>

---
v1->v2:
1. refer conf.rst from README.rst
2. drawing by graphviz instead of raw text.

v2->v3:
1. correct some typo
2. put dot files into conf.rst, since the build system of doc collects only rst
files

tools/acrn-crashlog/acrnprobe/README.rst | 2 +
tools/acrn-crashlog/acrnprobe/conf.rst | 379
+++++++++++++++++++++++++++++++
2 files changed, 381 insertions(+)
create mode 100644 tools/acrn-crashlog/acrnprobe/conf.rst

diff --git a/tools/acrn-crashlog/acrnprobe/README.rst b/tools/acrn-
crashlog/acrnprobe/README.rst
index fa137f3..5f537ae 100644
--- a/tools/acrn-crashlog/acrnprobe/README.rst
+++ b/tools/acrn-crashlog/acrnprobe/README.rst
@@ -175,4 +175,6 @@ Configuration files

Custom configuration file that ``acrnprobe`` reads.

+More details about configuration file, please refer to :ref:`acrnprobe-conf`.
+
.. _`telemetrics-client`: https://github.com/clearlinux/telemetrics-client
diff --git a/tools/acrn-crashlog/acrnprobe/conf.rst b/tools/acrn-
crashlog/acrnprobe/conf.rst
new file mode 100644
index 0000000..f88d411
--- /dev/null
+++ b/tools/acrn-crashlog/acrnprobe/conf.rst
@@ -0,0 +1,379 @@
+.. _acrnprobe-conf:
+
+Configuration Of Acrnprobe
+##########################
+
+Description
+***********
+``Acrnprobe`` uses XML as the format of its configuration file, namely
+``acrnprobe.xml``, so the configuration file should reach the `XML
+standard`_ at least.
+
+Layout
+******
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <conf>
+ Root node of configuration.
+
+ <senders>
+ Configuration section of senders.
+ </senders>
+
+ <triggers>
+ Configuration section of triggers.
+ </triggers>
+
+ <vms>
+ Configuration section of virtual machines.
+ </vms>
+
+ <logs>
+ Configuration section of logs.
+ </logs>
+
+ <crashes>
+ Configuration section of crashes.
+ Note that this section should be configured after triggers and logs, as
+ crashes depend on these two sections.
+ </crashes>
+
+ <infos>
+ Configuration section of infos.
+ Note that this section should be configured after triggers and logs, as
+ infos depend on these two sections.
+ </infos>
+
+ </conf>
+
+As for the definition of ``sender``, ``trigger``, ``crash`` and
+``info`` and information of supported ``vm``, please refer to
:ref:`acrnprobe_doc`.
+
+Properties of modules
+*********************
+
+Common properties
+=================
+
+- ``id``:
+ The index, which grows from 1, in its group.
+- ``enable``:
+ This part of configuration can only take effect when the value is ``true``.
+
+Other properties
+================
+
+- ``inherit``:
+ Specify a parent for a certain crash.
+ The child crash will inherit all configurations from the specified
+(by id)
+ crash. These inherited configurations could be overwritten by new ones.
+ Also, this property helps build the crash tree in ``acrnprobe``.
+- ``expression``:
+ See `Crash`_.
+
+Crash tree in acrnprobe
+***********************
+
+There could be a parent-child relationship between crashes. Refer to
+the diagrams below, crash B and D are the children of crash A, because
+crash B and D inherit from crash A, and crash C is the child of crash B.
+
+Build crash tree in configuration
+=================================
+
+.. graphviz::
+
+ digraph {
+ {
+ node [shape=plaintext];
+ "level 1" -> "level 2" -> "level 3";
+ }
+
+ node [shape=box;style="rounded,filled";color=AntiqueWhite;];
+ c1 [ label="crash A\nid 1\ncrash root" ];
+ c2 [ label="crash B\nid 2" ];
+ c3 [ label="crash C\nid 3\ncrash leaf" ];
+ c4 [ label="crash D\nid 4\ncrash leaf" ];
+ c5 [ label="crash E\nid 5\ncrash root\ncrash leaf" ];
+ { rank = same; "level 1"; c1; c5;}
+ { rank = same; "level 2"; c2; c4;}
+ { rank = same; "level 3"; c3;}
+
+ node [shape=box;color="transparent";];
+ "None" -> {c1 c5} [ label="inherit 0" ];
+ c1 -> {c2 c4} [ label="inherit 1" ];
+ c2 -> c3 [ label="inherit 2" ];
+ }
+
+Crash type matches at runtime
+=============================
+
+In order to find a more specific type, if one crash type matches
+successfully ``acrnprobe`` will do match for each child of it (if it
+has) continually, and return the last successful one.
+Supposing these crash trees are like the diagram above at runtime:
+If a crash E is triggered, crash E will be returned immediately.
+If a crash A is triggered, then the candidates are crash A, B, C and D.
+The following diagram describes what ``acrnprobe`` will do if the
+matched result is crash D.
+
+.. graphviz::
+
+ digraph {
+ {
+ node [shape=plaintext];
+ "level 1" -> "level 2" -> "level 3";
+ }
+
+ node [shape=box;style="rounded,filled";color=AntiqueWhite;];
+ c1 [ label="crash A\nid 1\ncrash root" ];
+ c2 [ label="crash B\nid 2" ];
+ c3 [ label="crash C\nid 3\ncrash leaf" ];
+ c4 [ label="crash D\nid 4\ncrash leaf" ];
+ { rank = same; "level 1"; c1;}
+ { rank = same; "level 2"; c2; c4;}
+ { rank = same; "level 3"; c3;}
+
+ node [shape=box;style="rounded,dashed";];
+ exp1 [ label="crash B matches fail\nmatch for the next child\nof crash
A"];
+ exp2 [ label="crash D matches successfully\nreturn crash D"];
+
+ node [shape=box;style="invis";];
+ "channel" -> c1 [ label="trigger" ]
+ c1 -> {exp1 exp2}
+ exp1 -> c2 -> c3 [ style=dashed dir=none]
+ exp2 -> c4
+ }
+
+Sections
+********
+
+Sender
+======
+
+Example:
+
+.. code-block:: xml
+
+ <sender id="1" enable="true">
+ <name>crashlog</name>
+ <outdir>/var/log/crashlog</outdir>
+ <maxcrashdirs>1000</maxcrashdirs>
+ <maxlines>5000</maxlines>
+ <spacequota>90</spacequota>
+ <uptime>
+ <name>UPTIME</name>
+ <frequency>5</frequency>
+ <eventhours>6</eventhours>
+ </uptime>
+ </sender>
+
+* ``name``:
+ Name of sender. ``Acrnprobe`` uses this label to distinguish
+different
+ senders.
+ More information about sender, please refer to :ref:`acrnprobe_doc`.
+* ``outdir``:
+ Directory to store generated files of sender. ``Acrnprobe`` will
+create
+ this directory if it doesn't exist.
+* ``maxcrashdirs``:
+ The maximum serial number of generated ``crash directories``, ``stat
+directories``
+ and ``vmevent directories``. The serial number will back to 0 if it
+reaches
+ the maximum. Only used by sender crashlog.
+* ``maxlines``:
+ The maximum lines of file ``history_event``. It will trigger action
+ ``"mv history_event history_event.bak"`` that the lines of
+``history_event``
+ reaches the ``maxlines``.
+* ``spacequota``:
+ ``Acrnprobe`` will stop collecting logs if it is true that
+ ``(used space / total space) * 100 > spacequota``. Only used by
+sender
+ crashlog.
+* ``uptime``:
+ Configuration to trigger ``UPTIME`` event.
+ sub-nodes:
+
+ + ``name``:
+ The name of event.
+ + ``frequency``:
+ Time interval in seconds to trigger ``uptime`` event.
+ + ``eventhours``:
+ Time interval in hours to generate a record.
+
+
+Trigger
+=======
+
+Example:
+
+.. code-block:: xml
+
+ <trigger id="1" enable="true">
+ <name>t_pstore</name>
+ <type>node</type>
+ <path>/sys/fs/pstore/console-ramoops-0</path>
+ </trigger>
+
+* ``name``:
+ The name of trigger. It's used by crash and info configuration module.
+* ``type`` and ``path``:
+ These two labels are used to get the content of trigger files.
+ ``Types`` have been implemented:
+
+ + ``node``:
+ ``Path`` cannot support ``mmap(2)-like`` operations. ``Acrnprobe`` can
+ only use ``read(2)`` to get its content.
+ + ``file``:
+ ``Path`` is a regular file which supports ``mmap(2)-like`` operations.
+ + ``dir``:
+ ``Path`` is a directory.
+ + ``rebootreason``:
+ The reboot reason of system. The content of ``rebootreason`` is not
+ obtained in a common way. So, it doesn't work with ``path``.
+ + ``cmd``:
+ ``Path`` is a command which will be launched by ``execvp(3)``.
+
+ Some programs often use format ``string%d`` instead of static file
+ name to generate target file dynamically. So ``path`` supports simple
+ formats for these cases:
+
+ + /.../dir/string[*] --> all files with prefix "string" under dir.
+ + /.../dir/string[0] --> the first file of files, sorted by ``alphasort(3)``,
+ with prefix "string" under dir.
+ + /.../dir/string[-1] --> the last file of files, sorted by ``alphasort(3)``,
+ with prefix "string" under dir.
+
+Vm
+==
+
+Example:
+
+.. code-block:: xml
+
+ <vm id="1" enable="true">
+ <name>VM1</name>
+ <channel>polling</channel>
+ <interval>60</interval>
+ <syncevent id="1">CRASH/TOMBSTONE</syncevent>
+ <syncevent id="2">CRASH/UIWDT</syncevent>
+ <syncevent id="3">CRASH/IPANIC</syncevent>
+ <syncevent id="4">REBOOT</syncevent>
+ </vm>
+
+* ``name``:
+ The name of virtual machine.
+* ``channel``:
+ The ``channel`` name to get the virtual machine events.
+* ``interval``:
+ Time interval in seconds of polling vm's image.
+* ``syncevent``:
+ Event type ``acrnprobe`` will synchronize from virtual machine's
``crashlog``.
+ User could specify different types by id. The event type can also be
+ indicated by ``type/subtype``.
+
+Log
+===
+
+Example:
+
+.. code-block:: xml
+
+ <log id="1" enable="true">
+ <name>pstore</name>
+ <type>node</type>
+ <path>/sys/fs/pstore/console-ramoops-0</path>
+ </log>
+
+* ``name``:
+ By default, ``acrnprobe`` will take this ``name`` as generated log's
+name in
+ ``outdir`` of sender crashlog.
+ If ``path`` is specified by simple formats (includes [*], [0] or
+[-1]) the
+ file name of generated logs will be the same as original. More
+details about
+ simple formats, see `Trigger`_.
+* ``type`` and ``path``:
+ Same as `Trigger`_.
+* ``lines``:
+ By default, all contents in the original will be copied to generated log.
+ If this label is configured, only the ``lines`` at the end in the
+original
+ will be copied to the generated log. It takes effect only when the
+``type`` is
+ ``file``.
+
+Crash
+=====
+
+Example:
+
+.. code-block:: xml
+
+ <crash id='1' inherit='0' enable='true'>
+ <name>UNKNOWN</name>
+ <trigger>t_rebootreason</trigger>
+ <channel>oneshot</channel>
+ <content id='1'>WARM</content>
+ <log id='1'>pstore</log>
+ <log id='2'>acrnlog_last</log>
+ </crash>
+ <crash id='2' inherit='1' enable='true'>
+ <name>IPANIC</name>
+ <trigger>t_pstore</trigger>
+ <content id='1'> </content>
+ <mightcontent expression='1' id='1'>Kernel panic - not
syncing:</mightcontent>
+ <mightcontent expression='1' id='2'>BUG: unable to handle
kernel</mightcontent>
+ <data id='1'>kernel BUG at</data>
+ <data id='2'>EIP is at</data>
+ <data id='3'>Comm:</data>
+ </crash>
+
+* ``name``:
+ The type of the ``crash``.
+* ``trigger``:
+ The trigger name of the crash.
+* ``channel``:
+ The name of channel crash use.
+* ``content`` and ``mightcontent``:
+ They're used to match crash type. The match is successful if all the
+ following conditions are met:
+
+ a. All ``contents`` with different ``ids`` are included in trigger's
+ content.
+ b. One of ``mightcontents`` with the same ``expression`` is included in
+ trigger's content at least.
+ c. If there are ``mightcontents`` with different ``expressions``, each group
+ with the same ``expression`` should meet condition b.
+* ``log``:
+ The log to be collected. The value is the configured ``name`` in log module.
+ User could specify different logs by ``id``.
+* ``data``:
+ It is used to generated ``DATA`` fields in ``crashfile``.
+``Acrnprobe`` will
+ copy the line which starts with configured ``data`` in trigger's
+content
+ to ``DATA`` fields. There are 3 fields in ``crashfile`` and they
+could be
+ specified by ``id`` 1, 2, 3.
+
+Info
+=====
+
+Example:
+
+.. code-block:: xml
+
+ <info id='1' enable='true'>
+ <name>BOOT_LOGS</name>
+ <trigger>t_boot</trigger>
+ <channel>oneshot</channel>
+ <log id='1'>kmsg</log>
+ <log id='2'>cmdline</log>
+ <log id='3'>acrnlog_cur</log>
+ <log id='4'>acrnlog_last</log>
+ </info>
+
+* ``name``:
+ The type of info.
+* ``trigger``:
+ The trigger name of the info.
+* ``channel``:
+ The name of channel info use.
+* ``log``:
+ The log to be collected. The value is the configured name in log
+module. User
+ could specify different logs by id.
+
+.. _`XML standard`: http://www.w3.org/TR/REC-xml
--
2.7.4