1ACRN-Crashlog
2#############
3
4Introduction
5************
6
7``ACRN-Crashlog`` is a collective name for various tools (``acrnprobe``,
8``usercrash_s``, ``usercrash_c``, ``debugger``, and more) and an overall
9control utility called ``crashlogctl``. Together these tools collect logs
10and information after each crash or event on an ACRN platform, including
11the hypervisor, Service VM, and Android as a Guest (AaaG).
12``ACRN-Crashlog`` provides a flexible way to configure which events are
13of interest, by using an XML configuration file.
14
15Building
16********
17
18Build Dependencies
19==================
20
21The ``ACRN-Crashlog`` tool depends on the following libraries
22(build and runtime):
23
24- libevent
25- OpenSSL
26- libxml2
27- systemd
28- libblkid
29- e2fsprogs
30
31Refer to the :ref:`getting_started` for instructions on how to set up your
32build environment, and follow the instructions below to build and configure the
33``ACRN-Crashlog`` tool.
34
35Build
36=====
37
38To build the ``ACRN-Crashlog``, run:
39
40.. code-block:: none
41
42   cd misc/debug_tools/acrn_crashlog
43   make
44
45To remove all generated files and return the folder to its clean state,
46use:
47
48.. code-block:: none
49
50   cd misc/debug_tools/acrn_crashlog
51   make clean
52
53Installing
54**********
55
56To install the build:
57
58.. code-block:: none
59
60   cd misc/debug_tools/acrn_crashlog
61   sudo make install
62
63Enabling/Disabling
64******************
65
66To enable this tool:
67
68.. code-block:: none
69
70   sudo crashlogctl enable
71
72Then it will show:
73
74.. code-block:: console
75
76   ... Backup core pattern to /var/log/crashlog/default_core_pattern
77   '/usr/share/acrn/crashlog/40-watchdog.conf' ->
78   '/etc/systemd/system.conf.d/40-watchdog.conf'
79   '/usr/share/acrn/crashlog/80-coredump.conf' ->
80   '/etc/sysctl.d/80-coredump.conf'
81   Created symlink /etc/systemd/system/multi-user.target.wants/acrnprobe.service -> /usr/lib/systemd/system/acrnprobe.service.
82   Created symlink /etc/systemd/system/multi-user.target.wants/usercrash.service -> /usr/lib/systemd/system/usercrash.service.
83   *** Please reboot your system. ***
84
85Follow the hints to reboot the system:
86
87.. code-block:: none
88
89   sudo reboot
90
91To disable this tool:
92
93.. code-block:: none
94
95   sudo crashlogctl disable
96
97Then it will show:
98
99.. code-block:: console
100
101   Removed /etc/systemd/system/multi-user.target.wants/acrnprobe.service.
102   Removed /etc/systemd/system/multi-user.target.wants/usercrash.service.
103   removed '/etc/sysctl.d/80-coredump.conf'
104   removed '/etc/systemd/system.conf.d/40-watchdog.conf'
105   *** Please reboot your system. ***
106
107Follow the hints to reboot the system:
108
109.. code-block:: none
110
111   sudo reboot
112
113To check the status of this tool:
114
115.. code-block:: none
116
117   sudo crashlogctl is-active
118
119It will show the status of the related services. Example:
120
121.. code-block:: console
122
123   acrnprobe  : inactive
124   usercrash  : inactive
125
126Usage
127*****
128
129The ``acrnprobe`` tool provides ``history_event`` (under
130``/var/log/crashlog/history_event``) to record ACRN-related events and
131crash information.
132
133``ACRN-Crashlog`` also provides a tool called ``debugger`` to dump specific
134process information:
135
136.. code-block:: none
137
138   sudo debugger 12
139
140Replace ``12`` with the process ID you want to dump.
141
142.. note::
143
144   You need to be ``root`` to use the ``debugger``.
145
146Source Code
147***********
148
149The source code structure:
150
151.. code-block:: none
152
153   acrn-crashlog/
154   ├── acrnprobe
155   │   └── include
156   ├── common
157   │   └── include
158   ├── data
159   └── usercrash
160       └── include
161
162- ``acrnprobe``: tool that gathers all the crash and event logs on the
163  platform. For the hypervisor, the log is collected with ``acrnlog``. For the
164  Service VM, the userspace crash log is collected with ``usercrash``, and the
165  kernel crash log is collected with the inherent mechanism, such as ``ipanic``
166  or ``pstore``. For an AaaG VM, the log is collected by monitoring the change
167  of related folders on the Service VM image, such as ``/data/logs/``.
168  ``acrnprobe`` also provides a flexible way to configure which crash or event
169  to collect, by using an XML configuration file.
170- ``common``: some utils for logs, command and string.
171- ``data``: configuration file, service files and shell script.
172- ``usercrash``: tool that gets the crash information for the
173  crashing process in userspace.
174
175Acrnprobe
176=========
177
178The ``acrnprobe`` tool detects all critical events on the platform and collects
179specific information for debug purposes. The information is saved as
180logs.
181For more details on ``acrnprobe``, see :ref:`acrnprobe_doc`.
182
183Usercrash
184=========
185
186The ``usercrash`` tool gets the crash information of the crashing process in
187userspace. It works in a client/server model. The server is autostarted, and
188the client is
189configured in ``core_pattern`` or ``coredump-wrapper``, which will be
190triggered once a crash occurs in userspace.
191For more details on ``usercrash``, see :ref:`usercrash_doc`.
192