diff --git a/tools/acrn-crashlog/acrnprobe/README.rst b/tools/acrn-crashlog/acrnprobe/README.rst index fa137f390..4e4f9ecfb 100644 --- a/tools/acrn-crashlog/acrnprobe/README.rst +++ b/tools/acrn-crashlog/acrnprobe/README.rst @@ -39,8 +39,8 @@ To see the version of ``acrnprobe``. Architecture ************ -Syntax -====== +Terms +===== - channel : Channel represents a way of detecting the system's events. There are 3 @@ -50,6 +50,19 @@ Syntax + polling: run a detecting job with fixed time interval. + inotify: monitor the change of file or dir. +- trigger : + Essentially, trigger represents one section of content. It could be + a file's content, a directory's content, or a memory's content which can be + obtained. By monitoring it ``acrnprobe`` could detect certain events which + happened in the system. + +- crash : + A subtype of event. It often corresponds to a crash of programs, system, or + hypervisor. ``acrnprobe`` detects it and reports it as ``CRASH``. + +- info : + A subtype of event. ``acrnprobe`` detects it and reports it as ``INFO``. + - event queue : There is a global queue to receive all events detected. Generally, events are enqueued in channel, and dequeued in event handler. @@ -136,15 +149,15 @@ Source files - main.c Entry of ``acrnprobe``. - channel.c - The implementation of *channel* (see `Syntax`_). + The implementation of *channel* (see `Terms`_). - crash_reclassify.c Analyzing the detailed types for crash event. - probeutils.c Provide some utils ``acrnprobe`` needs. - event_queue.c - The implementation of *event queue* (see `Syntax`_). + The implementation of *event queue* (see `Terms`_). - event_handler.c - The implementation of *event handler* (see `Syntax`_). + The implementation of *event handler* (see `Terms`_). - history.c There is a history_event file to manage all logs that ``acrnprobe`` archived. "history.c" provides the interfaces to modify the file in fixed format. @@ -154,7 +167,7 @@ Source files The ``acrnprobe`` needs to know some HW/SW properties, such as board version, build version. These properties are managed centrally in this file. - sender.c - The implementation of *sender* (see `Syntax`_). + The implementation of *sender* (see `Terms`_). - startupreason.c This file provides the function to get system reboot reason from kernel command line. @@ -175,4 +188,6 @@ Configuration files Custom configuration file that ``acrnprobe`` reads. +For 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 000000000..78c1df49f --- /dev/null +++ b/tools/acrn-crashlog/acrnprobe/conf.rst @@ -0,0 +1,416 @@ +.. _acrnprobe-conf: + +acrnprobe Configuration +####################### + +Description +*********** +``acrnprobe`` uses XML as the format of its configuration file, namely +``acrnprobe.xml``, following the `XML standard`_. + +Layout +****** + +.. code-block:: xml + + + + Root node of configuration. + + + Configuration section of senders. + Configuration of sender 1 + Configuration of sender 2 + + + + Configuration section of triggers. + Configuration of trigger 1 + Configuration of trigger 2 + + + + Configuration section of virtual machines. + Configuration of vm 1 + Configuration of vm 2 + + + + Configuration section of logs. + Configuration of log 1 + Configuration of log 2 + + + + Configuration section of crashes. + Note that this section must be configured after triggers and logs, as + crashes depend on these two sections. + Configuration of crash 1 + Configuration of crash 2 + + + + Configuration section of infos. + Note that this section must be configured after triggers and logs, as + infos depend on these two sections. + Configuration of info 1 + Configuration of info 2 + + + + +As for the definition of ``sender``, ``trigger``, ``crash`` and ``info`` +please refer to :ref:`acrnprobe_doc`. + +Properties of group members +*************************** + +``acrnprobe`` defined different groups in configuration file, which are +``senders``, ``triggers``, ``crashes`` and ``infos``. + +Common properties +================= + +- ``id``: + The index, which grows from 1 consecutively, in its group. +- ``enable``: + This group member will be ignored if the value is NOT ``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" ]; + } + +Match crash at runtime +====================== + +In order to find a more specific type, if one crash type matches +successfully ``acrnprobe`` will do a match for each child of it (if it has any) +continually, and return the last successful one. +About how to determine a match is successful, please refer to the ``content`` of +`Crash`_. + +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 + + + crashlog + /var/log/crashlog + 1000 + 5000 + 90 + + UPTIME + 5 + 6 + + + +* ``name``: + Name of sender. ``acrnprobe`` uses this label to distinguish different + senders. + For 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 be + reset to 0 if it reaches the specified maximum (``maxcrashdirs``). + Only used by sender crashlog. +* ``maxlines``: + If the number of lines in the ``history_event`` file reaches the specified + ``maxlines``, the ``history_event`` file will be renamed to + ``history_event.bak`` and logging will continue with a now empty + ``history_event`` file. +* ``spacequota``: + ``acrnprobe`` will stop collecting logs if + ``(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 + + + t_pstore + node + /sys/fs/pstore/console-ramoops-0 + + + t_acrnlog_last + file + /tmp/acrnlog/acrnlog_last.[*] + + +* ``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. + ``type`` have been implemented: + + + ``node``: + It means that ``path`` is a device node on virtual file system, which cannot + support ``mmap(2)-like`` operations. ``acrnprobe`` can use only ``read(2)`` + to get its content. + + ``file``: + It means that ``path`` is a regular file which supports ``mmap(2)-like`` + operations. + + ``dir``: + It means that ``path`` is a directory. + + ``rebootreason``: + It means that the trigger's content is the reboot reason of system. The + content of ``rebootreason`` is not obtained in a common way. So, it doesn't + work with ``path``. + + ``cmd``: + It means that ``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. + + Example of formats: + If there are 4 files under ``/tmp``: + ``acrnlog_last.1`` ``acrnlog_last.2`` ``acrnlog_last.3`` ``other.txt`` + + + ``/tmp/acrnlog_last.[-1]`` indicates ``acrnlog_last.3``. + + ``/tmp/acrnlog_last.[0]`` indicates ``acrnlog_last.1``. + + ``/tmp/acrnlog_last.[*]`` indicates the file set including + ``acrnlog_last.1``, ``acrnlog_last.2`` and ``acrnlog_last.3``. + + +Vm +== + +Example: + +.. code-block:: xml + + + VM1 + polling + 60 + CRASH/TOMBSTONE + CRASH/UIWDT + CRASH/IPANIC + REBOOT + + +* ``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 + + + pstore + node + /sys/fs/pstore/console-ramoops-0 + + +* ``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 + + + UNKNOWN + t_rebootreason + oneshot + WARM + pstore + acrnlog_last + + + IPANIC + t_pstore + + Kernel panic - not syncing: + BUG: unable to handle kernel + kernel BUG at + EIP is at + Comm: + + +* ``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 generate ``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 + + + BOOT_LOGS + t_boot + oneshot + kmsg + cmdline + acrnlog_cur + acrnlog_last + + +* ``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