README.rst
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