1.. _acrnprobe_doc:
2
3Acrnprobe
4#########
5
6Description
7***********
8
9The ``acrnprobe`` is a tool to detect all critical events on the platform and
10collect specific information for them. The collected information would be saved
11as logs. The log path would be delivered to `telemetrics-client`_ as a record if
12telemetrics-client exists on the system. In this case ``acrnprobe`` works as a
13*probe* of telemetrics-client. If telemetrics-client doesn't exist on the
14system, ``acrnprobe`` provides ``history_event`` (under ``/var/log/crashlog/``
15by default) to manage the crash and events records on the platform instead of
16``telem_journal``. But in this case, the records can't be delivered to the
17backend.
18
19Usage
20*****
21
22The ``acrnprobe`` is launched as a service at boot. Also, it provides some basic
23options:
24
25Specify a configuration file for ``acrnprobe``. If this option is unused,
26``acrnprobe`` will use the configuration file located in CUSTOM CONFIGURATION
27PATH or INSTALLATION PATH (see `CONFIGURATION FILES`_).
28
29.. code-block:: none
30
31   $ acrnprobe -c [configuration_path]
32
33To see the version of ``acrnprobe``.
34
35.. code-block:: none
36
37   $ acrnprobe -V
38
39Architecture
40************
41
42Terms
43=====
44
45channel
46  Channel represents a way of detecting the system's events. There are 3
47  channels:
48
49  + oneshot: detect once while ``acrnprobe`` startup.
50  + polling: run a detecting job with fixed time interval.
51  + inotify: monitor the change of file or dir.
52
53trigger
54  Essentially, trigger represents one section of content. It could be
55  a file's content, a directory's content, or a memory's content, which can be
56  obtained. By monitoring it, ``acrnprobe`` could detect certain events
57  that happened in the system.
58
59crash
60  A subtype of event. It often corresponds to a crash of programs, system, or
61  hypervisor. ``acrnprobe`` detects it and reports it as ``CRASH``.
62
63info
64  A subtype of event. ``acrnprobe`` detects it and reports it as ``INFO``.
65
66event queue
67  There is a global queue to receive all events detected.
68  Generally, events are enqueued in channel, and dequeued in event handler.
69
70event handler
71  Event handler is a thread to handle events detected by channel.
72  It's awakened by an enqueued event.
73
74sender
75  The sender corresponds to an exit of event.
76  There are two senders:
77
78  + ``crashlog`` is responsible for collecting logs and saving it locally.
79  + ``telemd`` is responsible for sending log records to telemetrics client.
80
81Description
82===========
83
84As a log collection mechanism to record critical events on the platform,
85``acrnprobe`` provides these functions:
86
871. detect event
88
89   From experience, the occurrence of a system event is usually accompanied
90   by some effects. The effects could be a generated file, an error message in
91   kernel's log, or a system reboot. To get these effects, for some of them we
92   can monitor a directory, for others, we might need to do detection
93   in a time loop.
94   So we implement the channel, which represents a common method of detection.
95
962. analyze event and determine the event type
97
98   Generally, a specific effect corresponds to a particular type of events.
99   However, it is the icing on the cake for analyzing the detailed event types
100   according to some phenomena. Crash reclassifying is implemented for this
101   purpose.
102
1033. collect information for detected events
104
105   This is for debug purpose. Events without information are meaningless,
106   and developers need to use this information to improve their system. Sender
107   ``crashlog`` is implemented for this purpose.
108
1094. archive these information as logs, and generate records
110
111   There must be a central place to tell user what happened in system.
112   Sender ``telemd`` is implemented for this purpose.
113
114Diagram
115=======
116::
117
118 +---------------------------------------------+
119 | channel:   |oneshot|  |polling|   |inotify| |
120 +--------------------------------------+------+
121                                        |
122 +---------------------+    +-----+     |
123 | event queue         +<---+event+<----+
124 +-+-------------------+    +-----+
125   |
126   v
127 +-+---------------------------------------------------------------------------+
128 |  event handler:                                                             |
129 |                                                                             |
130 |  event handler will handle internal event                                   |
131 |    +----------+    +------------+                                           |
132 |    |heart beat+--->+fed watchdog|                                           |
133 |    +----------+    +------------+                                           |
134 |                                                                             |
135 |  call sender for other types                                                |
136 |    +--------+   +----------------+   +------------+   +------------------+  |
137 |    |crashlog+-->+crash reclassify+-->+collect logs+-->+generate crashfile|  |
138 |    +--------+   +----------------+   +------------+   +------------------+  |
139 |                                                                             |
140 |    +------+    +------------------+                                         |
141 |    |telemd+--->+telemetrics client|                                         |
142 |    +------+    +------------------+                                         |
143 +-----------------------------------------------------------------------------+
144
145
146Source Files
147************
148
149- main.c
150  Entry of ``acrnprobe``.
151- channel.c
152  The implementation of *channel* (see `Terms`_).
153- crash_reclassify.c
154  Analyzing the detailed types for crash event.
155- probeutils.c
156  Provide some utils ``acrnprobe`` needs.
157- event_queue.c
158  The implementation of *event queue* (see `Terms`_).
159- event_handler.c
160  The implementation of *event handler* (see `Terms`_).
161- history.c
162  There is a history_event file to manage all logs that ``acrnprobe`` archived.
163  "history.c" provides the interfaces to modify the file in fixed format.
164- load_conf.c
165  Parse and load the configuration file.
166- property.c
167  The ``acrnprobe`` needs to know some HW/SW properties, such as board version,
168  build version. These properties are managed centrally in this file.
169- sender.c
170  The implementation of *sender* (see `Terms`_).
171- startupreason.c
172  This file provides the function to get system reboot reason from kernel
173  command line.
174- android_events.c
175  Sync events detected by Android ``crashlog``.
176- loop.c
177  This file provides interfaces to read from image.
178
179Configuration Files
180*******************
181
182* ``/usr/share/defaults/telemetrics/acrnprobe.xml``
183
184  If no custom configuration file is found, ``acrnprobe`` uses the settings in
185  this file.
186
187* ``/etc/acrnprobe.xml``
188
189  Custom configuration file that ``acrnprobe`` reads.
190
191For details about configuration file, please refer to :ref:`acrnprobe-conf`.
192
193.. _`telemetrics-client`: https://github.com/clearlinux/telemetrics-client
194