.. _acrnprobe_doc: Acrnprobe ######### Description *********** The ``acrnprobe`` is a tool to detect all critical events on the platform and collect specific information for them. The collected information would be saved as logs. The log path would be delivered to `telemetrics-client`_ as a record if telemetrics-client exists on the system. In this case ``acrnprobe`` works as a *probe* of telemetrics-client. If telemetrics-client doesn't exist on the system, ``acrnprobe`` provides ``history_event`` (under ``/var/log/crashlog/`` by default) to manage the crash and events records on the platform instead of ``telem_journal``. But in this case, the records can't be delivered to the backend. Usage ***** The ``acrnprobe`` is launched as a service at boot. Also, it provides some basic options: Specify a configuration file for ``acrnprobe``. If this option is unused, ``acrnprobe`` will use the configuration file located in CUSTOM CONFIGURATION PATH or INSTALLATION PATH (see `CONFIGURATION FILES`_). .. code-block:: none $ acrnprobe -c [configuration_path] To see the version of ``acrnprobe``. .. code-block:: none $ acrnprobe -V Architecture ************ Terms ===== channel Channel represents a way of detecting the system's events. There are 3 channels: + oneshot: detect once while ``acrnprobe`` startup. + 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 that 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. event handler Event handler is a thread to handle events detected by channel. It's awakened by an enqueued event. sender The sender corresponds to an exit of event. There are two senders: + ``crashlog`` is responsible for collecting logs and saving it locally. + ``telemd`` is responsible for sending log records to telemetrics client. Description =========== As a log collection mechanism to record critical events on the platform, ``acrnprobe`` provides these functions: 1. detect event From experience, the occurrence of a system event is usually accompanied by some effects. The effects could be a generated file, an error message in kernel's log, or a system reboot. To get these effects, for some of them we can monitor a directory, for others, we might need to do detection in a time loop. So we implement the channel, which represents a common method of detection. 2. analyze event and determine the event type Generally, a specific effect corresponds to a particular type of events. However, it is the icing on the cake for analyzing the detailed event types according to some phenomena. Crash reclassifying is implemented for this purpose. 3. collect information for detected events This is for debug purpose. Events without information are meaningless, and developers need to use this information to improve their system. Sender ``crashlog`` is implemented for this purpose. 4. archive these information as logs, and generate records There must be a central place to tell user what happened in system. Sender ``telemd`` is implemented for this purpose. Diagram ======= :: +---------------------------------------------+ | channel: |oneshot| |polling| |inotify| | +--------------------------------------+------+ | +---------------------+ +-----+ | | event queue +<---+event+<----+ +-+-------------------+ +-----+ | v +-+---------------------------------------------------------------------------+ | event handler: | | | | event handler will handle internal event | | +----------+ +------------+ | | |heart beat+--->+fed watchdog| | | +----------+ +------------+ | | | | call sender for other types | | +--------+ +----------------+ +------------+ +------------------+ | | |crashlog+-->+crash reclassify+-->+collect logs+-->+generate crashfile| | | +--------+ +----------------+ +------------+ +------------------+ | | | | +------+ +------------------+ | | |telemd+--->+telemetrics client| | | +------+ +------------------+ | +-----------------------------------------------------------------------------+ Source Files ************ - main.c Entry of ``acrnprobe``. - channel.c 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 `Terms`_). - event_handler.c 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. - load_conf.c Parse and load the configuration file. - property.c 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 `Terms`_). - startupreason.c This file provides the function to get system reboot reason from kernel command line. - android_events.c Sync events detected by Android ``crashlog``. - loop.c This file provides interfaces to read from image. Configuration Files ******************* * ``/usr/share/defaults/telemetrics/acrnprobe.xml`` If no custom configuration file is found, ``acrnprobe`` uses the settings in this file. * ``/etc/acrnprobe.xml`` 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