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